feat: add CycloneDX document validators to public API

.github/workflows/python.yml

@@ -49,21 +49,21 @@ jobs:
         run: poetry run tox run -e flake8 -s false
 
   static-code-analysis:
-    name: StaticCodingAnalysis (py${{ matrix.python-version}} ${{ matrix.toxenv-factor }})
+    name: StaticCodingAnalysis (py${{ matrix.python-version}} ${{ matrix.toxenv-factors }})
     runs-on: ${{ matrix.os }}
     timeout-minutes: 10
     strategy:
       fail-fast: false
       matrix:
         include:
-          - # test with the locked dependencies
+          - # test with the latest dependencies
             os: ubuntu-latest
             python-version: '3.11'
-            toxenv-factor: 'locked'
+            toxenv-factors: '-current'
           - # test with the lowest dependencies
             os: ubuntu-latest
             python-version: '3.8'
-            toxenv-factor: 'lowest'
+            toxenv-factors: '-lowest'
     steps:
       - name: Checkout
         # see https://github.com/actions/checkout
@@ -82,10 +82,10 @@ jobs:
       - name: Install dependencies
         run: poetry install --no-root
       - name: Run tox
-        run: poetry run tox run -e mypy-${{ matrix.toxenv-factor }} -s false
+        run: poetry run tox run -e mypy${{ matrix.toxenv-factors }} -s false
 
   build-and-test:
-    name: Test (${{ matrix.os }} py${{ matrix.python-version }} ${{ matrix.toxenv-factor }})
+    name: Test (${{ matrix.os }} py${{ matrix.python-version }} ${{ matrix.toxenv-factors }})
     runs-on: ${{ matrix.os }}
     timeout-minutes: 15
     strategy:
@@ -97,12 +97,9 @@ jobs:
           - "3.10"
           - "3.9"
           - "3.8"  # lowest supported
-        toxenv-factor: ['locked']
-        include:
-          - # test with the lowest dependencies
-            os: ubuntu-latest
-            python-version: '3.8'
-            toxenv-factor: 'lowest'
+        toxenv-factors:
+          - '-allExtras'
+          - '-noExtras'
     steps:
       - name: Disabled Git auto EOL CRLF transforms
         run: |
@@ -134,14 +131,14 @@ jobs:
       - name: Ensure build successful
         run: poetry build
       - name: Run tox
-        run: poetry run tox run -e py-${{ matrix.toxenv-factor }} -s false
+        run: poetry run tox run -e py${{ matrix.toxenv-factors }} -s false
       - name: Generate coverage reports
         shell: bash
         run: |
           set -eux
           poetry run coverage report
-          poetry run coverage xml -o "$REPORTS_DIR/coverage.${{ matrix.os }}_py${{ matrix.python-version }}_${{ matrix.toxenv-factor }}.cobertura.xml"
-          # poetry run coverage lcov -o "$REPORTS_DIR/coverage.${{ matrix.os }}_py${{ matrix.python-version }}_${{ matrix.toxenv-factor }}.lcov.xml"
+          poetry run coverage xml -o "$REPORTS_DIR/coverage.${{ matrix.os }}_py${{ matrix.python-version }}_${{ matrix.toxenv-factors }}.cobertura.xml"
+          # poetry run coverage lcov -o "$REPORTS_DIR/coverage.${{ matrix.os }}_py${{ matrix.python-version }}_${{ matrix.toxenv-factors }}.lcov.xml"
       - name: Artifact reports
         if: ${{ ! cancelled() }}
         # see https://github.com/actions/upload-artifact
@@ -174,9 +171,16 @@ jobs:
           coverage-reports: ${{ env.REPORTS_DIR }}/coverage.*
 
   examples:
-    name: Examples
+    name: Examples E:${{ matrix.install-extras || '<none>' }}
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        install-extras:
+          - '' # none
+          - json-validation
+          - xml-validation
     steps:
       - name: Checkout
         # see https://github.com/actions/checkout
