From d810d7035116855ef5e67218d2570d8dab1447de Mon Sep 17 00:00:00 2001
From: Chris Bloom <chrisbloom7@github.com>
Date: Fri, 17 Dec 2021 11:18:03 -0500
Subject: [PATCH] add schema_version and define how to use it (#17)

* Add a schema_version field

* Use SemVer instead of SchemaVer for schema_version format

* Updating docs with suggested changes to schema_version field

* Bump schema version to 1.1.0
---
 docs/schema.md         | 22 +++++++++++++++++++++-
 validation/schema.json |  3 +++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/docs/schema.md b/docs/schema.md
index 04e0391..0ffb60f 100644
--- a/docs/schema.md
+++ b/docs/schema.md
@@ -8,7 +8,7 @@ aside:
 show_edit_on_github: true
 ---
 
-**Version 1.0 (September 8, 2021)**
+**Version 1.1.0 (December 15, 2021)**
 
 Original authors:
 - Oliver Chang (ochang@google.com)
@@ -56,6 +56,7 @@ A JSON Schema for validation is also available
 
 ```json
 {
+	"schema_version": string,
 	"id": string,
 	"modified": string,
 	"published": string,
@@ -104,6 +105,25 @@ absolutely must be shared between databases, leaving customizations to the
 
 # Field Details
 
+## schema_version field
+
+```json
+{
+	"schema_version": string
+}
+```
+
+The `schema_version` field is used to indicate which version of the OSV schema
+a particular vulnerability was exported with. This can help consumer applications
+decide how to import the data for their own systems and offer some protection
+against future breaking changes. The value should be a string matching the OSV
+Schema version, which follows the [SemVer 2.0.0](https://semver.org) format, with
+no leading "v" prefix. If no value is specified, it should be assumed to be `1.0.0`,
+matching version 1.0 of the OSV Schema. Clients can assume that new minor and patch
+versions of the schema only add new fields, without changing the meaning of old
+fields, so that a client that knows how to read version 1.2.0 can process data
+identifying as schema version 1.3.0 by ignoring any unexpected fields.
+
 ## id, modified fields
 
 ```json
diff --git a/validation/schema.json b/validation/schema.json
index 328c556..a1e1b3d 100644
--- a/validation/schema.json
+++ b/validation/schema.json
@@ -4,6 +4,9 @@
   "description": "A schema for describing a vulnerability in an open source package.",
   "type": "object",
   "properties": {
+    "schema_version": {
+      "type": "string"
+    },
     "id": {
       "type": "string"
     },