Added support for conditional components and associated unit tests

schema/2.0/model/cyclonedx-component-2.0.schema.json

@@ -7,7 +7,7 @@
   "$defs": {
     "components": {
       "type": "array",
-      "items": {"$ref": "#/$defs/component"},
+      "items": {"$ref": "#/$defs/componentOrChoice"},
       "uniqueItems": true,
       "title": "Components"
     },
@@ -235,10 +235,10 @@
         },
         "components": {
           "type": "array",
-          "items": {"$ref": "#/$defs/component"},
+          "items": {"$ref": "#/$defs/componentOrChoice"},
           "uniqueItems": true,
           "title": "Components",
-          "description": "A list of software and hardware components included in the parent component. This is not a dependency tree. It provides a way to specify a hierarchical representation of component assemblies, similar to system → subsystem → parts assembly in physical supply chains."
+          "description": "A list of software and hardware components included in the parent component. Entries may be concrete components or component-choice wrappers expressing conditional or alternate relationships. This is not a dependency tree. It provides a way to specify a hierarchical representation of component assemblies, similar to system → subsystem → parts assembly in physical supply chains."
         },
         "evidence": {
           "$ref": "#/$defs/componentEvidence",
@@ -299,6 +299,78 @@
         }
       ]
     },
+    "componentOrChoice": {
+      "title": "Component or Component Choice",
+      "description": "An entry in a components array. May be a concrete component, or a component-choice wrapper that expresses a conditional or alternate relationship between two or more components. The discriminator is the `type` property: when `type` is `component-choice`, the entry shall conform to the `componentChoice` schema; otherwise it shall conform to the `component` schema.",
+      "oneOf": [
+        { "$ref": "#/$defs/component" },
+        { "$ref": "#/$defs/componentChoice" }
+      ]
+    },
+    "componentChoice": {
+      "type": "object",
+      "title": "Component Choice",
+      "description": "A wrapper that expresses a conditional or alternate relationship between two or more components. Use to model approved alternates, multi-sourced parts, build variants, and required component groups in physical device bills of materials.",
+      "required": [
+        "type",
+        "operator",
+        "components"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "component-choice",
+          "title": "Type",
+          "description": "Discriminator for a component-choice entry. The value shall be the literal string `component-choice`."
+        },
+        "bom-ref": {
+          "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType",
+          "title": "BOM Reference",
+          "description": "An identifier which can be used to reference the component-choice elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links."
+        },
+        "name": {
+          "type": "string",
+          "title": "Name",
+          "description": "A display name for the choice. Typically corresponds to a reference designator, a design intent name, or a description of the role the chosen component fulfils.",
+          "examples": ["2N2222 or PN2222A Transistor", "U1 5V LDO Regulator"]
+        },
+        "description": {
+          "type": "string",
+          "title": "Description",
+          "description": "A description of the choice and the rationale behind the alternates."
+        },
+        "operator": {
+          "type": "string",
+          "enum": [
+            "OR",
+            "XOR",
+            "AND"
+          ],
+          "meta:enum": {
+            "OR":  "Any non-empty subset of the contained components may be installed. Use for approved alternates where more than one may legitimately appear in a given instance.",
+            "XOR": "Exactly one of the contained components is installed in any single instance. Use for approved alternates that are mutually exclusive per instance, while the population of units may include multiple alternates across sourcing.",
+            "AND": "All of the contained components are installed together as a group. Use for tightly coupled component sets such as a transceiver and its required matching balun."
+          },
+          "title": "Operator",
+          "description": "The logical relationship between the contained components."
+        },
+        "components": {
+          "type": "array",
+          "minItems": 2,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/componentOrChoice" },
+          "title": "Components",
+          "description": "Two or more alternate or grouped entries. Each entry may itself be a component-choice to express nested alternates, such as a choice between kits."
+        },
+        "properties": {
+          "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties"
+        },
+        "externalReferences": {
+          "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReferences"
+        }
+      }
+    },
     "version": {
       "description": "A single disjunctive version identifier, for a component or service.",
       "type": "string",

tools/src/test/resources/2.0/invalid-component-choice-additional-property-2.0.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "type": "device",
+      "name": "Acme Product"
+    }
+  },
+  "components": [
+    {
+      "type": "component-choice",
+      "name": "Transistor Choice",
+      "description": "unexpected property `supplier`",
+      "operator": "XOR",
+      "supplier": { "name": "`supplier` is not allowed on a choice wrapper" },
+      "components": [
+        { "type": "device", "name": "Transistor A" },
+        { "type": "device", "name": "Transistor B" }
+      ]
+    }
+  ]
+}

tools/src/test/resources/2.0/invalid-component-choice-bad-operator-2.0.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "type": "device",
+      "name": "Acme Product"
+    }
+  },
+  "components": [
+    {
+      "type": "component-choice",
+      "name": "Transistor Choice",
+      "description": "unexpected value for `operator`",
+      "operator": "NAND",
+      "components": [
+        { "type": "device", "name": "Transistor A" },
+        { "type": "device", "name": "Transistor B" }
+      ]
+    }
+  ]
+}

