Schema

- addresses parts of oasis-tcs#616 - adopt prose to match schema - add additional sections - update profiles and guidance on size
tschmidtb51 · Jun 24, 2024 · 9b16fd2 · 9b16fd2
1 parent b96e201
commit 9b16fd2
Show file tree

Hide file tree

Showing 7 changed files with 21 additions and 3 deletions.
diff --git a/csaf_2.1/prose/edit/src/guidance-on-size.md b/csaf_2.1/prose/edit/src/guidance-on-size.md
@@ -282,7 +282,13 @@ A string which is an enum has a fixed maximum length given by its longest value.
 > Later versions of CSAF might add, modify or delete possible value which could change the longest value.
 > Therefore, this sizes should not be implemented as fixed limits if forward compatibility is desired.
 
-It seems to be safe to assume that the length of each value is not greater than 50. This applies to:
+The value of `/$schema` is a fixed URL, currently pointing to the JSON schema location.
+It seems to be safe to assume that the length of this value is not greater than 5. This applies to:
+
+* `/$schema` (64)
+
+For all other values, it seems to be safe to assume that the length of each value is not greater than 50.
+This applies to:
 
 * `/document/csaf_version` (3)
 * `/document/distribution/tlp/label` (12)

diff --git a/csaf_2.1/prose/edit/src/profiles.md b/csaf_2.1/prose/edit/src/profiles.md
@@ -27,6 +27,7 @@ Furthermore, it is the foundation all other profiles are build on.
 A CSAF document SHALL fulfill the following requirements to satisfy the profile "CSAF Base":
 
 * The following elements MUST exist and be valid:
+  * `/$schema`
   * `/document/category`
   * `/document/csaf_version`
   * `/document/distribution/tlp/label`

diff --git a/csaf_2.1/prose/edit/src/schema-elements-02-properties.md b/csaf_2.1/prose/edit/src/schema-elements-02-properties.md
@@ -1,4 +1,4 @@
 ## Properties
 
-These final three subsections document the three properties of a CSAF document.
-The single mandatory property `document`, as well as the optional properties `product_tree` and `vulnerabilities` in that order.
+These final four subsections document the four properties of a CSAF document.
+The two mandatory properties `$schema` and `document`, as well as the optional properties `product_tree` and `vulnerabilities` in that order.
diff --git a/csaf_2.1/prose/edit/src/schema-elements-02-props-01-$schema.md b/csaf_2.1/prose/edit/src/schema-elements-02-props-01-$schema.md
@@ -0,0 +1,11 @@
+### Schema Property
+
+JSON schema (`$schema`) of value type `string` and `enum` with format `uri` contains the URL of the CSAF JSON schema which the document promises to be valid for.
+The single valid value for this `enum` is:
+
+```
+  https://docs.oasis-open.org/csaf/csaf/v2.1/csaf_json_schema.json
+```
+
+> This value allows for tools to identify that a JSON document is meant to be valid against this schema.
+> Tools can use that to support users by automatically checking whether the CSAF adheres to the JSON schema identified by this URL.
diff --git a/...c/schema-elements-02-props-01-document.md → ...c/schema-elements-02-props-02-document.md b/...c/schema-elements-02-props-01-document.md → ...c/schema-elements-02-props-02-document.md
diff --git a/...hema-elements-02-props-02-product-tree.md → ...hema-elements-02-props-03-product-tree.md b/...hema-elements-02-props-02-product-tree.md → ...hema-elements-02-props-03-product-tree.md
diff --git a/...a-elements-02-props-03-vulnerabilities.md → ...a-elements-02-props-04-vulnerabilities.md b/...a-elements-02-props-03-vulnerabilities.md → ...a-elements-02-props-04-vulnerabilities.md