Read database_specific and ecosystem_specific only if you handle that exact source and have its documentation. The OSV schema says their meaning is entirely defined by the database that wrote them. For a general parser, rely on the standard fields and ignore the rest without failing.
What the fields are
The OSV schema defines a common record: an ID, aliases, affected packages with ranges, references, severity and more. It also leaves two places for source-specific content:
- database_specific. A top-level object for information from the originating database. The schema says "The meaning of the values within the object is entirely defined by the database." An affected entry can also have its own database_specific object, with the same rule.
- ecosystem_specific. Inside each affected entry, for information defined by the ecosystem the record applies to. The schema says the canonical database for an ecosystem should record its data here.
Why this matters for data quality
Teams sometimes find a useful value in one record, such as a severity label or a note, and build logic on it. That works until a record from another source lacks it or uses it differently. The result is a scanner that behaves well on one ecosystem and oddly on another.
Our post on OSV severity fields shows how uneven rating data is across sources. Treat any source-specific field the same way: it is not a guaranteed part of the contract.
How the schema wants you to behave
The schema says minor and patch versions only add fields, so a client can read newer data by ignoring any unexpected fields. That is the rule for forward compatibility:
- Parse the fields you know.
- Ignore the fields you do not know.
- Never fail a whole import because of an unfamiliar key.
A decision table
| Question | If yes | If no |
|---|---|---|
| Do you only handle one source and read its docs? | You may use its specific fields, with tests | Ignore them |
| Is the value required for a correct match? | Use the standard affected ranges instead | Skip it |
| Is the field shown to users? | Show it with the source name | Do not show unlabelled |
| Does your logic differ per source? | Keep the source in a lookup table, and version it | Keep one code path |
Other rules from the schema worth knowing
- Withdrawn. The withdrawn field is a timestamp; if missing, the entry has not been withdrawn. The rationale belongs in the summary text. See what to do when an advisory is withdrawn.
- IDs. An ID has the form of a database prefix plus an entry ID, restricted to letters, numbers and a few characters. The schema says the prefix x_ marks a local database not aggregated by OSV.dev.
- Prefixes. GHSA, PYSEC, MAL, RUSTSEC, GO and OSV identify source databases.
What to test
Feed your parser three records: one with extra unknown keys, one with no severity, and one withdrawn. It should not crash, should not invent a severity, and should hide the withdrawn one.
Where Safeguard fits
Safeguard provides SBOM and dependency scanning and policies that can gate on severity and KEV status. If you build your own ingestion alongside, use the schema rules above. Try a free scan at gold.safeguard.sh/scan.
Quick check
Who defines what database_specific means?
The database that wrote the record. The schema says the meaning is entirely defined by that database.
What should a client do with fields it does not know?
Ignore them. The schema says newer minor versions only add fields.
Sources
- OSV schema specification, fetched 19 October 2026.
Last reviewed: 19 October 2026.
