How to Contribute

January 28, 2026 ยท View on GitHub

We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.

Code of Conduct

This is a project of the Open Source Security Foundation and follows its Code of Conduct.

Accepted Contributions

This repository is primarily for the OSV Schema definition(human-readable and JSON Schema), and related tooling.

See the guiding principles for background thinking behind the schema's design, and what is more and less likely to be acceptable in the way of changes.

For more substantial changes, we encourage you to open an issue for discussion and to also engage with the OpenSSF Vulnerability Working Group about the proposed change.

Code Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Adding a new ecosystem

To add a new ecosystem, follow these steps:

  1. ecosystems.json: Add an entry for the new ecosystem and it's description.

    • If your ecosystem has multiple separate release, please include how releases are specified.

  2. Database-specific prefix: Generally a new ecosystem will introduce a new database-specific ID prefix (e.g., GHSA for GitHub Security Advisories), please add it to:

    • The "Database-specific prefixes" table in docs/schema.md.
    • The prefix pattern within validation/schema.json.

  3. README.md: Add the new ecosystem to the list of data exporters in the README.

  4. Run update script: Finally, run python3 ./scripts/update-ecosystems-lists.py. This script will automatically update the following files based on your changes to ecosystems.json:

    • bindings/go/osvschema/constants.go
    • The main ecosystem table in docs/schema.md
    • The ecosystem enum in validation/schema.json
    • Make a copy of the validation/schema.json for the linter in tools/osv-linter/internal/checks/schema_generated.json

Development policies

Dependencies

Selection

Dependencies should be taken in an intentional manner, following the OpenSSF's Best Practices Guides and Concise Guides. Bias towards avoiding taking a new dependency where possible. Include your rationale for adding a new dependency in the pull request that adds it so reviewers may understand it, and the rationale is captured in the commit history.

To ease their ongoing management, dependencies must be obtained from relevant language-specific package registries and not vendored.

Tracking

Dependencies are tracked by their respective lock files.

Management

Dependencies are managed with standard dependency management tooling, such as Dependabot.