Annex B (informative) Specification narrative

The following sections are derived from the working group's authoring notes maintained as Markdown in the source repository.

B.1 Transparency Exchange API: Consumer access

The consumer access starts with a TEI, A Transparency Exchange Identifier. This is used to find the API server as described in the discovery document.

B.1.1 API usage

The standard TEI points to a product release. A product release is something sold, downloaded as an open source project or acquired by other means. It contains one or multiple component releases.

List of TEA Component Releases: Component releases are components of a product release. Each Component release has its own versioning and its own set of artefacts, they have a timestamp and a lifecycle enumeration. They are normally sorted by timestamps. The TEA API has no requirements of type of version string (semantic or any other scheme) - it's just an identifier set by the manufacturer.
List of TEA Collections: For each release, there is a list of TEA collections as indicated by release date and a version integer starting with collection version 1.
List of TEA Artifacts: The collection is unique for a version and contains a list of artefacts. This can be SBOM files, VEX, SCITT, IN-TOTO or other documents. Note that a single artefact can belong to multiple Component or Product Releases.
List of artefact formats: An artefact can be published in multiple formats.

Finding the list of artefacts for a Product Release starts from the product release TEI and, in some cases, the version of each component (TEA Component Release).

B.1.2 API flow based on TEI discovery

Figure 1

B.1.3 API flow based on direct access to API

In this case, the client wants to search for a specific product release using the API

Figure 2

B.1.4 API flow based on cached data - checking for a new release

In this case a TEA client knows the component UUID and wants to check the status of the used release and if there's a new release.

Figure 3

B.1.5 API flow based on cached data - checking if a collection changed

In this case a TEA client knows the release UUID, the collection UUID, and the collection version from previous queries. If the given version is not the same, another query is done to get reason for update and new collection list of artefacts.

Figure 4

B.2 The TEA Product object

After TEA discovery, the Transparency Exchange Identifier (TEI) resolves to one or more TEA Product Releases, each a concrete, versioned offering; a TEI normally resolves to exactly one. A TEA Product is a higher-level object that groups multiple Product Releases for a product line or family and can be browsed via /product/{uuid}/releases.

A product release may consist of a single component, the output will be metadata about the product and the TEA COMPONENT object.
For a composed product release consisting of a bundle of components or component releases, the response will be multiple TEA COMPONENT objects.

In addition, all known TEIs for the product will be returned, in order for a TEA client to avoid duplication. This list can also include known Package URLs (PURL) and CPEs for the product.

B.2.1 Authorization

Authorization can be done on multiple levels, including which products and versions are supported for a specific user.

B.2.2 Composite products

A TEA Product Release will be the starting point of discovery. The TEA product release will list all included components with the UUID of the TEA component. The reference list may also include a UUID of a specific release of a component in the case where a product always includes a single release of the component.

The TEA Product object groups multiple releases together.

B.2.3 Structure

Key attributes:

uuid: A unique identifier for the TEA product
name: Product name
identifiers: List of identifiers for the product
- idType: Type of identifier, e.g. TEI, PURL, CPE
- idValue: Identifier value

Required fields:

uuid, name, identifiers

B.2.3.1 Example

An example of a product consisting of an OSS project and all its Maven artefacts:

{
  "uuid": "09e8c73b-ac45-4475-acac-33e6a7314e6d",
  "name": "Apache Log4j 2",
  "identifiers": [
    {
      "idType": "CPE",
      "idValue": "cpe:2.3:a:apache:log4j"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-layout-template-json"
    }
  ]
}

Releases for this Product can be browsed via the API endpoint /product/{uuid}/releases.

B.2.3.2 API usage

The user will find this API end point using TEA discovery.

A user will approach the API just to discover data before purchase, or with a specific product and product version in scope. The format of the version string can follow many syntaxes. This specification does not constrain that format.

An automated system may want to provide the user with a GUI, listing versions and being able to scroll to the next page until the user selects a version.

B.3 The TEA Product Release object

B.3.1 Overview

