Software Dependencies

Introduction

Software dependencies are the foundational building blocks of modern application development. They include pre-built libraries, frameworks, and tools, with the majority being open source components. Dependencies can be direct, explicitly used by an application, or transitive, where dependencies themselves rely on other components.

CycloneDX provides the ability to describe components and their dependency on other components. This relies on a components bom-ref to associate the component to the dependency element in the graph. The only requirement for bom-ref is that it is unique within the BOM. Package URL (PURL) is an ideal choice for bom-ref as it will be both unique and readable. If PURL is not an option or not all components represented in the BOM contain a PURL, then UUID is recommended.

Highlighted fields

PropertyUsage Description
bom-refA unique identifier within the BOM used to reference a specific component or service elsewhere in the document, enabling precise cross-referencing and relationships.
refIdentifies the component or service being described, which may depend on other components or services.
dependsOnLists the bom-ref identifiers of components or services that the described component or service depends on.
Components or services that do not have their own dependencies must be declared as empty elements within the graph. Components or services that are not represented in the dependency graph may have unknown dependencies. It is recommended that implementations assume this to be opaque and not an indicator of an object being dependency-free. It is recommended to leverage compositions to indicate unknown dependency graphs.
The example describes the "Acme Application" and its dependencies. The dependencies include "web-framework" and "persistence," which both rely on "common-util," illustrating a complete hierarchy of direct and transitive dependencies.

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-app",
      "type": "application",
      "name": "Acme Application",
      "version": "9.1.1"
    }
  },
  "components": [
    {
      "bom-ref": "pkg:maven/org.acme/[email protected]",
      "type": "library",
      "group": "org.acme",
      "name": "web-framework",
      "version": "1.0.0",
      "purl": "pkg:maven/org.acme/[email protected]"
    },
    {
      "bom-ref": "pkg:maven/org.acme/[email protected]",
      "type": "library",
      "group": "org.acme",
      "name": "persistence",
      "version": "3.1.0",
      "purl": "pkg:maven/org.acme/[email protected]"
    },
    {
      "bom-ref": "pkg:maven/org.acme/[email protected]",
      "type": "library",
      "group": "org.acme",
      "name": "common-util",
      "version": "3.0.0",
      "purl": "pkg:maven/org.acme/[email protected]"
    }
  ],
  "dependencies": [
    {
      "ref": "acme-app",
      "dependsOn": [
        "pkg:maven/org.acme/[email protected]",
        "pkg:maven/org.acme/[email protected]"
      ]
    },
    {
      "ref": "pkg:maven/org.acme/[email protected]",
      "dependsOn": [
        "pkg:maven/org.acme/[email protected]"
      ]
    },
    {
      "ref": "pkg:maven/org.acme/[email protected]",
      "dependsOn": [
        "pkg:maven/org.acme/[email protected]"
      ]
    },
    {
      "ref": "pkg:maven/org.acme/[email protected]",
      "dependsOn": []
    }
  ]
}

Authoritative Guide