Merge pull request #236 from CycloneDX/v1.5-explicit-bomlink

intro to explicitly linked elements

schema/bom-1.5.schema.json

@@ -42,6 +42,7 @@
       "type": "integer",
       "title": "BOM Version",
       "description": "Whenever an existing BOM is modified, either manually or through automated processes, the version of the BOM SHOULD be incremented by 1. When a system is presented with multiple BOMs with identical serial numbers, the system SHOULD use the most recent version of the BOM. The default version is '1'.",
+      "minimum": 1,
       "default": 1,
       "examples": [1]
     },
@@ -121,20 +122,28 @@
   },
   "definitions": {
     "refType": {
-      "$comment": "Identifier-DataType for interlinked elements.",
-      "type": "string"
+      "description": "Identifier for referable and therefore interlink-able elements.",
+      "type": "string",
+      "minLength": 1,
+      "$comment": "value SHOULD not start with the BOM-Link intro 'urn:cdx:'"
+    },
+    "refLinkType": {
+      "description": "Descriptor for an element identified by the attribute 'bom-ref' in the same BOM document.\nIn contrast to `bomLinkElementType`.",
+      "allOf": [{"$ref": "#/definitions/refType"}]
     },
     "bomLinkDocumentType": {
       "title": "BOM-Link document",
       "description": "Descriptor for another BOM document. See https://cyclonedx.org/capabilities/bomlink/",
       "type": "string",
+      "format": "iri-reference",
       "pattern": "^urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/[1-9][0-9]*$",
       "$comment": "part of the pattern is based on `bom.serialNumber`'s pattern"
     },
     "bomLinkElementType": {
       "title": "BOM-Link element",
       "description": "Descriptor for an element in another BOM document. See https://cyclonedx.org/capabilities/bomlink/",
       "type": "string",
+      "format": "iri-reference",
       "pattern": "^urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/[1-9][0-9]*#.+$",
       "$comment": "part of the pattern is based on `bom.serialNumber`'s pattern"
     },
@@ -1125,10 +1134,17 @@
       "additionalProperties": false,
       "properties": {
         "url": {
-          "type": "string",
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "iri-reference"
+            },
+            {
+              "$ref": "#/definitions/bomLink"
+            }
+          ],
           "title": "URL",
-          "description": "The URI (URL or URN) to the external reference. External references are URIs and therefore can accept any URL scheme including https ([RFC-7230](https://www.ietf.org/rfc/rfc7230.txt)), mailto ([RFC-2368](https://www.ietf.org/rfc/rfc2368.txt)), tel ([RFC-3966](https://www.ietf.org/rfc/rfc3966.txt)), and dns ([RFC-4501](https://www.ietf.org/rfc/rfc4501.txt)). External references may also include formally registered URNs such as [CycloneDX BOM-Link](https://cyclonedx.org/capabilities/bomlink/) to reference CycloneDX BOMs or any object within a BOM. BOM-Link transforms applicable external references into relationships that can be expressed in a BOM or across BOMs.",
-          "format": "iri-reference"
+          "description": "The URI (URL or URN) to the external reference. External references are URIs and therefore can accept any URL scheme including https ([RFC-7230](https://www.ietf.org/rfc/rfc7230.txt)), mailto ([RFC-2368](https://www.ietf.org/rfc/rfc2368.txt)), tel ([RFC-3966](https://www.ietf.org/rfc/rfc3966.txt)), and dns ([RFC-4501](https://www.ietf.org/rfc/rfc4501.txt)). External references may also include formally registered URNs such as [CycloneDX BOM-Link](https://cyclonedx.org/capabilities/bomlink/) to reference CycloneDX BOMs or any object within a BOM. BOM-Link transforms applicable external references into relationships that can be expressed in a BOM or across BOMs."
         },
         "comment": {
           "type": "string",
@@ -1199,15 +1215,15 @@
       "additionalProperties": false,
       "properties": {
         "ref": {
-          "$ref": "#/definitions/refType",
+          "$ref": "#/definitions/refLinkType",
           "title": "Reference",
           "description": "References a component by the components bom-ref attribute"
         },
         "dependsOn": {
           "type": "array",
           "uniqueItems": true,
           "items": {
-            "$ref": "#/definitions/refType"
+            "$ref": "#/definitions/refLinkType"
           },
           "title": "Depends On",
           "description": "The bom-ref identifiers of the components that are dependencies of this dependency object."
@@ -1362,17 +1378,31 @@
         "source": {
           "type": "array",
           "items": {
-            "type": "string",
-            "format": "iri-reference"
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "iri-reference"
+              },
+              {
+                "$ref": "#/definitions/bomLinkElementType"
+              }
+            ]
           },
           "title": "Source",
           "description": "The URI, URL, or BOM-Link of the components or services the data came in from"
         },
         "destination": {
           "type": "array",
           "items": {
-            "type": "string",
-            "format": "iri-reference"
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "iri-reference"
+              },
+              {
+                "$ref": "#/definitions/bomLinkElementType"
+              }
+            ]
           },
           "title": "Destination",
           "description": "The URI, URL, or BOM-Link of the components or services the data is sent to"