A TEA Product Release represents a specific versioned release of a TEA Product. It is the primary resolvable entity via TEI and the entry point for discovery of included components and related collections of security artefacts.

Key attributes:

uuid: A unique identifier for the TEA Product Release
product: UUID of the TEA Product this release belongs to
productName: Optional name of the parent product
version: Human-readable version string of the product release
createdDate: Timestamp when the product release was created in TEA (for sorting purposes)
releaseDate: Timestamp of the product release
preRelease: A flag indicating pre-release (or beta) status. May be disabled after the creation of the release object, but can't be enabled after creation of an object. (boolean)
identifiers: Array of identifiers for the product release (idType: CPE/TEI/PURL; idValue: string)
components: Array of component references that compose this product release. A component reference can optionally include the UUID of a specific component release to pin the exact version.

Required fields:

uuid, product, version, createdDate, components

Collections for a product release contain artefacts relevant to that product release.

B.3.2 JSON examples

The following example is reused from the OpenAPI schema (components/schemas/product-release.examples), ensuring exact field names and casing.

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "version": "2.24.3",
  "createdDate": "2025-04-01T15:43:00Z",
  "releaseDate": "2025-04-01T15:43:00Z",
  "product": "09e8c73b-ac45-4475-acac-33e6a7314e6d",
  "identifiers": [
    {
      "idType": "TEI",
      "idValue": "tei://vendor.example.com/uuid/47f51950-b0e2-11f1-adc2-1a52914d44b2"
    }
  ],
  "components": [
    {
      "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0"
    },
    {
      "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3",
      "release": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab"
    }
  ]
}

B.3.3 Handling the Pre-Release flag

The "Pre-release" flag is used to indicate that this is not a final release. For a given product release with a UUID, the flag can be set to indicate a "test", "beta", "alpha" or similar non-deployed release. It can only be set when creating the product release. The TEA implementation may allow it to be unset (False) once. This is to support situations where a object is promoted as is after testing to production version. The flag can not be set after initial creation and publication of the product release.

If the final version is different from the pre-release (bugs fixed, code changed, different binary) a new product release with a new UUID and version shall be created.

B.3.4 Notes

Use uppercase idType values exactly as defined by the schema enum: CPE, TEI, PURL.

B.4 The TEA Component object

The TEA Component represents a component lineage. A product release may be constructed with one or multiple TEA Components, each with their own set of releases and related artefacts. The component has releases, which has a set of artifacts for each release. One artifact may belong to multiple releases.

Each TEA Component has a list of Component Releases (see /component/{uuid}/releases), which enumerates all known versions for that component.

The TEA API is agnostic as to how a "version" is indicated - semver, vers, name, hash or anything else.

B.4.1 Versions and TEIs

A TEI resolves to one or more Product Releases. A Product groups related Product Releases.

For the API to be able to present a list of versions in a chronological order, a timestamp for a release is required.

B.4.2 Structure

A TEA Component object has the following parts:

uuid: A unique identifier for the TEA component
name: Component name
identifiers: List of identifiers for the component
- idType: Type of identifier, e.g. TEI, PURL, CPE
- idValue: Identifier value

Required fields:

uuid, name, identifiers

B.4.2.1 Examples

Some examples of Maven artefacts as TEA Components:

{
  "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0",
  "name": "Apache Log4j API",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
    }
  ]
}

{
  "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3",
  "name": "Apache Log4j Core",
  "identifiers": [
    {
      "idType": "CPE",
      "idValue": "cpe:2.3:a:apache:log4j"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core"
    }
  ]
}

B.4.3 References

Semantic versioning (Semver): https://semver.org
VERS https://tc54.org/vers/

B.5 The TEA Component Release object

B.5.1 Overview

A TEA Component Release represents a specific version of a TEA Component lineage. It is the concrete, versioned entity which has collections of security-related artifacts (SBOM, VDR/VEX, attestations, etc.).

A TEA Component Release object represents a specific version of a component, identified by a unique version number and associated metadata. Each release may include multiple distributions, which capture variations such as architecture, packaging, or localization.

