[1.7] Added citation support and test cases. (#630)

## Changed
- Formulations may be used to describe how any referencable object
within the BOM came together, including components, services, metadata,
declarations, or the BOM itself.
  Before, it was restricted to components and services.

## Added
- Citations - describe how certain information in the BOM came together,
or were sourced from, or are asserted.


-----

TODO/DONE 
- [x] JSON schema modified
- [x] XML schema modified
- [x] ProtoBuf schema modified
- [x] JSON examples/test data crafted 
- [x] XML examples/test data crafted 
- [x] ProtoBuf examples/test data crafted

Author: stevespringett

schema/bom-1.7.proto

@@ -37,12 +37,14 @@ message Bom {
   repeated Annotation annotations = 11;
   // Specifies optional, custom, properties
   repeated Property properties = 12;
-  // Describes how a component or service was manufactured or deployed. This is achieved through the use of formulas, workflows, tasks, and steps, which declare the precise steps to reproduce along with the observed formulas describing the steps which transpired in the manufacturing process.
+  // Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself. This may encompass how the object was created, assembled, deployed, tested, certified, or otherwise brought into its present form. Common examples include software build pipelines, deployment processes, AI/ML model training, cryptographic key generation or certification, and third-party audits. Processes are modeled using declared and observed formulas, composed of workflows, tasks, and individual steps.
   repeated Formula formulation = 13;
   // The list of declarations which describe the conformance to standards. Each declaration may include attestations, claims, and evidence.
   repeated Declarations declarations = 14;
   // A collection of reusable objects that are defined and may be used elsewhere in the BOM.
   repeated Definition definitions = 15;
+  // A collection of attributions indicating which entity supplied information for specific fields within the BOM.
+  repeated Citation citations = 16;
 }
 
 enum Classification {
@@ -313,7 +315,7 @@ enum ExternalReferenceType {
   EXTERNAL_REFERENCE_TYPE_CONFIGURATION = 35;
   // Information used to substantiate a claim.
   EXTERNAL_REFERENCE_TYPE_EVIDENCE = 36;
-  // Describes how a component or service was manufactured or deployed.
+  // Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself.
   EXTERNAL_REFERENCE_TYPE_FORMULATION = 37;
   // The location where the source code distributable can be obtained. This is often an archive format such as zip or tar.gz. The source-distribution type complements the use of the version control (vcs) type.
   EXTERNAL_REFERENCE_TYPE_SOURCE_DISTRIBUTION = 38;
@@ -331,6 +333,8 @@ enum ExternalReferenceType {
   EXTERNAL_REFERENCE_TYPE_PATENT_FAMILY = 44;
   // References assertions made regarding patents associated with a component or service. Assertions distinguish between ownership, licensing, and other relevant interactions with patents.
   EXTERNAL_REFERENCE_TYPE_PATENT_ASSERTION = 45;
+  // 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 = 46;
 }
 
 enum HashAlg {
@@ -2613,3 +2617,39 @@ enum PatentAssertionType {
   // The patent or patent family is being used under a research or evaluation license.
   PATENT_ASSERTION_TYPE_RESEARCH_OR_EVALUATION = 8;
 }
+
+// Details a specific attribution of data within the BOM to a contributing entity or process.
+message Citation {
+  message Pointers {
+    // Users of other serialisation formats (e.g. XML) shall use the JSON Pointer format to ensure consistent field referencing across representations.
+    // Must contain at least 1 item.
+    repeated string pointer = 1;
+  }
+  message Expressions {
+    // Specifies a path expression used to locate a value within a BOM. The expression syntax shall conform to the format of the BOM's serialisation.
+    // Use [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) for JSON, [XPath](https://www.w3.org/TR/xpath/) for XML, and default to JSONPath for Protocol Buffers unless otherwise specified.
+    // Implementers shall ensure the expression is valid within the context of the applicable serialisation format. Use either "pointer" or "expression" but not both in this object.
+    // Must contain at least 1 item.
+    repeated string expression = 1;
+  }
+
+  // Optional unique identifier for the citation
+  optional string bom_ref = 1;
+  // Exactly one of the "pointers" or "expressions" elements must be present.
+  oneof target {
+    // One or more JSON Pointers(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.
+    Pointers pointers = 2;
+    // One or more path expressions used to locate values within a BOM.
+    Expressions expressions = 3;
+  }
+  // Timestamp when the attribution was made or the information was supplied.
+  google.protobuf.Timestamp timestamp = 4;
+  // The `bom-ref` of an object, such as a component, service, tool, organisational entity, or person that supplied the cited information.
+  // At least one of the "attributed_to" or "process" elements must be present.
+  optional string attributed_to = 5;
+  // The `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.
+  // At least one of the "attributed_to" or "process" elements must be present.
+  optional string process = 6;
+  // An optional description or comment about the context or quality of the data attribution.
+  optional string note = 7;
+}

schema/bom-1.7.schema.json

@@ -100,7 +100,7 @@
       "items": {"$ref": "#/definitions/formula"},
       "uniqueItems": true,
       "title": "Formulation",
-      "description": "Describes how a component or service was manufactured or deployed. This is achieved through the use of formulas, workflows, tasks, and steps, which declare the precise steps to reproduce along with the observed formulas describing the steps which transpired in the manufacturing process."
+      "description": "Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself. This may encompass how the object was created, assembled, deployed, tested, certified, or otherwise brought into its present form. Common examples include software build pipelines, deployment processes, AI/ML model training, cryptographic key generation or certification, and third-party audits. Processes are modeled using declared and observed formulas, composed of workflows, tasks, and individual steps."
     },
     "declarations": {
       "type": "object",
@@ -527,6 +527,13 @@
         }
       }
     },
+    "citations": {
+      "type": "array",
+      "items": {"$ref": "#/definitions/citation"},
+      "uniqueItems": true,
+      "title": "Citations",
+      "description": "A collection of attributions indicating which entity supplied information for specific fields within the BOM."
+    },
     "properties": {
       "type": "array",
       "title": "Properties",
@@ -1900,6 +1907,7 @@
             "patent",
             "patent-family",
             "patent-assertion",
+            "citation",
             "other"
           ],
           "meta:enum": {
@@ -1925,7 +1933,7 @@
             "log": "A record of events that occurred in a computer system or application, such as problems, errors, or information on current operations.",
             "configuration": "Parameters or settings that may be used by other components or services.",
             "evidence": "Information used to substantiate a claim.",
-            "formulation": "Describes how a component or service was manufactured or deployed.",
+            "formulation": "Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself.",
             "attestation": "Human or machine-readable statements containing facts, evidence, or testimony.",
             "threat-model": "An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format.",
             "adversary-model": "The defined assumptions, goals, and capabilities of an adversary.",
@@ -1948,6 +1956,7 @@
             "patent": "References information about patents which may be defined in human-readable documents or in machine-readable formats such as CycloneDX or ST.96. For detailed patent information or to reference the information provided directly by patent offices, it is recommended to leverage standards from the World Intellectual Property Organization (WIPO) such as [ST.96](https://www.wipo.int/standards/en/st96).",
             "patent-family": "References information about a patent family which may be defined in human-readable documents or in machine-readable formats such as CycloneDX or ST.96. A patent family is a group of related patent applications or granted patents that cover the same or similar invention. For detailed patent family information or to reference the information provided directly by patent offices, it is recommended to leverage standards from the World Intellectual Property Organization (WIPO) such as [ST.96](https://www.wipo.int/standards/en/st96).",
             "patent-assertion" : "References assertions made regarding patents associated with a component or service. Assertions distinguish between ownership, licensing, and other relevant interactions with patents.",
+            "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."
           }
         },
