Component Compositions

Introduction

Component compositions in CycloneDX are a mechanism to describe the completeness of the inventory of components within a BOM. This is particularly important when representing the metadata component, as it defines the overall scope and coverage of the BOM. Compositions provide insight into whether the listed components represent a complete, partial, or unknown inventory, offering critical transparency into the accuracy and reliability of the BOM data.

By defining the completeness status, component compositions help consumers of the BOM understand the level of confidence they can place in the provided information. For instance, a BOM with a "complete" composition indicates that all relevant components have been identified and included, whereas an "incomplete" composition might highlight gaps or exclusions. This distinction is vital for risk management, compliance, and decision-making processes, especially when integrating the BOM into larger workflows or assessments.

Highlighted fields

PropertyUsage Description
aggregateDescribes the overall completeness of the inventory for the component, such as complete or incomplete.
assembliesLists the components or services that are structurally part of this component.
This example describes a complete inventory of the "Acme Application" and the dependency relationships. The BOM includes three libraries, where "Library A" and "Library B" are direct dependencies of the application, and "Library B" further depends on "Library C." The composition property indicates that both the inventory and dependency relationships are complete.

Examples

{
  "$schema": "http://cyclonedx.org/schema/bom-1.6.schema.json",
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
  "version": 1,
   "metadata": {
     "component": {
       "bom-ref": "acme-application",
       "type": "application",
       "name": "Acme Application",
       "version": "1.0.0"
     }
   },
  "components": [
    {
      "bom-ref": "library-a",
      "type": "library",
      "name": "Library A",
      "version": "2.5.1"
    },
    {
      "bom-ref": "library-b",
      "type": "library",
      "name": "Library B",
      "version": "3.3.0"
    },
    {
      "bom-ref": "library-c",
      "type": "library",
      "name": "Library C",
      "version": "3.1.3"
    }
  ],
  "dependencies": [
    {
      "ref": "acme-application",
      "dependsOn": [
        "library-a",
        "library-b"
      ]
    },
    {
      "ref": "library-b",
      "dependsOn": [
        "library-c"
      ]
    }
  ],
  "compositions": [
    {
      "aggregate": "complete",
      "assemblies": [
        "acme-application"
      ],
      "dependencies": [
        "acme-application"
      ]
    }
  ]
}

Authoritative Guide