For software components, each distribution typically corresponds to a different digital file delivered to users (e.g., by platform or packaging type).
For hardware components, distributions may reflect differences in packaging, language, or other physical attributes.

Each distribution is assigned a distributionId, a UUID defined by the producer, which is used to associate relevant TEA Artifacts with that distribution. Since TEA Artifacts can be associated with multiple release objects, a distributionId is unique within the TEA server and is not reused for a different distribution, so the association stays reliable across releases. What a distribution represents for the producer is carried by its description, not by its identifier.

Key attributes:

uuid: Unique identifier of the TEA Component Release (uuid)
component: UUID of the TEA Component this release belongs to
componentName: Name of the TEA Component this release belongs to
version: Human-readable version string
createdDate: Timestamp when this Release was created in TEA (for sorting purposes)
releaseDate: Timestamp of the release
preRelease: A flag indicating pre-release (or beta) status. May be disabled after the creation of the release object, but can't be enabled after creation of an object.
identifiers: Array of identifiers for the component release
distributions: List of different formats of this component release

Collections for a release contain artifacts relevant to that specific release.

Required fields:

uuid, component, version, createdDate

B.5.2 The TEA Component Release Distribution object

Distribution are object to declare different distribution formats of a component, like source code or a package for a specific Linux distribution or a CPU type

Key attributes:

distributionId: A unique identifier for the TEA Distribution object (uuid)
description: Free-text description of the distribution.
identifiers: Array of identifiers for the distribution of the release
url: Direct download URL for the distribution
signatureUrl: Direct download URL for the distribution's detached signature
checksums: Array of checksums for the distribution
- algType: Checksum algorithm used.
- algValue: Checksum value.

Required fields:

distributionId

B.5.3 JSON examples

The following examples are reused from the OpenAPI schema (components/schemas/component-release.examples), ensuring exact field names and casing.

{
  "uuid": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab",
  "version": "2.24.3",
  "component": "b844c9bd-55d6-478c-af59-954a932b6ad3",
  "componentName": "Apache Log4j Core",
  "createdDate": "2024-12-10T10:51:00Z",
  "releaseDate": "2024-12-13T12:52:29Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core@2.24.3"
    }
  ]
}

{
  "uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
  "version": "11.0.7",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2025-05-07T18:08:00Z",
  "releaseDate": "2025-05-12T18:08:00Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7"
    }
  ]
}

{
  "uuid": "95f481df-f760-47f4-b2f2-f8b76d858450",
  "version": "11.0.0-M26",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2024-09-13T17:49:00Z",
  "preRelease": true,
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26"
    }
  ]
}

B.5.3.1 Examples

B.5.3.1.1 Single distribution

This example shows a TEA Component Release for Apache Log4j Core, which is distributed as a single JAR file. Even though there is only one distribution, the distributions attribute is included to enable searching for the release by the SHA-256 checksum of the JAR. This structure also allows for future extensibility if additional distributions are introduced.

Example of simple release

{
  "uuid": "b1e2c3d4-5678-49ab-9cde-123456789abc",
  "version": "2.24.3",
  "component": "b844c9bd-55d6-478c-af59-954a932b6ad3",
  "createdDate": "2024-12-10T10:51:00Z",
  "releaseDate": "2024-12-13T12:52:29Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core@2.24.3"
    }
  ],
  "distributions": [
    {
      "distributionId": "0f3b9c51-2a4d-4a1e-9f6c-7d8e5b3a2c14",
      "description": "Binary distribution, JAR",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core@2.24.3?type=jar"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "b1e2c3d4f5a67890b1e2c3d4f5a67890b1e2c3d4f5a67890b1e2c3d4f5a67890"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3.jar",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3.jar.asc"
    }
  ]
}

B.5.3.1.2 Multiple distributions

This is an example of a TEA Component Release for Apache Tomcat 11.0.7 binary distributions. The example defines four distinct distributions, which is essential not only for associating the correct SBOMs with each distribution, but also for accurately tracking and reporting vulnerabilities that may affect only specific distributions. For instance:

