Extensibility through CycloneDX Properties

Introduction

CycloneDX properties provide a flexible mechanism to extend the specification with custom name-value pairs, enabling the inclusion of metadata tailored to specific use cases. This allows organizations to document unique attributes not covered by the predefined CycloneDX schema. Properties can be applied at multiple levels within a BOM, such as the BOM itself, components, or services, offering granular control over how additional information is captured and represented.

CycloneDX properties are serialization format agnostic, meaning the same extensibility mechanism works seamlessly across JSON, XML, and Protocol Buffers. This approach is particularly advantageous because it enables CycloneDX to maintain a hardened JSON schema for high-assurance environments. While JSON Schema itself is not inherently extensible, CycloneDX properties provide a solution that balances extensibility with the strict validation required in high-assurance environments.

To further support interoperability, CycloneDX includes a property taxonomy that defines standardized names for commonly used properties. This taxonomy comprises a formal set of registered namespaces, including cdx for pre-defined CycloneDX properties and others contributed by the community. These namespaces ensure properties are globally unique and clearly scoped, promoting consistency and interoperability across implementations. The optional property registration process allows organizations to define and publicly document their custom namespaces and properties, fostering collaboration and standardization. This structured approach enables CycloneDX to balance flexibility and extensibility while maintaining clarity and consistency across tools and environments.

Examples

{
  "$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": {
    "properties": [
      {
        "name": "Foo",
        "value": "Bar"
      },
      {
        "name": "Foo",
        "value": "You"
      },
      {
        "name": "Foo",
        "value": "Two"
      },
      {
        "name": "Bar",
        "value": "Foo"
      }
    ]
  },
  "components": [
    {
      "type": "library",
      "name": "acme-library",
      "version": "1.0.0",
      "properties": [
        {
          "name": "Foo",
          "value": "456"
        },
        {
          "name": "Bar",
          "value": "DEF"
        }
      ]
    }
  ],
  "services": [
    {
      "bom-ref": "b2a46a4b-8367-4bae-9820-95557cfe03a8",
      "group": "org.partner",
      "name": "Stock ticker service",
      "endpoints": [
        "https://partner.org/api/v1/stock"
      ],
      "properties": [
        {
          "name": "Foo",
          "value": "789"
        },
        {
          "name": "Bar",
          "value": "GHI"
        }
      ]
    }
  ]
}

Authoritative Guide