@@ -197,7 +201,7 @@ jobs:
         with:
           poetry-version: ${{ env.POETRY_VERSION }}
       - name: Install package and prod dependencies
-        run: poetry install --only=main -vvv
+        run: poetry install --only=main --extras='${{ matrix.install-extras }}' -vvv
       - name: run all examples
         run: >
           find examples -type f -name '*.py' -print0

.isort.cfg

@@ -20,3 +20,5 @@ src_paths =
     cyclonedx
     tests
     typings
+    examples
+    tools

CONTRIBUTING.md

@@ -12,7 +12,7 @@ This project uses [poetry]. Have it installed and setup first.
 To install dev-dependencies and tools:
 
 ```shell
-poetry install
+poetry install --all-extras
 ```
 
 ## Code style
@@ -23,7 +23,7 @@ Get it all applied via:
 
 ```shell
 poetry run isort .
-poetry run autopep8 -ir cyclonedx/ tests/ typings/
+poetry run autopep8 -ir cyclonedx/ tests/ typings/ examples/
 ```
 
 ## Documentation

cyclonedx/exception/__init__.py

@@ -25,3 +25,8 @@ class CycloneDxException(Exception):
     Root exception thrown by this library.
     """
     pass
+
+
+class MissingOptionalDependencyException(CycloneDxException):
+    """Validation did not happen, due to missing dependencies."""
+    pass

cyclonedx/schema/_res/.editorconfig

@@ -0,0 +1,10 @@
+
+# fix settings for files that are copied over, to keep them as is
+[*.SNAPSHOT.xsd]
+indent_size = 4
+indent_style = space
+trim_trailing_whitespace = false
+[*.SNAPSHOT.schema.json]
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = false

cyclonedx/schema/_res/.gitattributes

@@ -0,0 +1,6 @@
+# snapshots are vendored for offline use
+*.SNAPSHOT.*    linguist-vendored
+
+# specs are vendored for offline use
+*.xsd           linguist-vendored
+*.schema.json   linguist-vendored

cyclonedx/schema/_res/README.md

@@ -0,0 +1,30 @@
+# Resources: Schema files
+
+some schema for offline use as download via [script](../../../tools/schema-downloader.py).
+original sources: <https://github.com/CycloneDX/specification/tree/master/schema>
+
+Currently using version
+[fd4d383658196992364e5d62568a48c431ace515](https://github.com/CycloneDX/specification/commit/fd4d383658196992364e5d62568a48c431ace515)
+
+| file | note |
+|------|------|
+| [`bom-1.0.SNAPSHOT.xsd`](bom-1.0.SNAPSHOT.xsd) | applied changes: 1 |
+| [`bom-1.1.SNAPSHOT.xsd`](bom-1.1.SNAPSHOT.xsd) | applied changes: 1 |
+| [`bom-1.2.SNAPSHOT.xsd`](bom-1.2.SNAPSHOT.xsd) | applied changes: 1 |
+| [`bom-1.3.SNAPSHOT.xsd`](bom-1.3.SNAPSHOT.xsd) | applied changes: 1 |
+| [`bom-1.4.SNAPSHOT.xsd`](bom-1.4.SNAPSHOT.xsd) | applied changes: 1 |
+| [`bom-1.2.SNAPSHOT.schema.json`](bom-1.2.SNAPSHOT.schema.json) | applied changes: 2,3,4,5 |
+| [`bom-1.3.SNAPSHOT.schema.json`](bom-1.3.SNAPSHOT.schema.json) | applied changes: 2,3,4,5 |
+| [`bom-1.4.SNAPSHOT.schema.json`](bom-1.4.SNAPSHOT.schema.json) | applied changes: 2,3,4,5 |
+| [`bom-1.2-strict.SNAPSHOT.schema.json`](bom-1.2-strict.SNAPSHOT.schema.json) | applied changes: 2,3,4,5 |
+| [`bom-1.3-strict.SNAPSHOT.schema.json`](bom-1.3-strict.SNAPSHOT.schema.json) | applied changes: 2,3,4,5 |
+| [`spdx.SNAPSHOT.xsd`](spdx.SNAPSHOT.xsd) | |
+| [`spdx.SNAPSHOT.schema.json`](spdx.SNAPSHOT.schema.json) | |
+| [`jsf-0.82.SNAPSHOT.schema.json`](jsf-0.82.SNAPSHOT.schema.json) | |
+
+changes:
+1. `https?://cyclonedx.org/schema/spdx` was replaced with `spdx.SNAPSHOT.xsd`
+2. `spdx.schema.json` was replaced with `spdx.SNAPSHOT.schema.json`
+3. `jsf-0.82.schema.json` was replaced with `jsf-0.82.SNAPSHOT.schema.json`
+4. `properties.$schema.enum` was fixed to match `$id`
+5. `required.version` removed, as it is actually optional with default value

cyclonedx/schema/_res/__init__.py

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from os.path import dirname, join
+from typing import Dict, Optional
+
+from .. import SchemaVersion
+
+"""
+Content in here is internal, not for public use.
+Breaking changes without notice may happen.
+"""
+
+__DIR = dirname(__file__)
+
+BOM_XML: Dict[SchemaVersion, Optional[str]] = {
+    SchemaVersion.V1_4: join(__DIR, 'bom-1.4.SNAPSHOT.xsd'),
+    SchemaVersion.V1_3: join(__DIR, 'bom-1.3.SNAPSHOT.xsd'),
+    SchemaVersion.V1_2: join(__DIR, 'bom-1.2.SNAPSHOT.xsd'),
+    SchemaVersion.V1_1: join(__DIR, 'bom-1.1.SNAPSHOT.xsd'),
+    SchemaVersion.V1_0: join(__DIR, 'bom-1.0.SNAPSHOT.xsd'),
+}
+
+BOM_JSON: Dict[SchemaVersion, Optional[str]] = {
+    SchemaVersion.V1_4: join(__DIR, 'bom-1.4.SNAPSHOT.schema.json'),
+    SchemaVersion.V1_3: join(__DIR, 'bom-1.3.SNAPSHOT.schema.json'),
+    SchemaVersion.V1_2: join(__DIR, 'bom-1.2.SNAPSHOT.schema.json'),
+    # <= v1.1 is not defined in JSON
+    SchemaVersion.V1_1: None,
+    SchemaVersion.V1_0: None,
+}
+
+BOM_JSON_STRICT: Dict[SchemaVersion, Optional[str]] = {
+    # >= v1.4 is already strict - no special file here
+    SchemaVersion.V1_4: join(__DIR, 'bom-1.4.SNAPSHOT.schema.json'),
+    # <= 1.3 need special files
+    SchemaVersion.V1_3: join(__DIR, 'bom-1.3-strict.SNAPSHOT.schema.json'),
+    SchemaVersion.V1_2: join(__DIR, 'bom-1.2-strict.SNAPSHOT.schema.json'),
+    # <= v1.1 is not defined in JSON
+    SchemaVersion.V1_1: None,
+    SchemaVersion.V1_0: None,
+}
+
+SPDX_JSON = join(__DIR, 'spdx.SNAPSHOT.schema.json')
+SPDX_XML = join(__DIR, 'spdx.SNAPSHOT.xsd')
+
+JSF = join(__DIR, 'jsf-0.82.SNAPSHOT.schema.json')

cyclonedx/schema/bom-1.0.xsd → cyclonedx/schema/_res/bom-1.0.SNAPSHOT.xsd

@@ -7,9 +7,9 @@
            targetNamespace="http://cyclonedx.org/schema/bom/1.0"
            vc:minVersion="1.0"
            vc:maxVersion="1.1"
-           version="1.0">
+           version="1.0.1">
 
-    <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
+    <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.SNAPSHOT.xsd"/>
 
     <xs:complexType name="component">
         <xs:sequence>

cyclonedx/schema/bom-1.1.xsd → cyclonedx/schema/_res/bom-1.1.SNAPSHOT.xsd

@@ -24,7 +24,7 @@ limitations under the License.
            vc:maxVersion="1.1"
            version="1.1">
 
-    <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
+    <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.SNAPSHOT.xsd"/>
 
     <xs:annotation>
         <xs:documentation>
@@ -38,6 +38,13 @@ limitations under the License.
         </xs:documentation>
     </xs:annotation>
 
+    <xs:simpleType name="refType">
+        <xs:annotation>
+            <xs:documentation>Identifier-DataType for interlinked elements.</xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string" />
+    </xs:simpleType>
+
     <xs:complexType name="componentsType">
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
             <xs:element name="component" type="bom:component"/>
@@ -201,7 +208,7 @@ limitations under the License.
                 </xs:documentation>
             </xs:annotation>
         </xs:attribute>
-        <xs:attribute name="bom-ref" type="xs:string">
+        <xs:attribute name="bom-ref" type="bom:refType">
             <xs:annotation>
                 <xs:documentation>
                     An optional identifier which can be used to reference the component elsewhere in the BOM.

cyclonedx/schema/bom-1.2b.schema.json → cyclonedx/schema/_res/bom-1.2-strict.SNAPSHOT.schema.json

@@ -6,15 +6,14 @@
   "$comment" : "CycloneDX JSON schema is published under the terms of the Apache License 2.0.",
   "required": [
     "bomFormat",
-    "specVersion",
-    "version"
+    "specVersion"
   ],
   "additionalProperties": false,
   "properties": {
     "$schema": {
       "type": "string",
       "enum": [
-        "http://cyclonedx.org/schema/bom-1.2a.schema.json"
+        "http://cyclonedx.org/schema/bom-1.2b.schema.json"
       ]
     },
     "bomFormat": {
@@ -87,6 +86,10 @@
     }
   },
   "definitions": {
+    "refType": {
+      "$comment": "Identifier-DataType for interlinked elements.",
+      "type": "string"
+    },
     "metadata": {
       "type": "object",
       "title": "BOM Metadata Object",
@@ -261,7 +264,7 @@
           "pattern": "^[-+a-z0-9.]+/[-+a-z0-9.]+$"
         },
         "bom-ref": {
-          "type": "string",
+          "$ref": "#/definitions/refType",
           "title": "BOM Reference",
           "description": "An optional identifier which can be used to reference the component elsewhere in the BOM. Every bom-ref should be unique.",
           "default": "",
@@ -595,7 +598,7 @@
       "additionalProperties": false,
       "properties": {
         "id": {
-          "$ref": "spdx.schema.json",
+          "$ref": "spdx.SNAPSHOT.schema.json",
           "title": "License ID (SPDX)",
           "description": "A valid SPDX license ID",
           "examples": ["Apache-2.0"]
@@ -859,16 +862,15 @@
       "additionalProperties": false,
       "properties": {
         "ref": {
-          "type": "string",
-          "format": "string",
+          "$ref": "#/definitions/refType",
           "title": "Reference",
           "description": "References a component by the components bom-ref attribute"
         },
         "dependsOn": {
           "type": "array",
           "uniqueItems": true,
           "items": {
-            "type": "string"
+            "$ref": "#/definitions/refType"
           },
           "title": "Depends On",
           "description": "The bom-ref identifiers of the components that are dependencies of this dependency object."
@@ -884,7 +886,7 @@
       "additionalProperties": false,
       "properties": {
         "bom-ref": {
-          "type": "string",
+          "$ref": "#/definitions/refType",
           "title": "BOM Reference",
           "description": "An optional identifier which can be used to reference the service elsewhere in the BOM. Every bom-ref should be unique.",
           "default": "",