The zip and tar.gz archives contain only Java JARs.
The Windows x64 zip archive additionally includes the Apache Procrun binary, which is specific to Windows and may introduce unique vulnerabilities.
The Windows Service Installer contains the same data as the Windows x64 zip archive, but is packaged as a self-extracting installer created by the Nullsoft Scriptable Install System.

By giving each of these its own distributionId, it becomes possible to precisely associate artefacts and vulnerability disclosures with the affected distributions, ensuring accurate risk assessment and remediation. The description of a distribution carries what it represents; the identifier itself is opaque.

Example of four different binary distributions in the same release

{
  "uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
  "version": "11.0.7",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2025-05-07T18:08:00Z",
  "releaseDate": "2025-05-12T18:08:00Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7"
    }
  ],
  "distributions": [
    {
      "distributionId": "6a0d58e1-4896-4f1e-83f7-5feb6c032537",
      "description": "Core binary distribution, zip archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?type=zip"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.zip",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.zip.asc"
    },
    {
      "distributionId": "dba01c13-dd96-4928-be72-9c87ffa8cab8",
      "description": "Core binary distribution, tar.gz archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?type=tar.gz"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.tar.gz",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.tar.gz.asc"
    },
    {
      "distributionId": "cfe068c2-fae7-43d0-97ec-5ea092454040",
      "description": "Core binary distribution, Windows x64 zip archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?classifier=windows-x64&type=zip"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-windows-x64.zip",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-windows-x64.zip.asc"
    },
    {
      "distributionId": "de45ffaf-e4b5-47b5-be28-444a76df098e",
      "description": "Core binary distribution, Windows Service Installer (.exe)",
      "checksums": [
        {
          "algType": "SHA-512",
          "algValue": "1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96"
        }
      ],
      "url": "https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe",
      "signatureUrl": "https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc"
    }
  ]
}

B.5.4 Handling the Pre-Release flag

B.5.4.1 Pre-release flag usage

The preRelease flag is used to indicate that a release is not production ready, regardless of the version naming scheme. This helps consumers identify non-production releases without relying on conventions like -beta, -rc, or -M in the version string.

There are two main scenarios for using the preRelease flag:

Pending release: The distribution is still undergoing quality assurance or review and is not yet officially released. These typically lack a releaseDate attribute. Once the release is approved, the preRelease flag is set to false and the releaseDate is added.
Permanent pre-release: The distribution is intentionally marked as a pre-release (e.g., beta, milestone, or release candidate) and will never be considered production ready, even after all checks are complete. These may have a releaseDate, but preRelease remains true.

Examples of non-production ready distributions

Pending release (no releaseDate):

{
  "uuid": "e2a1c7b4-3f2d-4e8a-9c1a-7b2e4d5f6a8b",
  "version": "11.0.0",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2025-09-01T00:00:00Z",
  "preRelease": true,
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0?repository_url=https:%2F%2Frepository.apache.org%2Fcontent%2Fgroups%2Fstaging%2F"
    }
  ]
}

Transition to production-ready (preRelease flag turned off, releaseDate added):

{
  "uuid": "e2a1c7b4-3f2d-4e8a-9c1a-7b2e4d5f6a8b",
  "version": "11.0.0",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2025-09-01T00:00:00Z",
  "releaseDate": "2025-09-10T12:00:00Z",
  "preRelease": false,
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0"
    }
  ]
}

Beta version (has releaseDate, but not production ready):

{
  "uuid": "95f481df-f760-47f4-b2f2-f8b76d858450",
  "version": "11.0.0-M26",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2024-09-13T17:49:00Z",
  "releaseDate": "2024-09-16T17:49:00Z",
  "preRelease": true,
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26"
    }
  ]
}

Notes:

Use uppercase idType values exactly as defined by the schema enum: CPE, TEI, PURL.

B.6 The TEA Collection object