@@ -1480,7 +1510,10 @@
               "type": "array",
               "uniqueItems": true,
               "items": {
-                "$ref": "#/definitions/refType"
+                "anyOf": [
+                  {"$ref": "#/definitions/refLinkType"},
+                  {"$ref": "#/definitions/bomLinkElementType"}
+                ]
               },
               "title": "BOM References",
               "description": "The object in the BOM identified by its bom-ref. This is often a component or service, but may be any object type supporting bom-refs. Tools used for analysis should already be defined in the BOM, either in the metadata/tools, components, or formulation."
@@ -1600,7 +1633,10 @@
           "type": "array",
           "uniqueItems": true,
           "items": {
-            "$ref": "#/definitions/refType"
+            "anyOf": [
+              {"$ref": "#/definitions/refLinkType"},
+              {"$ref": "#/definitions/bomLinkElementType"}
+            ]
           },
           "title": "BOM references",
           "description": "The bom-ref identifiers of the components or services being described. Assemblies refer to nested relationships whereby a constituent part may include other constituent parts. References do not cascade to child parts. References are explicit for the specified constituent part only."
@@ -2182,7 +2218,10 @@
             "additionalProperties": false,
             "properties": {
               "ref": {
-                "$ref": "#/definitions/refType",
+                "anyOf": [
+                  {"$ref": "#/definitions/refLinkType"},
+                  {"$ref": "#/definitions/bomLinkElementType"}
+                ],
                 "title": "Reference",
                 "description": "References a component or service by the objects bom-ref"
               },
@@ -2275,7 +2314,10 @@
           "type": "array",
           "uniqueItems": true,
           "items": {
-            "$ref": "#/definitions/refType"
+            "anyOf": [
+              {"$ref": "#/definitions/refLinkType"},
+              {"$ref": "#/definitions/bomLinkElementType"}
+            ]
           },
           "title": "BOM References",
           "description": "The object in the BOM identified by its bom-ref. This is often a component or service, but may be any object type supporting bom-refs."
@@ -2413,7 +2455,10 @@
                     "additionalProperties": false,
                     "properties": {
                       "ref": {
-                        "$ref": "#/definitions/refType",
+                        "anyOf": [
+                          {"$ref": "#/definitions/refLinkType"},
+                          {"$ref": "#/definitions/bomLinkElementType"}
+                        ],
                         "title": "Reference",
                         "description": "References a data component by the components bom-ref attribute"
                       }

schema/bom-1.5.xsd

@@ -37,9 +37,21 @@ limitations under the License.
 
     <xs:simpleType name="refType">
         <xs:annotation>
-            <xs:documentation>Identifier-DataType for interlinked elements.</xs:documentation>
+            <xs:documentation>Identifier for referable and therefore interlink-able elements.</xs:documentation>
         </xs:annotation>
-        <xs:restriction base="xs:string" />
+        <xs:restriction base="xs:string">
+            <xs:minLength value="1"/>
+            <!-- value SHOULD not start with the BOM-Link intro "urn:cdx:" -->
+        </xs:restriction>
+    </xs:simpleType>
+    <xs:simpleType name="refLinkType">
+        <xs:annotation>
+            <xs:documentation xml:lang="en">
+                Descriptor for an element identified by the attribute "bom-ref" in the same BOM document.
+                In contrast to `bomLinkElementType`.
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="bom:refType"/>
     </xs:simpleType>
 
     <xs:simpleType name="bomLinkDocumentType">
@@ -49,9 +61,9 @@ limitations under the License.
                 See https://cyclonedx.org/capabilities/bomlink/
             </xs:documentation>
         </xs:annotation>
-        <xs:restriction base="xs:string">
+        <xs:restriction base="xs:anyURI">
             <!-- part of the pattern is based on `bom.serialNumber`'s pattern -->
-            <xs:pattern value="urn:cdx:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})|(\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\})/[1-9][0-9]*"/>
+            <xs:pattern value="urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/[1-9][0-9]*"/>
         </xs:restriction>
     </xs:simpleType>
     <xs:simpleType name="bomLinkElementType">
@@ -61,9 +73,9 @@ limitations under the License.
                 See https://cyclonedx.org/capabilities/bomlink/
             </xs:documentation>
         </xs:annotation>
-        <xs:restriction base="xs:string">
+        <xs:restriction base="xs:anyURI">
             <!-- part of the pattern is based on `bom.serialNumber`'s pattern -->
-            <xs:pattern value="urn:cdx:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})|(\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\})/[1-9][0-9]*#.+"/>
+            <xs:pattern value="urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/[1-9][0-9]*#.+"/>
         </xs:restriction>
     </xs:simpleType>
     <xs:simpleType name="bomLinkType">
@@ -1380,7 +1392,7 @@ limitations under the License.
 
     <xs:complexType name="externalReference">
         <xs:sequence>
-            <xs:element name="url" type="xs:anyURI" minOccurs="1" maxOccurs="1">
+            <xs:element name="url" minOccurs="1" maxOccurs="1">
                 <xs:annotation>
                     <xs:documentation xml:lang="en">The URI (URL or URN) to the external reference. External references
                         are URIs and therefore can accept any URL scheme including https, mailto, tel, and dns.
@@ -1389,6 +1401,9 @@ limitations under the License.
                         references into relationships that can be expressed in a BOM or across BOMs. Refer to:
                         https://cyclonedx.org/capabilities/bomlink/</xs:documentation>
                 </xs:annotation>
+                <xs:simpleType>
+                    <xs:union memberTypes="xs:anyURI bom:bomLinkType"/>
+                </xs:simpleType>
             </xs:element>
             <xs:element name="comment" type="xs:string" minOccurs="0" maxOccurs="1">
                 <xs:annotation>
@@ -1769,9 +1784,9 @@ limitations under the License.
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
             <xs:element name="dependency" type="bom:dependencyType"/>
         </xs:sequence>
-        <xs:attribute name="ref" type="bom:refType" use="required">
+        <xs:attribute name="ref" type="bom:refLinkType" use="required">
             <xs:annotation>
-                <xs:documentation>References a component or service by the its bom-ref attribute</xs:documentation>
+                <xs:documentation>References a component or service by its bom-ref attribute</xs:documentation>
             </xs:annotation>
         </xs:attribute>
         <xs:anyAttribute namespace="##other" processContents="lax">
@@ -1902,7 +1917,11 @@ limitations under the License.
                                         </xs:annotation>
                                         <xs:complexType>
                                             <xs:sequence minOccurs="0" maxOccurs="unbounded">
-                                                <xs:element name="url" type="xs:anyURI"/>
+                                                <xs:element name="url">
+                                                    <xs:simpleType>
+                                                        <xs:union memberTypes="xs:anyURI bom:bomLinkElementType"/>
+                                                    </xs:simpleType>
+                                                </xs:element>
                                             </xs:sequence>
                                         </xs:complexType>
                                     </xs:element>
@@ -1912,7 +1931,11 @@ limitations under the License.
                                         </xs:annotation>
                                         <xs:complexType>
                                             <xs:sequence minOccurs="0" maxOccurs="unbounded">
-                                                <xs:element name="url" type="xs:anyURI"/>
+                                                <xs:element name="url">
+                                                    <xs:simpleType>
+                                                        <xs:union memberTypes="xs:anyURI bom:bomLinkElementType"/>
+                                                    </xs:simpleType>
+                                                </xs:element>
                                             </xs:sequence>
                                         </xs:complexType>
                                     </xs:element>
@@ -2647,10 +2670,13 @@ limitations under the License.
                             </xs:annotation>
                             <xs:complexType>
                                 <xs:choice minOccurs="0" maxOccurs="unbounded">
-                                    <xs:element name="ref" type="bom:refType" minOccurs="0" maxOccurs="1">
+                                    <xs:element name="ref" minOccurs="0" maxOccurs="1">
                                         <xs:annotation>
                                             <xs:documentation>References a data component by the components bom-ref attribute</xs:documentation>
                                         </xs:annotation>
+                                        <xs:simpleType>
+                                            <xs:union memberTypes="bom:refLinkType bom:bomLinkElementType"/>
+                                        </xs:simpleType>
                                     </xs:element>
                                     <xs:element name="dataset" type="bom:componentDataType" minOccurs="0" maxOccurs="1" />
                                 </xs:choice>
@@ -3217,10 +3243,13 @@ limitations under the License.
     </xs:simpleType>
 
     <xs:complexType name="bomReferenceType">
-        <xs:attribute name="ref" type="bom:refType" use="required">
+        <xs:attribute name="ref" use="required">
             <xs:annotation>
-                <xs:documentation>References a component or service by the its bom-ref attribute</xs:documentation>
+                <xs:documentation>References a component or service by its bom-ref attribute</xs:documentation>
             </xs:annotation>
+            <xs:simpleType>
+                <xs:union memberTypes="bom:refLinkType bom:bomLinkType"/>
+            </xs:simpleType>
         </xs:attribute>
         <xs:anyAttribute namespace="##other" processContents="lax">
             <xs:annotation>
@@ -3574,10 +3603,13 @@ limitations under the License.
                         <xs:element name="target">
                             <xs:complexType>
                                 <xs:sequence minOccurs="0" maxOccurs="1">
-                                    <xs:element name="ref" type="bom:refType" minOccurs="1" maxOccurs="1">
+                                    <xs:element name="ref" minOccurs="1" maxOccurs="1">
                                         <xs:annotation>
                                             <xs:documentation>References a component or service by the objects bom-ref.</xs:documentation>
                                         </xs:annotation>
+                                        <xs:simpleType>
+                                            <xs:union memberTypes="bom:refLinkType bom:bomLinkElementType"/>
+                                        </xs:simpleType>
                                     </xs:element>
                                     <xs:element name="versions" minOccurs="0" maxOccurs="1">
                                         <xs:annotation>
@@ -5383,7 +5415,7 @@ limitations under the License.
                     </xs:annotation>
                 </xs:any>
             </xs:sequence>
-            <xs:attribute name="version" type="xs:integer" default="1">
+            <xs:attribute name="version" type="xs:positiveInteger" default="1">
                 <xs:annotation>
                     <xs:documentation>Whenever an existing BOM is modified, either manually or through automated
                         processes, the version of the BOM SHOULD be incremented by 1. When a system is presented with

tools/src/test/resources/1.5/invalid-component-ref-1.5.json

@@ -15,6 +15,12 @@
       "bom-ref": "123",
       "name": "acme-library",
       "version": "1.0.0"
+    },
+    {
+      "type": "library",
+      "bom-ref": "",
+      "name": "acme-library",
+      "version": "1.0.0"
     }
   ]
 }