tools/src/test/resources/2.0/invalid-component-choice-missing-name-2.0.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "type": "device",
+      "name": "Acme Product"
+    }
+  },
+  "components": [
+    {
+      "type": "component-choice",
+      "operator": "XOR",
+      "components": [
+        { "type": "device", "name": "Transistor A" },
+        { "type": "device", "name": "Transistor B" }
+      ]
+    }
+  ]
+}

tools/src/test/resources/2.0/invalid-component-choice-missing-operator-2.0.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "type": "device",
+      "name": "Acme Product"
+    }
+  },
+  "components": [
+    {
+      "type": "component-choice",
+      "name": "Transistor Choice",
+      "description": "missing property `operator`",
+      "components": [
+        { "type": "device", "name": "Transistor A" },
+        { "type": "device", "name": "Transistor B" }
+      ]
+    }
+  ]
+}

tools/src/test/resources/2.0/invalid-component-choice-optional-operator-2.0.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "type": "device",
+      "name": "Acme Product"
+    }
+  },
+  "components": [
+    {
+      "type": "component-choice",
+      "name": "JP2 Debug Header",
+      "description": "invalid value for `operator`",
+      "operator": "OPTIONAL",
+      "components": [
+        { "type": "device", "name": "Debug Header A" },
+        { "type": "device", "name": "Debug Header B" }
+      ]
+    }
+  ]
+}

tools/src/test/resources/2.0/invalid-component-choice-too-few-2.0.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "type": "device",
+      "name": "Acme Product"
+    }
+  },
+  "components": [
+    {
+      "type": "component-choice",
+      "name": "Transistor Choice",
+      "description": "`components` must list at least two items",
+      "operator": "XOR",
+      "components": [
+        { "type": "device", "name": "Lone Transistor" }
+      ]
+    }
+  ]
+}

tools/src/test/resources/2.0/valid-component-choice-and-2.0.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "bom-ref": "rf-board",
+      "type": "device",
+      "name": "RF Front End Board"
+    }
+  },
+  "components": [
+    {
+      "type": "component-choice",
+      "name": "Transceiver and Matching Balun",
+      "description": "The transceiver and its matching balun are installed together. Selecting one without the other yields a non-functional radio.",
+      "operator": "AND",
+      "components": [
+        {
+          "type": "device",
+          "name": "2.4GHz RF Transceiver",
+          "supplier": { "name": "Acme RF" }
+        },
+        {
+          "type": "device",
+          "name": "Matching Balun for 2.4GHz Transceiver",
+          "supplier": { "name": "Acme RF" }
+        }
+      ]
+    }
+  ]
+}

tools/src/test/resources/2.0/valid-component-choice-in-nested-components-2.0.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "bom-ref": "main-board",
+      "type": "device",
+      "name": "Main Board"
+    }
+  },
+  "components": [
+    {
+      "type": "device",
+      "name": "Power Management Sub-board",
+      "components": [
+        {
+          "type": "device",
+          "name": "Input Diode"
+        },
+        {
+          "type": "component-choice",
+          "name": "U1 5V LDO Regulator",
+          "operator": "XOR",
+          "components": [
+            {
+              "type": "device",
+              "name": "LD1117S50TR",
+              "supplier": { "name": "STMicroelectronics" }
+            },
+            {
+              "type": "device",
+              "name": "AMS1117-5.0",
+              "supplier": { "name": "Advanced Monolithic Systems" }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

tools/src/test/resources/2.0/valid-component-choice-nested-2.0.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+  "specFormat": "CycloneDX",
+  "specVersion": "2.0",
+  "version": 1,
+  "metadata": {
+    "component": {
+      "bom-ref": "radio-module",
+      "type": "device",
+      "name": "Radio Module"
+    }
+  },
+  "components": [
+    {
+      "type": "component-choice",
+      "name": "Radio Subsystem",
+      "description": "Choose exactly one radio subsystem. Each option is itself a tightly coupled group of transceiver and matching balun that must be installed together.",
+      "operator": "XOR",
+      "components": [
+        {
+          "type": "component-choice",
+          "name": "2.4GHz Radio Group",
+          "operator": "AND",
+          "components": [
+            {
+              "type": "device",
+              "name": "2.4GHz Transceiver",
+              "supplier": { "name": "Acme RF" }
+            },
+            {
+              "type": "device",
+              "name": "2.4GHz Balun",
+              "supplier": { "name": "Acme RF" }
+            }
+          ]
+        },
+        {
+          "type": "component-choice",
+          "name": "Sub-GHz Radio Group",
+          "operator": "AND",
+          "components": [
+            {
+              "type": "device",
+              "name": "915MHz Transceiver",
+              "supplier": { "name": "Beta RF" }
+            },
+            {
+              "type": "device",
+              "name": "915MHz Balun",
+              "supplier": { "name": "Beta RF" }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}