For each product and version there is a Tea Collection object (TCO), which is a list of available artifacts for this specific version.

The TEA collection is normally created by the TEA application server at publication time of artifacts. The publisher may sign the collection object as a JSON file at time of publication.

A release is never served without a collection. If no artifacts have been published when the release first becomes retrievable, the server serves collection version 1 with an empty artifacts list and updateReason.type: INITIAL_RELEASE. That version is immutable like any other; the first artifacts are published as version 2. Classification follows the update-reason rules below. A publisher that publishes the release and its artifacts together never has an empty version and starts at version 1 with content. In both cases version 1 is the first collection a client could have retrieved. A server may also synthesize the collection dynamically (see below).

If there are any updates of artefacts within a collection for the same version of a product, then a new TEA Collection object is created and optionally signed. This update will have the same UUID, but a new version number. A reason for the update will have to be provided. This shall be used to correct mistakes, spelling errors as well as to provide new information on dynamic artifact types such as CLE or VEX. If the product is modified, that is a new product version and that should generate a new collection object with a new UUID and updated metadata.

The API allows for retrieving the latest version of the collection, or a specific version.

B.6.1 Dynamic or static Collection objects

The TCO is managed by the TEA software platform. There are two ways to implement this:

Dynamic: The TCO is built for each API request and created dynamically.
Static: The TCO is built at publication time as a static object by the publisher. This object can be digitally signed at publication time and version controlled.

B.6.2 Structure

The TEA Collection object has the following parts:

Preamble
uuid: UUID of the TEA Collection object. A TEA Collection shall use the same UUID as its parent Product Release or Component Release. Within an API base, a Product Release and a Component Release shall not share a UUID. Consequently, Collections belonging to different parent releases have different UUIDs. Versions of the same Collection retain the same UUID. See TEA UUID Scope and Stability.
version: TEA Collection version, incremented by 1 each time its content changes. Versions start with 1. Content changes include replacing an embedded artifact with a newer revision (for example one published because an external url or signatureUrl changed). If a Collection adopts that new artifact revision, the server shall publish a new Collection version. Previously published Collection versions shall remain unchanged. Classification of that adoption follows the update-reason rules below.
createdDate: Timestamp when the TEA Collection version was created.
belongsTo: Indicates whether this collection belongs to a Component Release or a Product Release. Enum values COMPONENT_RELEASE or PRODUCT_RELEASE.
updateReason: Reason for the update/release of the TEA Collection object.
- type: Type of update reason. See reasons for TEA Collection update below.
- comment: Free text description.
artifacts: Array of TEA Artifact objects. See below.

Required fields:

uuid, version, createdDate, belongsTo, updateReason, artifacts, updateReason.type

B.6.3 The TEA Artifact object

A TEA Artifact object represents a security-related document or file linked to a component release, such as an SBOM, VEX, attestation, or license. TEA Artifacts are strictly immutable per revision: if the underlying document or any published field, including external url / signatureUrl values, changes, a new TEA Artifact revision shall be created. For a fixed artifact UUID, version, and format, the server shall ensure that successful content retrieval through its download endpoint, including retrieval after following redirects, yields unchanged artifact bytes after HTTP transfer coding and content coding are removed. The server shall ensure that successful signature retrieval through its signature download endpoint yields unchanged signature bytes on the same terms. Changing only a download response's Location, or only its HTTP content coding, while preserving those bytes, does not require a new artifact or collection version. For artifact content retrieved from an external url, the published checksums are the integrity statement for the revision. These checksums do not cover detached signatures.

TEA Artifacts can be reused across multiple TEA Collections, allowing the same document to be referenced by different component or product releases. This promotes consistency and reduces duplication. Publishing a new artifact revision does not by itself change Collections that continue to embed an older revision.

Optionally, each TEA Artifact can specify the distributionIds of the distributions it applies to. If this field is absent, the TEA Artifact is considered applicable to all distributions of the release.

B.6.3.1 Structure

A TEA Artifact object contains the following fields:

