Application SBOM (ConcertDef schema)

The application SBOM focuses on the static definition of the application's components, libraries, and dependencies. It provides a high-level, theoretical list of these components and their metadata using the ConcertDef schema.

The application SBOM is typically used in the pre-build phase to outline the intended structure of the application, however it can be generated at any time during the lifecycle for ingestion into the Concert platform. One application definition SBOM is required for every application in your environment.

Important notes

Note the following when generating an application SBOM in ConcertDef format:

An application SBOM may reference (without details) multiple in-scope deployment environments.
An application SBOM may reference (without details) several build artifacts using the component names and versions.
Application and environment names may not contain any spaces (leading, trailing, or in between) or slash (/) characters.
To replace an SBOM file for an existing application, the image (name of the Docker image) must be the same. Only the digest should be unique.
You must generate one application SBOM for each application.

Warning: To replace an SBOM file for an existing application, the image (name of the Docker image) must be the same. Only the digest should be unique.

Application SBOM schema

The following code represents the complete application SBOM schema in ConcertDef format. You can copy and paste these details into a separate file or download the schema via API.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://concert.ibm.com/schema/concertdef-1.0.2.schema.json",
  "type": "object",
  "title": "ConcertDef v1.0.2 Schema for Application Blueprint SBOM Files",
  "required": [
    "bomFormat",
    "specVersion",
    "metadata"
  ],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "enum": [
        "http://concert.ibm.com/schema/concertdef-1.0.2.json"
      ]
    },
    "bomFormat": {
      "type": "string",
      "title": "BOM Format",
      "description": "Format of the BOM.",
      "enum": [
        "ConcertDef"
      ]
    },
    "specVersion": {
      "type": "string",
      "title": "Concert Schema Specification Version",
      "description": "Version of the ConcertDef specification.",
      "enum": [
        "1.0.2"
      ]
    },
    "metadata": {
      "$ref": "#/definitions/metadata",
      "title": "BOM Metadata",
      "uniqueItems": true,
      "description": "Provides additional information about a BOM."
    },
    "components": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "$ref": "#/definitions/blueprint-build"
          }
        ]
      },
      "uniqueItems": true,
      "title": "Components",
      "description": "A list of top-level software components."
    },
    "environments": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/environment"
      },
      "uniqueItems": true,
      "title": "Environments",
      "description": "A list of software deployment environments."
    },
    "services": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "$ref": "#/definitions/app-service"
          }
        ]
      },
      "uniqueItems": true,
      "title": "Components",
      "description": "A list of services in Application SBOM or in deploy SBOM."
    },
    "dependencies": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/dependency"
      },
      "uniqueItems": true,
      "title": "Dependencies",
      "description": "Provides the ability to document dependency relationships."
    },
    "properties": {
      "type": "array",
      "title": "Properties",
      "items": {
        "$ref": "#/definitions/property"
      }
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "uniqueItems": true,
      "title": "Tags",
      "description": "An optional list of strings that can be used for searching or filtering.",
      "examples": [
        "team-tiger"
      ]
    }
  },
  "definitions": {
    "refType": {
      "description": "An identifier which can be used to reference the component elsewhere in the BOM. Every bom-ref MUST be unique within the BOM.",
      "type": "string",
      "minLength": 1
    },
    "refLinkType": {
      "description": "Descriptor for an element identified by the attribute 'bom-ref' in the same BOM document.\nIn contrast to `bomLinkElementType`.",
      "allOf": [
        {
          "$ref": "#/definitions/refType"
        }
      ]
    },
    "bomLinkDocumentType": {
      "title": "CycloneDX BOM-Link Document",
      "description": "Descriptor for another BOM document. See https://cyclonedx.org/capabilities/bomlink/",
      "type": "string",
      "minLength": 1,
      "format": "iri-reference",
      "$comment": "part of the pattern is based on `bom.serialNumber`'s pattern",
      "examples": [
        "urn:uuid:97cdf861-f4e8-4bb1-893b-9e5907ebb399/1"
      ]
    },
    "bomLinkElementType": {
      "title": "CycloneDX BOM-Link Element",
      "description": "Descriptor for an element in a BOM document. See https://cyclonedx.org/capabilities/bomlink/",
      "type": "string",
      "minLength": 1,
      "format": "iri-reference",
      "$comment": "part of the pattern is based on `bom.serialNumber`'s pattern"
    },
    "bomLink": {
      "anyOf": [
        {
          "$ref": "#/definitions/bomLinkDocumentType"
        },
        {
          "$ref": "#/definitions/bomLinkElementType"
        }
      ]
    },
    "metadata": {
      "type": "object",
      "title": "BOM Metadata Object",
      "required": [
        "type",
        "component"
      ],
      "additionalProperties": false,
      "properties": {
        "timestamp": {
          "type": "string",
          "minLength": 1,
          "format": "date-time",
          "title": "Timestamp",
          "description": "ISO 8601 date and time when the BOM was created.",
          "examples": [
            "2024-01-01T12:00:00Z"
          ]
        },
        "type": {
          "type": "string",
          "enum": [
            "application"
          ],
          "title": "Metadata Type",
          "description": "Specifies the ConcertDef type of the software component.  The types are:\n\n* __application__ = A software application definition without environment-dependent deployment specifics for its constituent containers, code repositories, services, and/or API endpoints.\n* __build__ = A component comprising versioned container image artifact and the associated versioned code repository.\n* __deploy__ = A component comprsing deployment components, runtime-components, and relevant services and API endpoint URLs for deploying environment-specific application microservices.",
          "examples": [
            "build"
          ]
        },
        "component": {
          "type": "object",
          "title": "Metadata Component",
          "description": "ConcertDef component labels used for searching or selecting in Concert.",
          "required": [
            "name",
            "version"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "title": "Name",
              "description": "Name of the ConcertDef component",
              "examples": [
                "my-component-1"
              ]
            },
            "version": {
              "type": "string",
              "minLength": 1,
              "title": "Version",
              "description": "Versioon string of the ConcertDef component.",
              "examples": [
                "2.100.0"
              ]
            }
          }
        },
        "business": {
          "$ref": "#/definitions/organizationalEntity"
        },
        "properties": {
          "type": "array",
          "title": "Properties",
          "items": {
            "$ref": "#/definitions/property"
          }
        }
      }
    },
    "organizationalEntity": {
      "type": "object",
      "title": "Organizational Entity Object",
      "required": [
        "name"
      ],
      "description": " The business organization that supplied the component that the BOM describes.",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Name",
          "description": "The name of the business organization",
          "examples": [
            "Acme Inc."
          ]
        },
        "units": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/organizationalContact"
          },
          "uniqueItems": true,
          "title": "Business Units",
          "description": "A list of business units."
        }
      }
    },
    "organizationalContact": {
      "type": "object",
      "title": "Organizational Contact",
      "required": [
        "name"
      ],
      "description": "A business unit contact at the organization. Multiple contacts are allowed.",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Name",
          "description": "The name of a business unit",
          "examples": [
            "HR"
          ]
        },
        "email": {
          "type": "string",
          "minLength": 1,          
          "format": "idn-email",
          "title": "Email Address",
          "description": "The email address of the business unit.",
          "examples": [
            "hr@acme.com"
          ]
        },
        "phone": {
          "type": "string",
          "minLength": 1,
          "title": "Phone",
          "description": "The phone number of the business unit.",
          "examples": [
            "(123) 123-1234"
          ]
        }
      }
    },
    "blueprint-build": {
      "type": "object",
      "title": "Build Blueprint",
      "required": [
        "type",
        "name",
        "version"
      ],
      "additionalProperties": false,
      "properties": {
        "bom-ref": {
          "$ref": "#/definitions/refType"
        },
        "type": {
          "type": "string",
          "enum": [
            "build"
          ]
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Build Blueprint Name",
          "description": "Name of the Build component. This is often a shortened, single name of the component.",
          "examples": [
            "my-component-1"
          ]
        },
        "version": {
          "type": "string",
          "minLength": 1,
          "title": "Version",
          "description": "Version string for the component.  The value can be a timestamp string.",
          "examples": [
            "0.0.1"
          ]
        },
        "components": {
          "items": {
            "anyOf": [
              {
                "$ref": "#/definitions/blueprint-library"
              },
              {
                "$ref": "#/definitions/blueprint-container"
              },
              {
                "$ref": "#/definitions/blueprint-code"
              }
            ]
          },
          "title": "Blueprint Objects for a Build Component",
          "description": "A list of Build object blueprints, each of which is associated with a Build object."
        },
        "properties": {
          "type": "array",
          "title": "Properties",
          "items": {
            "$ref": "#/definitions/property"
          }
        }
      }
    },
    "blueprint-library": {
      "type": "object",
      "title": "Library Blueprint",
      "required": [
        "type",
        "name",
        "version"
      ],
      "additionalProperties": false,
      "properties": {
        "bom-ref": {
          "$ref": "#/definitions/refType"
        },
        "type": {
          "type": "string",
          "enum": [
            "library"
          ]
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Library Name",
          "description": "Library name per CycloneDX specification.",
          "examples": [
            "maven/com.app.example"
          ]
        },
        "version": {
          "type": "string",
          "minLength": 1,
          "title": "Version",
          "description": "Version string for the component.",
          "examples": [
            "0.0.1"
          ]
        }
      }
    },
    "blueprint-container": {
      "type": "object",
      "title": "Container Blueprint",
      "required": [
        "type",
        "name"
      ],
      "additionalProperties": false,
      "properties": {
        "bom-ref": {
          "$ref": "#/definitions/refType"
        },
        "type": {
          "type": "string",
          "enum": [
            "container"
          ]
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Container Image Reference",
          "description": "Image path (without tag or digest).",
          "examples": [
            "us.icr.io/myapp/my-component-1"
          ]
        }
      }
    },
    "blueprint-code": {
      "type": "object",
      "title": "Code Blueprint",
      "required": [
        "type",
        "name",
        "purl"
      ],
      "additionalProperties": false,
      "properties": {
        "bom-ref": {
          "$ref": "#/definitions/refType"
        },
        "type": {
          "type": "string",
          "enum": [
            "code"
          ]
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Code Name",
          "description": "Name of the Code blueprint. This is often a shortened, single name of the code repo.",
          "examples": [
            "my-component-1"
          ]
        },
        "purl": {
          "type": "string",
          "minLength": 1,
          "title": "Code URL",
          "description": "URL (or folder path) of the Code blueprint. This is often the URL of a source code repo (or file system).",
          "examples": [
            "https://github.ibm.com/myapp/my-component-1"
          ]
        }
      }
    },
    "environment": {
      "type": "object",
      "title": "Environment",
      "required": [
        "type",
        "name"
      ],
      "additionalProperties": false,
      "properties": {
        "bom-ref": {
          "$ref": "#/definitions/refType"
        },
        "type": {
          "type": "string",
          "enum": [
            "environment"
          ],
          "title": "Environment Type",
          "description": "A deployment environment."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Deployment Environment Name",
          "description": "The deployment environment name must be unique in the Concert service in use.",
          "examples": [
            "acme-test",
            "cluster-001",
            "us-west-vpc-005"
          ]
        }
      }
    },
    "app-service": {
      "type": "object",
      "title": "Service Blueprint in Application SBOM",
      "required": [
        "name",
        "endpoints"
      ],
      "additionalProperties": false,
      "properties": {
        "bom-ref": {
          "$ref": "#/definitions/refType"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Service Name",
          "description": "The name of the service. This will often be a shortened, single name of the service.",
          "examples": [
            "mongodb"
          ]
        },
        "endpoints": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "minItems": 1,
          "uniqueItems": true,
          "title": "Endpoints",
          "description": "The API paths of the service providing component. Base URLs of the API service endpoints are provided by the service's Deploy component",
          "examples": [
            "/v1/ticker"
          ]
        },
        "properties": {
          "type": "array",
          "title": "Properties",
          "description": "Valid values for the \"network_exposure\" property are: \"private\" and \"public\".  Networking infrastructure of the target deployment environments must be configured and managed accordingly.",
          "items": {
            "$ref": "#/definitions/property"
          }
        }
      }
    },
    "dependency": {
      "type": "object",
      "title": "Dependency",
      "description": "Defines the direct dependencies of a component or service.",
      "required": [
        "ref",
        "dependsOn"
      ],
      "additionalProperties": false,
      "properties": {
        "ref": {
          "$ref": "#/definitions/refLinkType",
          "title": "Reference",
          "description": "References a component or service by its bom-ref attribute"
        },
        "dependsOn": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "$ref": "#/definitions/refLinkType"
          },
          "title": "Depends On",
          "description": "The bom-ref identifiers of the components or services that are dependencies of this dependency object."
        }
      }
    },
    "property": {
      "type": "object",
      "title": "Lightweight name-value pair",
      "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values.",
      "required": [
        "name",
        "value"
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "title": "Name",
          "description": "The name of the property. Duplicate names are allowed, each potentially having a different value."
        },
        "value": {
          "type": "string",
          "title": "Value",
          "description": "The value of the property."
        }
      }
    }
  }
}

