feat: add custom properties to external references (#610)

With this property external references can be annotated with additional
metadata in a machine-readable format.

As discussed in #608 this adds support for custom properties in external
references.


fixes #608

Author: jkowalleck

schema/bom-1.7.proto

@@ -230,6 +230,8 @@ message ExternalReference {
   optional string comment = 3;
   // Optional integrity hashes for the external resource content
   repeated Hash hashes = 4;
+  // Specifies optional, custom, properties
+  repeated Property properties = 5;
 }
 
 enum ExternalReferenceType {

schema/bom-1.7.schema.json

@@ -1883,6 +1883,12 @@
           "items": {"$ref": "#/definitions/hash"},
           "title": "Hashes",
           "description": "The hashes of the external reference (if applicable)."
+        },
+        "properties": {
+          "type": "array",
+          "title": "Properties",
+          "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.",
+          "items": {"$ref": "#/definitions/property"}
         }
       }
     },

schema/bom-1.7.xsd

@@ -1682,6 +1682,16 @@ limitations under the License.
                     </xs:sequence>
                 </xs:complexType>
             </xs:element>
+            <xs:element name="properties" type="bom:propertiesType" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>Provides the ability to document properties in a name/value store.
+                        This provides flexibility to include data not officially supported in the standard
+                        without having to use additional namespaces or create extensions. Property names
+                        of interest to the general public are encouraged to be registered in the
+                        CycloneDX Property Taxonomy - https://github.com/CycloneDX/cyclonedx-property-taxonomy.
+                        Formal registration is optional.</xs:documentation>
+                </xs:annotation>
+            </xs:element>
         </xs:sequence>
         <xs:attribute name="type" type="bom:externalReferenceType" use="required">
             <xs:annotation>

tools/src/test/resources/1.7/valid-external-reference-properties-1.7.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://cyclonedx.org/schema/bom-1.7.schema.json",
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.7",
+  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
+  "version": 1,
+  "components": [
+    {
+      "type": "application",
+      "name": "dummy",
+      "description": "this component has an external reference with properties",
+      "externalReferences": [
+        {
+          "type": "component-analysis-report",
+          "url": "http://example.com/extref/component-analysis-report",
+          "properties": [
+            {
+              "name": "author",
+              "value": "John Doe"
+            },
+            {
+              "name": "timestamp",
+              "value": "2025-01-27T12:27:26Z"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

tools/src/test/resources/1.7/valid-external-reference-properties-1.7.textproto

@@ -0,0 +1,23 @@
+# proto-file: schema/bom-1.7.proto
+# proto-message: Bom
+
+spec_version: "1.7"
+version: 1
+serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79"
+components {
+  type: CLASSIFICATION_APPLICATION
+  name: "dummy"
+  description: "this component has an external reference with properties"
+  external_references {
+    type: EXTERNAL_REFERENCE_TYPE_COMPONENT_ANALYSIS_REPORT
+    url: "http://example.com/extref/component-analysis-report"
+    properties {
+      name: "author"
+      value: "John Doe"
+    }
+    properties {
+      name: "timestamp"
+      value: "2025-01-27T12:27:26Z"
+    }
+  }
+}

tools/src/test/resources/1.7/valid-external-reference-properties-1.7.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1" xmlns="http://cyclonedx.org/schema/bom/1.7">
+    <components>
+        <component type="application">
+            <name>dummy</name>
+            <description>this component has an external reference with properties</description>
+            <externalReferences>
+                <reference type="component-analysis-report">
+                    <url>http://example.com/extref/component-analysis-report</url>
+                    <properties>
+                        <property name="author">John Doe</property>
+                        <property name="timestamp">2025-01-27T12:27:26Z</property>
+                    </properties>
+                </reference>
+            </externalReferences>
+        </component>
+    </components>
+</bom>