diff --git a/schema/bom-1.7.proto b/schema/bom-1.7.proto
index 999dccba..9af2dcb9 100644
--- a/schema/bom-1.7.proto
+++ b/schema/bom-1.7.proto
@@ -43,6 +43,8 @@ message Bom {
repeated Declarations declarations = 14;
// A collection of reusable objects that are defined and may be used elsewhere in the BOM.
repeated Definition definitions = 15;
+ // Details a specific attribution of data within the BOM to a contributing entity or process.
+ repeated Citation citations = 16;
}
enum Classification {
@@ -320,6 +322,8 @@ enum ExternalReferenceType {
EXTERNAL_REFERENCE_TYPE_RFC_9116 = 41;
// Reference to release notes
EXTERNAL_REFERENCE_TYPE_RELEASE_NOTES = 42;
+ // A reference to external citations applicable to the object identified by this BOM entry or the BOM itself. When used with a BOM-Link, this allows offloading citations into a separate CycloneDX BOM.
+ EXTERNAL_REFERENCE_TYPE_CITATION = 43;
}
enum HashAlg {
@@ -2393,3 +2397,18 @@ message CryptoProperties {
// The object identifier (OID) of the cryptographic asset.
optional string oid = 6;
}
+
+message Citation {
+ // Optional unique identifier for the citation
+ optional string bom_ref = 1;
+ // One or more JSON Pointers(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.
+ repeated string pointer = 2;
+ // Timestamp when the attribution was made or the information was supplied.
+ google.protobuf.Timestamp timestamp = 3;
+ // The `bom-ref` of an object, such as a component, service, organisational entity, or person that supplied the cited information.
+ optional string attributed_to = 4;
+ // An optional `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data.
+ optional string process = 5;
+ // An optional description or comment about the context or quality of the data attribution.
+ optional string note = 6;
+}
diff --git a/schema/bom-1.7.schema.json b/schema/bom-1.7.schema.json
index 60459495..d5667bf5 100644
--- a/schema/bom-1.7.schema.json
+++ b/schema/bom-1.7.schema.json
@@ -517,6 +517,13 @@
}
}
},
+ "citations": {
+ "type": "array",
+ "items": {"$ref": "#/definitions/citation"},
+ "uniqueItems": true,
+ "title": "Citations",
+ "description": "A list of attributions indicating which entity supplied information for specific fields within the BOM."
+ },
"properties": {
"type": "array",
"title": "Properties",
@@ -1805,6 +1812,7 @@
"electronic-signature",
"digital-signature",
"rfc-9116",
+ "citation",
"other"
],
"meta:enum": {
@@ -1850,6 +1858,7 @@
"electronic-signature": "An e-signature is commonly a scanned representation of a written signature or a stylized script of the person's name.",
"digital-signature": "A signature that leverages cryptography, typically public/private key pairs, which provides strong authenticity verification.",
"rfc-9116": "Document that complies with [RFC 9116](https://www.ietf.org/rfc/rfc9116.html) (A File Format to Aid in Security Vulnerability Disclosure)",
+ "citation": "A reference to external citations applicable to the object identified by this BOM entry or the BOM itself. When used with a BOM-Link, this allows offloading citations into a separate CycloneDX BOM.",
"other": "Use this if no other types accurately describe the purpose of the external reference."
}
},
@@ -5725,6 +5734,60 @@
"translation",
"object-detection"
]
+ },
+ "citation": {
+ "type": "object",
+ "title": "Citation",
+ "description": "Details a specific attribution of data within the BOM to a contributing entity or process.",
+ "additionalProperties": false,
+ "properties": {
+ "bom-ref": {
+ "$ref": "#/definitions/refType",
+ "title": "BOM Reference"
+ },
+ "attributedTo": {
+ "$ref": "#/definitions/refLinkType",
+ "title": "Attributed To",
+ "description": "The `bom-ref` of an object, such as a component, service, organisational entity, or person that supplied the cited information."
+ },
+ "pointers": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "title": "Field Reference",
+ "description": "A [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM field to which the attribution applies. Users of other serialisation formats (e.g. XML) shall use the JSON Pointer format to ensure consistent field referencing across representations."
+ },
+ "minItems": 1,
+ "title": "Field References",
+ "description": "One or more [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies."
+ },
+ "timestamp": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Timestamp",
+ "description": "The date and time when the attribution was made or the information was supplied."
+ },
+ "process": {
+ "$ref": "#/definitions/refLinkType",
+ "title": "Process Reference",
+ "description": "An optional `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data."
+ },
+ "note": {
+ "type": "string",
+ "title": "Note",
+ "description": "An optional description or comment about the context or quality of the data attribution."
+ },
+ "signature": {
+ "$ref": "#/definitions/signature",
+ "title": "Signature",
+ "description": "An optional digital signature verifying the authenticity or integrity of the attribution."
+ }
+ },
+ "required": ["pointers", "timestamp"],
+ "anyOf": [
+ { "required": ["attributedTo"] },
+ { "required": ["process"] }
+ ]
}
}
}
diff --git a/schema/bom-1.7.xsd b/schema/bom-1.7.xsd
index dfc9eaa5..6ec52e46 100644
--- a/schema/bom-1.7.xsd
+++ b/schema/bom-1.7.xsd
@@ -1578,6 +1578,11 @@ limitations under the License.
Document that complies with RFC-9116 (A File Format to Aid in Security Vulnerability Disclosure)
+
+
+ A reference to external citations applicable to the object identified by this BOM entry or the BOM itself. When used with a BOM-Link, this allows offloading citations into a separate CycloneDX BOM.
+
+
Use this if no other types accurately describe the purpose of the external reference
@@ -8349,6 +8354,90 @@ limitations under the License.
+
+
+
+
+
+ Details a specific attribution of data within the BOM to a contributing entity or process.
+
+
+
+
+
+
+
+
+
+
+
+ One or more JSON Pointers(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.
+
+
+
+
+
+
+
+ A JSON Pointer(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM field to which the attribution applies. Users of other serialisation formats (e.g. XML) shall use the JSON Pointer format to ensure consistent field referencing across representations.
+
+
+
+
+
+
+
+
+
+ The date and time when the attribution was made or the information was supplied.
+
+
+
+
+
+
+ The `bom-ref` of an object, such as a component, service, organisational entity, or person that supplied the cited information.
+
+
+
+
+
+
+ An optional `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data.
+
+
+
+
+
+
+ An optional description or comment about the context or quality of the data attribution.
+
+
+
+
+
+
+ Allows any undeclared elements as long as the elements are placed in a different namespace.
+
+
+
+
+
+
+
+ An optional identifier which can be used to reference the object elsewhere in the BOM.
+ Uniqueness is enforced within all elements and children of the root-level bom element.
+
+
+
+
+
+ User-defined attributes may be used on this element as long as they
+ do not have the same name as an existing attribute used by the schema.
+
+
+
+
@@ -8430,6 +8519,11 @@ limitations under the License.
+
+
+ A list of attributions indicating which entity supplied information for specific fields within the BOM.
+
+
diff --git a/tools/src/test/resources/1.7/valid-citations-1.7.json b/tools/src/test/resources/1.7/valid-citations-1.7.json
new file mode 100644
index 00000000..e3e53e54
--- /dev/null
+++ b/tools/src/test/resources/1.7/valid-citations-1.7.json
@@ -0,0 +1,77 @@
+{
+ "$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,
+ "metadata": {
+ "timestamp": "2025-05-01T14:23:00Z",
+ "authors": [
+ {
+ "bom-ref": "person-1",
+ "name": "Alice Example",
+ "email": "alice@example.com"
+ }
+ ]
+ },
+ "components": [
+ {
+ "type": "library",
+ "bom-ref": "component-1",
+ "name": "example-lib",
+ "version": "1.2.3",
+ "licenses": [
+ {
+ "license": {
+ "id": "Apache-2.0"
+ }
+ }
+ ]
+ }
+ ],
+ "citations": [
+ {
+ "bom-ref": "citation-1",
+ "pointers": [ "/components/0/name" ],
+ "timestamp": "2025-05-01T14:00:00Z",
+ "attributedTo": "person-1",
+ "note": "Manually entered by Alice Example"
+ },
+ {
+ "bom-ref": "citation-2",
+ "pointers": [ "/components/0/licenses/0/license/id" ],
+ "timestamp": "2025-05-01T14:05:00Z",
+ "attributedTo": "scan-tool-1",
+ "process": "task-license-scan",
+ "note": "Auto-detected by license scanner tool"
+ }
+ ],
+ "formulation": [
+ {
+ "components": [
+ {
+ "bom-ref": "scan-tool-1",
+ "type": "application",
+ "name": "My Scan Tool"
+ }
+ ],
+ "bom-ref": "workflow-1",
+ "workflows": [
+ {
+ "bom-ref": "workflow-1",
+ "uid": "259bae74-5ec4-4de8-9386-c91b1f7719b8",
+ "name": "My workflow",
+ "tasks": [
+ {
+ "bom-ref": "task-license-scan",
+ "uid": "6d75f8d6-a008-41cf-8b65-c4129fc249f9",
+ "taskTypes": [ "scan" ],
+ "description": "License scan of the source files using OpenSourceScanner v2.1"
+ }
+ ],
+ "taskTypes": [ "scan" ]
+ }
+ ]
+ }
+ ]
+}
diff --git a/tools/src/test/resources/1.7/valid-citations-1.7.textproto b/tools/src/test/resources/1.7/valid-citations-1.7.textproto
new file mode 100644
index 00000000..7062652a
--- /dev/null
+++ b/tools/src/test/resources/1.7/valid-citations-1.7.textproto
@@ -0,0 +1,75 @@
+# 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"
+
+metadata {
+ timestamp {
+ seconds: 1746118980
+ nanos: 0
+ }
+ authors {
+ bom_ref: "person-1"
+ name: "Alice Example"
+ email: "alice@example.com"
+ }
+}
+
+components {
+ bom_ref: "component-1"
+ type: CLASSIFICATION_LIBRARY
+ name: "example-lib"
+ version: "1.2.3"
+ licenses {
+ license {
+ id: "Apache-2.0"
+ }
+ }
+}
+
+citations [
+ {
+ bom_ref: "citation-1"
+ pointer: "/components/0/name"
+ timestamp: {
+ seconds: 1746108000
+ nanos: 0
+ }
+ attributed_to: "person-1"
+ note: "Manually entered by Alice Example"
+ },
+ {
+ bom_ref: "citation-2"
+ pointer: "/components/0/licenses/0/license/id"
+ timestamp: {
+ seconds: 1746108000
+ nanos: 0
+ }
+ attributed_to: "scan-tool-1"
+ process: "task-license-scan"
+ note: "Auto-detected by license scanner tool"
+ }
+]
+
+formulation {
+ bom_ref: "workflow-1"
+ components {
+ bom_ref: "scan-tool-1"
+ type: CLASSIFICATION_APPLICATION
+ name: "My Scan Tool"
+ }
+ workflows {
+ bom_ref: "workflow-1"
+ uid: "259bae74-5ec4-4de8-9386-c91b1f7719b8"
+ name: "My workflow"
+ taskTypes: TASK_TYPE_SCAN
+ tasks {
+ bom_ref: "task-license-scan"
+ uid: "6d75f8d6-a008-41cf-8b65-c4129fc249f9"
+ taskTypes: TASK_TYPE_SCAN
+ description: "License scan of the source files using OpenSourceScanner v2.1"
+ }
+ }
+}
diff --git a/tools/src/test/resources/1.7/valid-citations-1.7.xml b/tools/src/test/resources/1.7/valid-citations-1.7.xml
new file mode 100644
index 00000000..8536b51c
--- /dev/null
+++ b/tools/src/test/resources/1.7/valid-citations-1.7.xml
@@ -0,0 +1,71 @@
+
+
+
+ 2025-05-01T14:23:00Z
+
+
+ Alice Example
+ alice@example.com
+
+
+
+
+
+ example-lib
+ 1.2.3
+
+
+ Apache-2.0
+
+
+
+
+
+
+
+
+ My Scan Tool
+
+
+
+
+ 259bae74-5ec4-4de8-9386-c91b1f7719b8
+ My workflow
+
+
+ 6d75f8d6-a008-41cf-8b65-c4129fc249f9
+ License scan of the source files using OpenSourceScanner v2.1
+
+ scan
+
+
+
+
+ scan
+
+
+
+
+
+
+
+
+ /components/0/name
+
+ 2025-05-01T14:00:00Z
+ person-1
+ Manually entered by Alice Example
+
+
+
+ /components/0/licenses/0/license/id
+
+ 2025-05-01T14:05:00Z
+ scan-tool-1
+ task-license-scan
+ Auto-detected by license scanner tool
+
+
+