What Is the OSV Schema and How Are Vulnerabilities Described?

The OSV schema is the OpenSSF data format that every advisory in the OSV database uses to describe a vulnerability. It is both human- and machine-readable, and its defining feature is that it maps a vulnerability precisely to open source package versions or commit hashes rather than to vague product names. If you are consuming OSV data through the API, writing a scanner, or publishing your own advisories, the schema is the contract you work against.

Why a dedicated schema exists

Traditional vulnerability identifiers such as CVEs describe products ("this library, versions before X"). That works for commercial software with clear version boundaries, but open source dependency trees are messier: the same package name can exist in several ecosystems, versions are often pinned by commit rather than release, and a fix may land on a branch without a version bump.

The OSV schema was developed in collaboration with open source communities to solve exactly that. It gives each advisory a structured record whose affected ranges can be expressed in the versioning scheme of the ecosystem it belongs to, or as explicit commit ranges.

The core fields

The OSV database's own example record shows the shape of an advisory:

{
  "schema_version": "1.7.4",
  "id": "GHSA-c3g4-w6cv-6v7h",
  "modified": "2022-04-01T13:56:42Z",
  "published": "2022-04-01T13:56:42Z",
  "aliases": ["CVE-2022-27651"],
  "summary": "Non-empty defaul..."
}

The aliases field is what lets you reconcile OSV records with CVE-based tooling: an OSV advisory and its CVE are the same underlying issue, linked rather than duplicated.

Precise version and commit mapping

The part of the schema that matters most for automation is the affected-package description. Rather than naming a product, an OSV record points at a package inside a named ecosystem and then gives the ranges where the vulnerability applies. Those ranges can be written as version constraints in that ecosystem's own versioning convention, or as commit ranges when the project does not cut releases for every fix.

This is why the OSV database can list ecosystems as different as npm, PyPI, Go, Maven, crates.io, Debian, Ubuntu, and Alpine side by side — each advisory speaks the versioning language of its own ecosystem instead of forcing everything into one product-version model.

What this means in practice

• For consumers: you can match a dependency against OSV data by ecosystem plus package name plus version, without guessing which product a CVE was filed under.
• For publishers: adopting the schema means your advisories are readable by any tool that already ingests OSV, and your IDs can be aliased to CVEs.
• For tooling: because the format is machine-readable, the same record drives a human-facing advisory page and an automated scanner.

The OSV database exposes this data through its API and a vulnerability scanner, so the schema is not just documentation — it is the format you actually receive when you query the service.