In an OSV record, aliases mean the same vulnerability in another database, upstream means the vulnerabilities a downstream advisory bundles, and related means something connected but not identical. Join on aliases to merge duplicates, follow upstream to find the root cause, and never merge on related.
Why three fields exist
A single flaw often shows up in several places. A language ecosystem publishes an advisory, a CVE gets assigned, and a Linux distribution ships a patched package with its own advisory. If a tool counts each as a separate finding, the report triples. If a tool merges too eagerly, it hides real differences. The OSV schema uses three fields so a producer can say precisely how two records relate.
The three fields side by side
| Field | Meaning | Symmetric | Transitive |
|---|---|---|---|
| aliases | Same vulnerability, different database | Yes | Yes |
| upstream | Upstream vulnerabilities this record refers to | No, direction matters | Yes |
| related | Closely related, not the same | Yes | No |
The schema text defines aliases tightly. Two entries are aliases only if a patch for one addresses both and nothing else. If A aliases B and B aliases C, then A aliases C.
The rule that trips up scanners
The schema says aliases must not point up or down the supply chain. Its example: a CVE describes a flaw in a language library, and a Linux distribution package contains that library and publishes its own advisory. The distribution record must not list the CVE as an alias. It uses upstream instead.
The reason is practical. A distribution advisory can bundle several upstream fixes in one record. Calling it an alias of one CVE would be wrong, because patching the distribution package addresses more than that CVE.
For related, the schema gives two typical uses: a similar but different vulnerability, and cases that do not meet the strict definitions of aliases or upstream.
How to build a dedupe step
- Load all records for your component and version.
- Build groups by following aliases in both directions until no new IDs appear. Because aliases are symmetric and transitive, this is a connected components pass.
- Pick a display ID for each group. Many teams prefer a CVE where one exists.
- For each group, keep the record with the latest modified timestamp as the authority for details. The schema says that when two entries claim the same id, the later modification time is authoritative.
- Attach upstream IDs as extra context, not as group members.
- Show related IDs as links only.
Common mistakes
Merging on related inflates your suppression list and can hide a second, different flaw. Merging across upstream hides the fact that a distribution fix covers several issues. Ignoring withdrawn records leaves ghosts in your group. A withdrawn field means the record was retracted.
Try it yourself
Click through it at your own pace, or open it full screen. Notice how one underlying issue is shown once, however many databases describe it.
Where this fits
Good dedupe is what keeps a findings list honest. Related reading: CVE, GHSA and OSV IDs compared. Safeguard offers SBOM and dependency scanning, and the free scan shows findings grouped for a real project.
Quick check
Can I treat a distribution advisory as an alias of an upstream CVE?
No. The schema says distribution records should use upstream for that, because one distribution advisory may cover several upstream issues.
Is related safe to use for merging records?
No. Related is symmetric but not transitive and covers cases that fall short of aliases or upstream. Use it for links only.
Sources
Last reviewed: 19 October 2026.