uuid: The UUID of the TEA Artifact object. Together with version uniquely identifies the TEA Artifact.
version: Revision number, starting at 1 and incremented by 1 for each new revision of the same artifact UUID. Together with uuid uniquely identifies the TEA Artifact. Successive revisions cover content changes and changes to any published field, including external url or signatureUrl values. Each published revision is immutable.
name: A human-readable name for the artifact.
type: The type of TEA artifact. See TEA Artifact types for allowed values (e.g., BOM, VULNERABILITIES, LICENSE).
createdDate: The date and time the TEA Artifact revision was created.
distributionIds: (optional): Array of TEA Component Release distributions that this TEA Artifact applies to. If absent or empty, the TEA Artifact applies to all distributions.
formats:
A non-empty array of objects, each representing the same artifact content in a different format. The order of the list is not significant. Each format object includes:
- mediaType: The media type of the document (e.g., application/vnd.cyclonedx+xml). Required. A media type appears at most once across the formats of a TEA Artifact revision, so that a format can be selected unambiguously by media type.
- description: A free-text description of the artifact format.
- url (optional): An external download URL for the artifact, outside the TEA API. When present, clients shall retrieve the content from it. When absent, the TEA server hosts the content itself and clients shall retrieve it from the artifact download endpoint (/artifact/{uuid}/{version}/download), selecting the format by its media type. url and signatureUrl should be stable URLs. Servers should not publish pre-signed or otherwise expiring URLs in them. A server that serves content from expiring storage links shall omit them and answer from the download endpoints, with 302 where the bytes live elsewhere. Changing url shall create a new artifact revision, even when content and checksums are unchanged. The server shall preserve the URLs published on each historical artifact and collection version. Collection adoption follows the collection version rules above. Byte stability for content retrieved through the server's download endpoint follows the artifact revision rule above. Servers shall publish at least one checksum for every format that has a url; content that does not match them is not the content of that revision. The latest download endpoints are mutable by design and shall not be used as a format's url or signatureUrl.
- signatureUrl (optional): An external download URL for a detached digital signature of the artifact, outside the TEA API. If present, clients retrieve the signature from it. If absent, clients retrieve it from the artifact signature download endpoint (/artifact/{uuid}/{version}/signature/download), which answers 404 when no signature is published for the format. Changing signatureUrl follows the same revision and collection-adoption rules as url. Byte stability for signature retrieval through the server's signature download endpoint follows the artifact revision rule above.
- checksums: When present, the array shall contain at least one entry. When url is present, checksums is required. An array of checksum objects for the artifact format's content bytes, each containing:
  - algType: The checksum algorithm used (e.g., SHA-256, SHA3-512).
  - algValue: The checksum value as a string. When url is present, these checksums are the integrity statement for the revision. Content that does not match them is not the content of that revision.
  Published checksums shall be calculated over the artifact format's bytes before HTTP content coding is applied. Clients verifying them shall first remove any HTTP transfer coding and content coding, and shall not otherwise transform or canonicalize the artifact bytes. An artifact that is itself compressed, such as a .gz file, stays in that form. The TEA servers shall not declare the artifact's own compression as HTTP content coding, because clients would then remove it and the checksum would not match.

Required fields:

uuid, type, formats, createdDate, version

B.6.3.2 Notes

The formats array allows the same artifact to be provided in multiple encodings or serializations (e.g., JSON, XML).
The checksums field provides integrity verification for each artifact format's bytes before HTTP content coding is applied. It does not cover detached signatures, and it is not a digest of an HTTP-encoded representation; Repr-Digest covers that.
Detached signatures, whether at signatureUrl or served by the TEA server, enable consumers to verify the authenticity of the artifact.
url and signatureUrl are always external locations; a TEA server that hosts content or signatures itself omits them and serves the bytes from its download endpoints. A TEA access token is sent only to the TEA server's own API, never to an external URL.

B.6.4 The reason for TCO update enum

Table 129: TEA Collection update reasons