tools/src/test/resources/1.5/invalid-component-ref-1.5.xml

@@ -6,6 +6,12 @@
             <version>1.0.0</version>
             <components>
                 <component type="library" bom-ref="123">
+                    <!-- duplicate value in attribute `bom-ref` -->
+                    <name>acme-library</name>
+                    <version>1.0.0</version>
+                </component>
+                <component type="library" bom-ref="">
+                    <!-- empty value in attribute `bom-ref` -->
                     <name>acme-library</name>
                     <version>1.0.0</version>
                 </component>

tools/src/test/resources/1.5/invalid-dependency-1.5.json

@@ -27,6 +27,12 @@
     {
       "dependsOn": []
     },
+    {
+      "ref": "",
+      "dependsOn": [
+        "library-a"
+      ]
+    },
     {
       "ref": "library-b",
       "dependsOn": [

tools/src/test/resources/1.5/invalid-dependency-1.5.xml

@@ -15,9 +15,17 @@
         </component>
     </components>
     <dependencies>
-        <dependency />
+        <dependency>
+            <!-- invalid: missing attribute `ref` -->
+        </dependency>
+        <dependency ref="">
+            <!-- invalid: attribute `ref` is empty -->
+            <dependency ref="library-a"/>
+        </dependency>
         <dependency ref="library-b">
-            <dependency ref="library-c"/>
+            <dependency ref="library-c">
+                <!-- valid -->
+            </dependency>
         </dependency>
     </dependencies>
 </bom>