Sample: Application SBOM

The following code snippet provides an example for the type of information expected in the application SBOM file.

{
  "bomFormat": "ConcertDef",
  "specVersion": "1.0.2",
  "metadata": {
    "timestamp": "2024-12-06T15:23:57Z",
    "type": "application",
    "component": {
      "name": "concert-sample-devsecops",
      "version": "1.0.0"
    },
    "business": {
      "name": "Acme Inc.",
      "units": [
        {
          "name": "Unit 1",
          "email": "myemail@acme.com",
          "phone": "(123) 123-1234"
        }
      ]
    }
  },
  "components": [
    {
      "bom-ref": "build:concert-sample-devsecops",
      "type": "build",
      "name": "concert-sample-devsecops",
      "version": "1.0.0",
      "components": [
        {
          "bom-ref": "container:us.icr.io/icr4mcc/concert-sample-devsecops",
          "type": "container",
          "name": "us.icr.io/icr4mcc/concert-sample-devsecops"
        },
        {
          "bom-ref": "repository:coderepo:github:concert-sample-devsecops",
          "type": "code",
          "name": "concert-sample-devsecops",
          "purl": "https://github.ibm.com/concert/concert-sample-devsecops"
        }
      ]
    }
  ],
  "environments": [
    {
      "bom-ref": "environment:dev",
      "type": "environment",
      "name": "dev"
    },
    {
      "bom-ref": "environment:stage",
      "type": "environment",
      "name": "stage"
    },
    {
      "bom-ref": "environment:prod",
      "type": "environment",
      "name": "prod"
    }
  ],
  "services": [
    {
      "bom-ref": "appapi:concert-sample-devsecops",
      "name": "concert-sample-devsecops",
      "endpoints": [
        "/"
      ]
    }
  ],
  "dependencies": [
    {
      "ref": "build:concert-sample-devsecops",
      "dependsOn": [
        "appapi:concert-sample-devsecops"
      ]
    }
  ],
  "properties": [
    {
      "name": "application_criticality",
      "value": "3"
    }
  ]
}

Next step: Validate the SBOM file

Refer to Validating a ConcertDef SBOM for details about validating the file via API before uploading to your Concert instance.