ENUM	Description
INITIAL_RELEASE	Initial release of the collection
VEX_UPDATED	Adding or revising an artifact of type `VULNERABILITIES`, including a new revision whose external `url` or `signatureUrl` changed
ARTIFACT_UPDATED	A new revision of an artifact whose type is not `VULNERABILITIES`, including a revision whose external `url` or `signatureUrl` changed
ARTIFACT_REMOVED	Removal of artifact
ARTIFACT_ADDED	Addition of an artifact whose type is not `VULNERABILITIES`

Replacing an embedded artifact revision solely because its published url or signatureUrl changed is VEX_UPDATED when the artifact type is VULNERABILITIES, and ARTIFACT_UPDATED otherwise. VEX_UPDATED covers adding or revising an artifact of type VULNERABILITIES. VEX and VDR share that type. Removing an artifact, including one of type VULNERABILITIES, counts as ARTIFACT_REMOVED. The first Collection version shall use INITIAL_RELEASE. In subsequent versions, adding or revising an artifact of type VULNERABILITIES counts as VEX_UPDATED. When multiple change kinds occur, the server shall select updateReason.type using the precedence rule below.

When a collection version other than the first contains changes of more than one kind, the server shall set updateReason.type to the first applicable value in this order: VEX_UPDATED, ARTIFACT_REMOVED, ARTIFACT_ADDED, ARTIFACT_UPDATED. comment can describe the other changes. A client that needs the complete set of changes should compare the version with the previous one.

Updates of VEX (CSAF) files may be handled in a different way by a TEA client, producing different alerts than other changes of a collection.

B.6.5 TEA Artifact types

Table 130: TEA Artifact types

ENUM	Description
ATTESTATION	Machine-readable statements containing facts, evidence, or testimony.
BOM	Bill of Materials: SBOM, OBOM, HBOM, SaaSBOM, etc.
BUILD_META	Build-system specific metadata file: `pom.xml`, `package.json`, `.nuspec`, etc.
CERTIFICATION	Industry, regulatory, or other certification from an accredited certification body.
FORMULATION	Describes how a component or service was manufactured or deployed.
LICENSE	License file
RELEASE_NOTES	Release notes document
SECURITY_TXT	A `security.txt` file
THREAT_MODEL	A threat model
VULNERABILITIES	A list of vulnerabilities: VDR/VEX
OTHER	Document that does not fall into any of the above categories

B.6.5.1 Examples

{
  "uuid": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab",
  "version": 10,
  "createdDate": "2024-12-15T00:00:00Z",
  "belongsTo": "COMPONENT_RELEASE",
  "updateReason": {
    "type": "VEX_UPDATED",
    "comment": "VDR file updated"
  },
  "artifacts": [
    {
      "uuid": "1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce",
      "version": 2,
      "createdDate": "2024-12-13T00:00:00Z",
      "name": "Build SBOM",
      "type": "BOM",
      "formats": [
        {
          "mediaType": "application/vnd.cyclonedx+xml",
          "description": "CycloneDX SBOM (XML)",
          "url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml",
          "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml.asc",
          "checksums": [
            {
              "algType": "SHA-256",
              "algValue": "e04c9d55986d7194822eaa4f8115a77f801844d807ad6e0d454ac31dd41861e5"
            },
            {
              "algType": "SHA-1",
              "algValue": "5a7d4caef63c5c5ccdf07c39337323529eb5a770"
            }
          ]
        }
      ]
    },
    {
      "uuid": "dfa35519-9734-4259-bba1-3e825cf4be06",
      "version": 7,
      "createdDate": "2024-12-15T00:00:00Z",
      "name": "Vulnerability Disclosure Report",
      "type": "VULNERABILITIES",
      "formats": [
        {
          "mediaType": "application/vnd.cyclonedx+xml",
          "description": "CycloneDX VDR (XML)",
          "url": "https://logging.apache.org/cyclonedx/vdr.xml",
          "checksums": [
            {
              "algType": "SHA-256",
              "algValue": "75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a"
            }
          ]
        }
      ]
    }
  ]
}