Add examples validation

.github/workflows/validate_examples.yml

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: Copyright 2024 The SPDX Contributors
+on:
+  pull_request:
+    paths:
+      - 'docs/*.md'  # For code snippets inside a document
+      - 'examples/jsonld/*.json'
+  push:
+    paths:
+      - 'docs/*.md'
+      - 'examples/jsonld/*.json'
+  workflow_dispatch: {}
+jobs:
+  validate-examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  #v4.2.2
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install check-jsonschema==0.30.0 pyshacl==0.29.1 spdx3-validate==0.0.5
+      - name: Install dependencies
+        run: |
+          sudo apt install -y gawk  
+      - name: Check examples
+        run: |
+          ./bin/check-examples.sh

bin/check-examples.sh

@@ -0,0 +1,124 @@
+#! /bin/bash
+#
+# Validates SPDX example, both in separate files and inline in the
+# documentation
+#
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright 2024 The SPDX Contributors
+
+set -e
+
+THIS_DIR=$(dirname "$0")
+MD_DIR=docs
+JSON_DIR=examples/jsonld
+
+SPDX_VERSION="3.0.1"
+SCHEMA_URL="https://spdx.org/schema/${SPDX_VERSION}/spdx-json-schema.json"
+RDF_URL="https://spdx.org/rdf/${SPDX_VERSION}/spdx-model.ttl"
+CONTEXT_URL="https://spdx.org/rdf/${SPDX_VERSION}/spdx-context.jsonld"
+
+# print validation setup
+echo "Checking examples in"
+echo "Snippets         : $MD_DIR"
+echo "Files            : $JSON_DIR"
+echo "SPDX version     : $SPDX_VERSION"
+echo "Schema           : $SCHEMA_URL"
+echo "Schema resolved  : $(curl -I "$SCHEMA_URL" 2>/dev/null | grep -i "location:" | awk '{print $2}')"
+echo "RDF              : $RDF_URL"
+echo "RDF resolved     : $(curl -I "$RDF_URL" 2>/dev/null | grep -i "location:" | awk '{print $2}')"
+echo "Context          : $CONTEXT_URL"
+echo "Context resolved : $(curl -I "$CONTEXT_URL" 2>/dev/null | grep -i "location:" | awk '{print $2}')"
+echo "$(check-jsonschema --version)"
+echo -n "$(pyshacl --version)"
+echo "spdx3-validate version: $(spdx3-validate --version)"
+echo ""
+
+check_schema() {
+    echo "Checking schema (check-jsonschema): $1"
+    check-jsonschema \
+        --verbose \
+        --schemafile $SCHEMA_URL \
+        "$1"
+}
+
+check_model() {
+    echo "Checking model (pyschacl): $1"
+    pyshacl \
+        --shacl $RDF_URL \
+        --ont-graph $RDF_URL \
+        "$1"
+}
+
+check_spdx() {
+    echo "SPDX 3 validating (spdx3-validate): $1"
+    spdx3-validate --json $1
+}
+
+# Check examples in JSON files
+if [ "$(ls $THIS_DIR/../$JSON_DIR/*.json 2>/dev/null)" ]; then
+    for f in $THIS_DIR/../$JSON_DIR/*.json; do
+        check_schema $f
+        echo ""
+        check_model $f
+        echo ""
+        check_spdx $f
+        echo ""
+    done
+fi
+
+# Check examples in inline code snippets in Markdown files
+TEMP=$(mktemp -d)
+for f in $THIS_DIR/../$MD_DIR/*.md; do
+    if ! grep -q '^```json' $f; then
+        continue
+    fi
+    echo "Extract snippets from $f"
+    DEST=$TEMP/$(basename $f)
+    mkdir -p $DEST
+
+    # Read inline code snippets and save them in separate, numbered files.
+    cat $f | awk -v DEST="$DEST" 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > DEST "/doc-" flag ".spdx.json"}'
+
+    # Combine all JSON code snippets into a single file, with SPDX context and creation info.
+    COMBINED_JSON = $DEST/__combined.json
+    echo "[" > $COMBINED_JSON
+
+    for doc in $DEST/*.spdx.json; do
+        if ! grep -q '@context' $doc; then
+            mv $doc $doc.fragment
+            cat >> $doc <<HEREDOC
+{
+    "@context": "$CONTEXT_URL",
+    "@graph": [
+HEREDOC
+            cat $doc.fragment >> $doc
+            cat >> $doc <<HEREDOC
+        {
+            "type": "CreationInfo",
+            "@id": "_:creationInfo",
+            "specVersion": "$SPDX_VERSION",
+            "created": "2024-04-23T00:00:00Z",
+            "createdBy": [
+                {
+                    "type": "Agent",
+                    "spdxId": "http://spdx.dev/dummy-agent",
+                    "creationInfo": "_:creationInfo"
+                }
+            ]
+        }
+    ]
+}
+HEREDOC
+        fi
+        check_schema $doc
+        cat $doc >> $COMBINED_JSON
+        echo "," >> $COMBINED_JSON
+    done
+
+    echo "{}]" >> $COMBINED_JSON
+
+    check_model $COMBINED_JSON
+    echo ""
+    check_spdx $COMBINED_JSON
+    echo ""
+done

docs/cross-reference.md

@@ -16,13 +16,13 @@ It is frequently desired (and necessary) to reference an SPDX 3
 [Element][Class_Element] that lives in one document from another. Since SPDX
 documents are valid [JSON-LD][JSON_LD] documents, linking elements together can
 be as simple as referencing the spdxId of one element from another (in the same
-way that doing so within a document links Elements together. For example,
+way that doing so within a document links Elements together). For example,
 assume we have this document that contains a [Person][Class_Person] we want to
 reference in another document:
 
 ```json
 {
-    "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld",
+    "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
     "@graph": [
         {
             "type": "Person",
@@ -40,7 +40,7 @@ reference in another document:
         {
             "type": "CreationInfo",
             "@id": "_:creationinfo",
-            "specVersion": "3.0.0",
+            "specVersion": "3.0.1",
             "createdBy": [
                 "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f"
             ],
@@ -69,12 +69,12 @@ was also written by the same person, we can reference it in the creation info
 ```json
 ---
 {
-    "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld",
+    "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
     "@graph": [
         {
             "type": "CreationInfo",
             "@id": "_:creationinfo1",
-            "specVersion": "3.0.0",
+            "specVersion": "3.0.1",
             "createdBy": [
                 "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f"
             ],
@@ -89,7 +89,7 @@ information that SPDX requires you to specify. Namely, since spdxIds are _not_
 necessarily resolvable URLs, this gives no indication as to where the
 [Person][Class_Person] can be found. In order to provide this information, SPDX
 requires that all externally referenced spdxIds be enumerated in the
-[imports][Property_imports] property of the local
+[import][Property_import] property of the local
 [SpdxDocument][Class_SpdxDocument]. Lets start by writing the preamble for the
 SpdxDocument:
 
@@ -102,10 +102,10 @@ SpdxDocument:
                 "core",
                 "software"
             ],
-            "imports": [
+            "import": [
 ```
 
-The [imports][Property_imports] property is a list of
+The [import][Property_import] property is a list of
 [ExternalMap][Class_ExternalMap] objects, one for each external spdxId being
 referenced. The class has one required property called
 [externalSpdxId][Property_externalSpdxId] which is the external spdxId being
@@ -153,7 +153,7 @@ class, it is also recommended:
 ```
 
 It should be noted that it is reasonable for the `definingArtifact` itself to
-be an external spdxId, as long as it also has the relevant entry in `imports`.
+be an external spdxId, as long as it also has the relevant entry in `import`.
 
 We also need to add an import for the [SpdxDocument][Class_SpdxDocument] that
 contains the author, as we will be referencing it later, so lets do that now:
@@ -231,17 +231,17 @@ needed to import it earlier:
 
 Happy Linking!
 
-[Class_Artifact]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Artifact
-[Class_Element]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element
-[Class_ExternalMap]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ExternalMap
-[Class_IntegrityMethod]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/IntegrityMethod
-[Class_Person]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Person
-[Class_SpdxDocument]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/SpdxDocument
-[Class_Relationship]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Relationship
+[Class_Artifact]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Artifact/
+[Class_Element]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/
+[Class_ExternalMap]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ExternalMap/
+[Class_IntegrityMethod]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/IntegrityMethod/
+[Class_Person]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Person/
+[Class_SpdxDocument]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/SpdxDocument/
+[Class_Relationship]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Relationship/
 [JSON_LD]: https://json-ld.org/
-[Property_createdBy]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/createdBy
-[Property_definingArtifact]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/definingArtifact
-[Property_externalSpdxId]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/externalSpdxId
-[Property_imports]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/imports
-[Property_verifiedUsing]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/verifiedUsing
-[Property_locationHint]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/locationHint
+[Property_createdBy]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/createdBy/
+[Property_definingArtifact]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/definingArtifact/
+[Property_externalSpdxId]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/externalSpdxId/
+[Property_import]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/import/
+[Property_verifiedUsing]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/verifiedUsing/
+[Property_locationHint]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/locationHint/

docs/diffs-from-previous-editions.md

@@ -37,7 +37,7 @@ Each ExternalDocumentRef instance will translate as follows:
   - An integrity method of “Hash” will be created with the same information as the checksum property and will be referenced using the “verifiedUsing” property on the ExternalMap entry.
 - An entry would be created in the ExternalMap for each element referenced in the current SpdxDocument that is originally specified in the referenced SpdxDocument.
   - A string identifier consisting of the DocumentRef-[idstring] (the same value as the prefix in the NamespaceMap) concatenated with a “:” and then concatenated with the local portion of the element identifier would be used for the externalSpdxId in the ExternalMap
-  - A “definingDocument” property would be specified containing a string identifier consisting of the DocumentRef-[idstring] concatenated with a “:” and then concatenated with “SPDXRef-DOCUMENT”. This is a shortcut linkage to tie the referenced element to its defining SpdxDocument for verification and location information.
+  - A “definingArtifact” property would be specified containing a string identifier consisting of the DocumentRef-[idstring] concatenated with a “:” and then concatenated with “SPDXRef-DOCUMENT”. This is a shortcut linkage to tie the referenced element to its defining SpdxDocument for verification and location information.
 
 ##### Rationale
 
@@ -51,7 +51,7 @@ The ExternalDocumentRef structure in SPDX 2.3 is based on the presumptions that
 
 The Namespace map structure in SPDX 3.0 fully supports the namespace prefixing use case for SpdxDocuments previously covered by ExternalDocumentRef but also equally covers the same use case capability for all element types and for any number of element identifier namespaces (in SPDX 3.0 all elements within an SpdxDocument are not required to have the same namespace and can actually be any desired mix of namespaces) to support this capability required in SPDX 3.0.
 
-The ExternalMap structure in SPDX 3.0 fully supports the external element (including SpdxDocument elements) referencing use case for SpdxDocuments previously covered by ExternalDocumentRef but also equally covers the same use case capability for any elements whether they were originally defined within an SpdxDocument or not to support this capability required in SPDX 3.0. The ExternalMap structure in SPDX 3.0 provides the ability to specify verification and location details for any element, not just SpdxDocuments, if appropriate but also provides simple linkage, using the “definingDocument'' property, from element entries in the ExternalMap to SpdxDocument entries in the ExternalMap where the elements were defined within the SpdxDocument and verification of the elements can be achieved via proxy to the SpdxDocument “verifiedUsing” information (this is how the SPDX 2.3 ExternalDocumentRef structure currently works).
+The ExternalMap structure in SPDX 3.0 fully supports the external element (including SpdxDocument elements) referencing use case for SpdxDocuments previously covered by ExternalDocumentRef but also equally covers the same use case capability for any elements whether they were originally defined within an SpdxDocument or not to support this capability required in SPDX 3.0. The ExternalMap structure in SPDX 3.0 provides the ability to specify verification and location details for any element, not just SpdxDocuments, if appropriate but also provides simple linkage, using the “definingArtifact” property, from element entries in the ExternalMap to SpdxDocument entries in the ExternalMap where the elements were defined within the SpdxDocument and verification of the elements can be achieved via proxy to the SpdxDocument “verifiedUsing” information (this is how the SPDX 2.3 ExternalDocumentRef structure currently works).
 
 #### Agent
 
@@ -113,17 +113,17 @@ An example conversion table from SPDX 2.3 `FileType` to SPDX 3.0 `ContentType` o
 
 | SPDX 2 File Type | SPDX 3 Software Purpose | SPDX 3 Content Type |
 |------------------|-------------------------|---------------------|
-| ARCHIVE | Archive | |
+| ARCHIVE | archive | |
 | BINARY | | application/octet-stream |
-| SOURCE | Source | |
+| SOURCE | source | |
 | TEXT | | text/plain |
-| APPLICATION | Application | |
+| APPLICATION | application | |
 | AUDIO | | audio/* |
 | IMAGE | | image/* |
 | VIDEO | | video/* |
-| DOCUMENTATION | Documentation | |
-| SPDX | | text/spdx |
-| OTHER | Other | |
+| DOCUMENTATION | documentation | |
+| SPDX | | application/spdx+json, text/spdx |
+| OTHER | other | |
 
 #### Package File Name
 
@@ -133,7 +133,7 @@ The packageFileName property and packageChecksum property has been replaced by a
 
 ##### Translating from 2.3 to 3.0
 
-Create an SPDX File with the name from the packageFileName and a verifiedUsing value from the packageChecksum for a single file.  If the packageFileName is a directory, then the SPDX File is created with the directory name and is verified using the contentIdentifier property on the File and a fileKind of directory.  Create a hasDistributionArifact relationship from the SPDX Package to the SPDX File.
+Create an SPDX File with the name from the packageFileName and a verifiedUsing value from the packageChecksum for a single file.  If the packageFileName is a directory, then the SPDX File is created with the directory name and is verified using the contentIdentifier property on the File and a fileKind of directory.  Create a hasDistributionArtifact relationship from the SPDX Package to the SPDX File.
 
 ##### Rationale
 
@@ -158,7 +158,7 @@ The following ExternalRef Types should be converted to ExternalIdentifiers:
 - swid
 - purl
 
-The following ExternalRef Types should be converted to ContentIdentifers:
+The following ExternalRef Types should be converted to ContentIdentifiers:
 
 - gitoid
 - swh
@@ -185,15 +185,15 @@ If there is a single ExternalReference of type purl without the optional Externa
 
 ##### Rationale
 
-Package URL is  a very common method of identifying software packages.  Moving this to a property makes it significantly simpler to find and correlate Package URL identifiers.
+Package URL is a very common method of identifying software packages.  Moving this to a property makes it significantly simpler to find and correlate Package URL identifiers.
 
 #### Annotation
 
 ##### Description of Change
 
 Annotations are now subclasses of Element, so it inherits a number of new optional properties including names, annotations, and its own relationships.
 
-Annotations are no longer a property of an Element.  It is now a standalone element with a “subject”  field which points to the Element being annotated.
+Annotations are no longer a property of an Element.  It is now a standalone element with a “subject” field which points to the Element being annotated.
 
 ##### Translating from 2.3 to 3.0
 
@@ -309,7 +309,8 @@ Changing the snippetFromFile from a property to a relationship [to be filled in]
 
 The type of SpecVersion is changed from a simple string without constraints to a SemVer string which must follow the [Semantic Versioning format](https://semver.org/).
 
-This adds a constraint where a patch version is required.  Previous usage of the SpecVersiononly included the major and minor version.
+This adds a constraint where a patch version is required.
+Previous usage of the SpecVersion only included the major and minor version.
 
 ##### Translating from 2.3 to 3.0
 
@@ -357,23 +358,23 @@ LicenseException
 
 This field has not been used.
 
-#### LicenseInfoInFiles
+#### LicenseInfoInFile
 
 ##### SPDX 2.3 Model Name
 
-licenseInfoInFiles
+licenseInfoInFile
 
 ##### Tag/Value Name
 
-LicenseInfoInFiles
+LicenseInfoInFile
 
 ##### Range / Where Used
 
 Package
 
 ##### Rationale
 
-This field is redundant with the declaredLicense property in the Files contained in the Package.  It is recommended that the licenseInfoInFiles can be added as an Annotation to the Package in the format: “SPDX 2.X LicenseInfoInFiles: [expression1], [expression2]”  where the [expressions] are the string representation of the license expressions.
+This field is redundant with the declaredLicense property in the Files contained in the Package.  It is recommended that the licenseInfoInFile can be added as an Annotation to the Package in the format: “SPDX 2.X LicenseInfoInFile: [expression1], [expression2]” where the [expressions] are the string representation of the license expressions.
 
 #### FilesAnalyzed
 
@@ -689,7 +690,7 @@ Custom Additions have been added in SPDX 3.0 which operate in a similar manner t
 
 ##### SPDX 2.3 Model Name
 
-ExtractedLicenseInfo
+extractedText
 
 ##### Tag/Value Name