From 7be52eccfc0f8433ac39983a68c4d1e4fe4203e4 Mon Sep 17 00:00:00 2001
From: Oliver Chang <ochang@google.com>
Date: Sat, 16 Nov 2024 08:31:04 +1100
Subject: [PATCH] Add `upstream` field.

Fixes #249.

Signed-off-by: Oliver Chang <ochang@google.com>
---
 CHANGELOG.md   |  1 +
 docs/schema.md | 26 ++++++++++++++++++++++----
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a62114c..790dbb0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,3 +37,4 @@
   prefixes.
 - 2024-09-12 Released version 1.6.6. Add RHBA, RHEA, SUSE-OU prefixes.
 - 2024-09-16 Released version 1.6.7. JSON schema and minor text formatting changes.
+- 2024-TBD Released version 1.6.8. Add `upstream` field.
diff --git a/docs/schema.md b/docs/schema.md
index 705a59e..39662f0 100644
--- a/docs/schema.md
+++ b/docs/schema.md
@@ -51,6 +51,7 @@ A JSON Schema for validation is also available
 	"published": string,
 	"withdrawn": string,
 	"aliases": [ string ],
+	"upstream": [ string ],
 	"related": [ string ],
 	"summary": string,
 	"details": string,
@@ -518,7 +519,26 @@ package(s). For example, if a CVE describes a vulnerability in a language
 library, and a Linux distribution package contains that library and therefore
 publishes an advisory, the distribution's OSV record must not list the CVE ID as
 an alias. Similarly, distributions often bundle multiple upstream
-vulnerabilities into a single record. `related` should be used in these cases.
+vulnerabilities into a single record. `upstream` should be used in these cases.
+
+## upstream field
+
+```
+{
+  "upstream": [ string ]
+}
+```
+
+The `upstream` field gives a list of IDs of upstream vulnerabilities that are
+bundled by the vulnerability entry.
+
+For example, a downstream package ecosystem (such as a Linux distribution) may
+issue its own advisories that include (possibly multiple) upstream
+vulnerabilities.
+
+`upstream` should be considered transitive but not symmetric. For example, if B is
+an upstream vulnerability for A, and C is an upstream vulnerability for B, then
+C is also an upstream vulnerability for A.
 
 ## related field
 
@@ -531,9 +551,7 @@ vulnerabilities into a single record. `related` should be used in these cases.
 The `related` field gives a list of IDs of closely related vulnerabilities, such
 as:
 - A similar but completely different vulnerability.
-- A similar OSV entry that bundles multiple distinct vulnerabilities in the same
-entry.
-- Cases that do not satisfy the strict definition of `aliases`.
+- Cases that do not satisfy the strict definition of `aliases` or `upstream`.
 
 Related vulnerabilities are symmetric but not transitive.