@@ -6105,6 +6114,75 @@
           "$ref": "#/definitions/patentFilingDate"
         }
       }
+    },
+    "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"
+        },
+        "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.\nUsers 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.\nExactly one of the \"pointers\" or \"expressions\" elements must be present."
+        },
+        "expressions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "title": "Path Expression",
+            "description": "Specifies a path expression used to locate a value within a BOM. The expression syntax shall conform to the format of the BOM's serialisation.\nUse [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) for JSON, [XPath](https://www.w3.org/TR/xpath/) for XML, and default to JSONPath for Protocol Buffers unless otherwise specified.\nImplementers shall ensure the expression is valid within the context of the applicable serialisation format."
+          },
+          "minItems": 1,
+          "title": "Path Expressions",
+          "description": "One or more path expressions used to locate values within a BOM.\nExactly one of the \"pointers\" or \"expressions\" elements must be present."
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "title": "Timestamp",
+          "description": "The date and time when the attribution was made or the information was supplied."
+        },
+        "attributedTo": {
+          "$ref": "#/definitions/refLinkType",
+          "title": "Attributed To",
+          "description": "The `bom-ref` of an object, such as a component, service, tool, organisational entity, or person that supplied the cited information.\nAt least one of the \"attributedTo\" or \"process\" elements must be present."
+        },
+        "process": {
+          "$ref": "#/definitions/refLinkType",
+          "title": "Process Reference",
+          "description": "The `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.\nAt least one of the \"attributedTo\" or \"process\" elements must be present."
+        },
+        "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": ["timestamp"],
+      "anyOf": [
+        { "required": ["attributedTo"] },
+        { "required": ["process"] }
+      ],
+      "oneOf": [
+        { "required": ["pointers"] },
+        { "required": ["expressions"] }
+      ]
     }
   }
 }