doc: annex: Validate documentation examples

Updates the security information Annex to conform to the SPDX 3.0 schema
and model. In addition, the CI workflow is updated to use a standalone
script to do the validation (making it easier to validate locally). When
validation documentation files, the script will now detect if the
documentation is a complete document or just fragements of a document.
In the latter case, a wrapper is made around the JSON from the
documentation to make it a valid document for validation (e.g.
"@context", "@graph", and a CreationInfo).

Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>

.github/workflows/validate_examples.yml

@@ -13,35 +13,7 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt install -y gawk
-      - name: Check files
-        run: |
-          set -e
-          for f in examples/jsonld/*.json; do
-            echo "Checking $f"
-
-            check-jsonschema \
-              -v \
-              --schemafile https://spdx.org/schema/3.0.0/spdx-json-schema.json \
-              $f
 
-            pyshacl \
-              -s https://spdx.org/rdf/3.0.0/spdx-model.ttl \
-              -e https://spdx.org/rdf/3.0.0/spdx-model.ttl \
-              $f
-          done
-
-      - name: Check documentation examples
+      - name: Check examples
         run: |
-          for f in docs/annexes/getting-started.md; do
-            echo "Checking $f"
-            cat $f | awk '/^```json/, $0=="```" {if ($0 !~ /^```.*/ ) print}' > temp.json
-            check-jsonschema \
-              -v \
-              --schemafile https://spdx.org/schema/3.0.0/spdx-json-schema.json \
-              temp.json
-
-            pyshacl \
-              -s https://spdx.org/rdf/3.0.0/spdx-model.ttl \
-              -e https://spdx.org/rdf/3.0.0/spdx-model.ttl \
-              temp.json
-          done
+          ./bin/check-examples.sh

bin/check-examples.sh

@@ -0,0 +1,76 @@
+#! /bin/bash
+#
+# Validates SPDX example, both in separate files and inline in the
+# documentation
+#
+# SPDX-License-Identifier: MIT
+
+set -e
+
+THIS_DIR=$(dirname $0)
+
+for f in examples/jsonld/*.json; do
+    echo "Checking $f"
+
+    check-jsonschema \
+        -v \
+        --schemafile https://spdx.org/schema/3.0.0/spdx-json-schema.json \
+        $f
+
+    pyshacl \
+        -s https://spdx.org/rdf/3.0.0/spdx-model.ttl \
+        -e https://spdx.org/rdf/3.0.0/spdx-model.ttl \
+        $f
+done
+
+T=$(mktemp -d)
+
+for f in $THIS_DIR/../docs/annexes/*.md; do
+    if ! grep -q '```json' $f; then
+        continue
+    fi
+    echo "Checking $f"
+    echo "" > $T/temp.json
+
+    if ! grep -q '@context' $f; then
+        cat >> $T/temp.json <<HEREDOC
+{
+    "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld",
+    "@graph": [
+HEREDOC
+    fi
+
+    cat $f | awk '/^```json/, $0=="```" {if ($0 !~ /^```.*/ ) print}' >> $T/temp.json
+
+    if ! grep -q '@context' $f; then
+        cat >> $T/temp.json <<HEREDOC
+        {
+            "type": "CreationInfo",
+            "@id": "_:creationInfo",
+            "specVersion": "3.0.0",
+            "created": "2024-04-23T00:00:00Z",
+            "createdBy": [
+                {
+                    "type": "Agent",
+                    "spdxId": "http://spdx.dev/dummy-agent",
+                    "creationInfo": "_:creationInfo"
+                }
+            ]
+        }
+    ]
+}
+HEREDOC
+    fi
+
+    check-jsonschema \
+        -v \
+        --schemafile https://spdx.org/schema/3.0.0/spdx-json-schema.json \
+        $T/temp.json
+
+    pyshacl \
+        -s https://spdx.org/rdf/3.0.0/spdx-model.ttl \
+        -e https://spdx.org/rdf/3.0.0/spdx-model.ttl \
+        $T/temp.json
+done
+
+