# $schema: https://spec.openapis.org/oas/3.1/schema-base/2025-02-13 openapi: 3.1.1 jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base info: title: Transparency Exchange API summary: The OWASP Transparency Exchange API specification for consumers and publishers description: TBC contact: name: TEA Working Group email: tbc@somewhere.tld url: https://github.com/CycloneDX/transparency-exchange-api license: name: Apache 2.0 url: https://github.com/CycloneDX/transparency-exchange-api/blob/main/LICENSE version: 0.5.0 servers: - url: http://localhost/tea/v1 description: Local development paths: /product/{uuid}: get: description: Get a TEA Product by UUID operationId: getTeaProductByUuid parameters: - name: uuid in: path required: true description: UUID of the TEA product in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: Requested TEA Product found and returned content: application/json: schema: $ref: "#/components/schemas/product" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Product /product/{uuid}/releases: get: description: Get releases of the product operationId: getReleasesByProductId parameters: - name: uuid in: path required: true description: UUID of TEA Product in the TEA server schema: "$ref": "#/components/schemas/uuid" - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/page-token" - $ref: "#/components/parameters/sort-field-product-release" - $ref: "#/components/parameters/sort-order" responses: '200': $ref: "#/components/responses/paginated-product-release" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Product Release /productRelease/{uuid}: get: description: Get a TEA Product Release operationId: getTeaProductReleaseByUuid parameters: - name: uuid in: path required: true description: UUID of TEA Product Release in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: Requested TEA Product Release found and returned content: application/json: schema: "$ref": "#/components/schemas/productRelease" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Product Release /productRelease/{uuid}/cle: get: description: Get the CLE (Common Lifecycle Enumeration) data for a TEA Product Release operationId: getCleByProductReleaseId parameters: - name: uuid in: path required: true description: UUID of TEA Product Release in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: CLE data for the requested TEA Product Release found and returned content: application/json: schema: "$ref": "#/components/schemas/cle" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - CLE /productReleases: get: description: Returns a list of TEA product releases. Note that multiple product releases may match. operationId: queryTeaProductReleases parameters: # For result filtering - $ref: "#/components/parameters/id-type" - $ref: "#/components/parameters/id-value" # For pagination - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/page-token" - $ref: "#/components/parameters/sort-field-product-release" - $ref: "#/components/parameters/sort-order" responses: '200': $ref: "#/components/responses/paginated-product-release" '400': $ref: "#/components/responses/400-invalid-request" tags: - TEA Product Release /product/{uuid}/cle: get: description: Get the CLE (Common Lifecycle Enumeration) data for a TEA Product operationId: getCleByProductId parameters: - name: uuid in: path required: true description: UUID of TEA Product in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: CLE data for the requested TEA Product found and returned content: application/json: schema: "$ref": "#/components/schemas/cle" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - CLE /products: get: description: Returns a list of TEA products. Note that multiple products may match. operationId: queryTeaProducts parameters: # For result filtering - $ref: "#/components/parameters/id-type" - $ref: "#/components/parameters/id-value" # For pagination - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/page-token" - $ref: "#/components/parameters/sort-field-product" - $ref: "#/components/parameters/sort-order" responses: '200': $ref: "#/components/responses/paginated-product" '400': $ref: "#/components/responses/400-invalid-request" tags: - TEA Product /component/{uuid}: get: description: Get a TEA Component operationId: getTeaComponentById parameters: - name: uuid in: path required: true description: UUID of TEA Component in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: Requested TEA Component found and returned content: application/json: schema: "$ref": "#/components/schemas/component" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Component /component/{uuid}/releases: get: description: Get releases of the component operationId: getReleasesByComponentId parameters: - name: uuid in: path required: true description: UUID of TEA Component in the TEA server schema: "$ref": "#/components/schemas/uuid" - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/page-token" - $ref: "#/components/parameters/sort-field-component-release" - $ref: "#/components/parameters/sort-order" responses: '200': $ref: "#/components/responses/paginated-component-release" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Component /component/{uuid}/cle: get: description: Get the CLE (Common Lifecycle Enumeration) data for a TEA Component operationId: getCleByComponentId parameters: - name: uuid in: path required: true description: UUID of TEA Component in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: CLE data for the requested TEA Component found and returned content: application/json: schema: "$ref": "#/components/schemas/cle" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - CLE /components: get: description: Returns a list of TEA components. Note that multiple components may match. operationId: queryTeaComponents parameters: # For result filtering - $ref: "#/components/parameters/id-type" - $ref: "#/components/parameters/id-value" # For pagination - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/page-token" - $ref: "#/components/parameters/sort-field-component" - $ref: "#/components/parameters/sort-order" responses: '200': $ref: "#/components/responses/paginated-component" '400': $ref: "#/components/responses/400-invalid-request" tags: - TEA Component /componentReleases: get: description: Returns a list of TEA component releases. Note that multiple component releases may match. operationId: queryTeaComponentReleases parameters: # For result filtering - $ref: "#/components/parameters/id-type" - $ref: "#/components/parameters/id-value" # For pagination - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/page-token" - $ref: "#/components/parameters/sort-field-component-release" - $ref: "#/components/parameters/sort-order" responses: '200': $ref: "#/components/responses/paginated-component-release" '400': $ref: "#/components/responses/400-invalid-request" tags: - TEA Component Release /componentRelease/{uuid}: get: description: Get the TEA Component Release with its latest collection operationId: getComponentReleaseById parameters: - name: uuid in: path required: true description: UUID of TEA Component Release in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: Requested TEA Component Release and its latest Collection found and returned content: application/json: schema: "$ref": "#/components/schemas/component-release-with-collection" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Component Release /componentRelease/{uuid}/cle: get: description: Get the CLE (Common Lifecycle Enumeration) data for a TEA Component Release operationId: getCleByComponentReleaseId parameters: - name: uuid in: path required: true description: UUID of TEA Component Release in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: CLE data for the requested TEA Component Release found and returned content: application/json: schema: "$ref": "#/components/schemas/cle" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - CLE /componentRelease/{uuid}/collection/latest: get: description: Get the latest TEA Collection belonging to the TEA Component Release operationId: getLatestCollection parameters: - name: uuid in: path required: true description: UUID of TEA Component Release in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: Requested TEA Collection found and returned content: application/json: schema: "$ref": "#/components/schemas/collection" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Component Release /productRelease/{uuid}/collection/latest: get: description: Get the latest TEA Collection belonging to the TEA Product Release operationId: getLatestCollectionForProductRelease parameters: - name: uuid in: path required: true description: UUID of TEA Product Release in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: Requested TEA Collection found and returned content: application/json: schema: "$ref": "#/components/schemas/collection" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Product Release /componentRelease/{uuid}/collections: get: description: Get the TEA Collections belonging to the TEA Component Release operationId: getCollectionsByReleaseId parameters: - name: uuid in: path required: true description: UUID of TEA Component Release in the TEA server schema: "$ref": "#/components/schemas/uuid" - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/page-token" - $ref: "#/components/parameters/sort-field-collection" - $ref: "#/components/parameters/sort-order" responses: '200': $ref: "#/components/responses/paginated-collection" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Component Release /productRelease/{uuid}/collections: get: description: Get the TEA Collections belonging to the TEA Product Release operationId: getCollectionsByProductReleaseId parameters: - name: uuid in: path required: true description: UUID of TEA Product Release in the TEA server schema: "$ref": "#/components/schemas/uuid" - $ref: "#/components/parameters/page-size" - $ref: "#/components/parameters/page-token" - $ref: "#/components/parameters/sort-field-collection" - $ref: "#/components/parameters/sort-order" responses: '200': $ref: "#/components/responses/paginated-collection" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Product Release /productRelease/{uuid}/collection/{collectionVersion}: get: description: Get a specific Collection (by version) for a TEA Product Release by its UUID operationId: getCollectionForProductRelease parameters: - name: uuid in: path required: true description: UUID of TEA Product Release in the TEA server schema: "$ref": "#/components/schemas/uuid" - name: collectionVersion in: path required: true description: Version of TEA Collection schema: type: integer responses: '200': description: Requested TEA Collection Version found and returned content: application/json: schema: "$ref": "#/components/schemas/collection" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Product Release /componentRelease/{uuid}/collection/{collectionVersion}: get: description: Get a specific Collection (by version) for a TEA Component Release by its UUID operationId: getCollection parameters: - name: uuid in: path required: true description: UUID of TEA Collection in the TEA server schema: "$ref": "#/components/schemas/uuid" - name: collectionVersion in: path required: true description: Version of TEA Collection schema: type: integer responses: '200': description: Requested TEA Collection Version found and returned content: application/json: schema: "$ref": "#/components/schemas/collection" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Component Release /artifact/{uuid}/latest: get: description: Get metadata for latest revision of a specific TEA Artifact operationId: getLatestArtifact parameters: - name: uuid in: path required: true description: UUID of TEA Artifact in the TEA server schema: "$ref": "#/components/schemas/uuid" responses: '200': description: Requested TEA Artifact metadata found and returned content: application/json: schema: "$ref": "#/components/schemas/artifact" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Artifact /artifact/{uuid}/{artifactVersion}: get: description: Get metadata for a specific revision of a specific TEA Artifact operationId: getArtifactByVersion parameters: - name: uuid in: path required: true description: UUID of TEA Artifact in the TEA server schema: "$ref": "#/components/schemas/uuid" - name: artifactVersion in: path required: true description: Version of TEA Artifact schema: type: integer responses: '200': description: Requested TEA Artifact metadata found and returned content: application/json: schema: "$ref": "#/components/schemas/artifact" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Artifact /artifact/{uuid}/latest/download: get: description: | Download the content of the latest revision of a specific TEA Artifact. Equivalent to the versioned download endpoint, resolving to whichever revision `/artifact/{uuid}/latest` currently reports. The content this returns changes when a new revision is published, so unlike the versioned endpoint the response is not immutable: caches shall revalidate it, which the `ETag` of the resolved revision makes cheap. The `Content-Location` header names the versioned URL the request was resolved to; clients that need a stable, reproducible reference use that URL. operationId: downloadLatestArtifact parameters: - name: uuid in: path required: true description: UUID of TEA Artifact in the TEA server schema: "$ref": "#/components/schemas/uuid" - $ref: "#/components/parameters/artifact-media-type" responses: '200': $ref: "#/components/responses/artifact-content-latest" '302': $ref: "#/components/responses/artifact-content-redirect" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" '406': $ref: "#/components/responses/406-no-acceptable-format" tags: - TEA Artifact /artifact/{uuid}/{artifactVersion}/download: get: description: | Download the content of a specific revision of a specific TEA Artifact. This endpoint returns the bytes of one `format` of the artifact revision. It is how a TEA server hosts artifact content itself: a format that has no external `url` is retrieved from here, selected by its `mediaType`. A format that has a `url` is retrieved from that external location instead, and this endpoint is not required to serve it. A TEA access token is sent only to the TEA server's own API base URL. External `url` targets are retrieved without it - they are either openly accessible, pre-signed, or covered by credentials the client arranges separately. Because a TEA Artifact revision is immutable, the response is cacheable indefinitely and servers should return a strong `ETag`. operationId: downloadArtifactByVersion parameters: - name: uuid in: path required: true description: UUID of TEA Artifact in the TEA server schema: "$ref": "#/components/schemas/uuid" - name: artifactVersion in: path required: true description: Version of TEA Artifact schema: type: integer - $ref: "#/components/parameters/artifact-media-type" responses: '200': $ref: "#/components/responses/artifact-content" '302': $ref: "#/components/responses/artifact-content-redirect" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" '406': $ref: "#/components/responses/406-no-acceptable-format" tags: - TEA Artifact /artifact/{uuid}/latest/signature/download: get: description: | Download the detached signature for the latest revision of a specific TEA Artifact. Equivalent to the versioned signature endpoint, resolving to whichever revision `/artifact/{uuid}/latest` currently reports. As with the latest content endpoint, the response is not immutable and caches shall revalidate it; `Content-Location` names the versioned URL the request was resolved to. operationId: downloadLatestArtifactSignature parameters: - name: uuid in: path required: true description: UUID of TEA Artifact in the TEA server schema: "$ref": "#/components/schemas/uuid" - $ref: "#/components/parameters/artifact-signature-media-type" responses: '200': $ref: "#/components/responses/artifact-signature-content-latest" '302': $ref: "#/components/responses/artifact-content-redirect" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" '406': $ref: "#/components/responses/406-no-acceptable-format" tags: - TEA Artifact /artifact/{uuid}/{artifactVersion}/signature/download: get: description: | Download the detached signature for one format of a specific revision of a specific TEA Artifact. This is the counterpart of the artifact content endpoint, for TEA servers that host signatures themselves: a format that has no external `signatureUrl` is retrieved from here, selected by its `mediaType`. A format that has a `signatureUrl` is retrieved from that external location instead, and this endpoint is not required to serve it. Signatures are per format: each format of a revision is a distinct sequence of bytes and therefore has its own signature. The `mediaType` parameter selects which format's signature is returned, not the format of the signature itself. This specification makes no assumption about the signature technology in use, and does not model the signing algorithm, key, or certificate chain; the response is the signature as published. A client that cannot determine how to verify what it receives should treat the signature as unusable rather than as invalid. `404` is returned both when the artifact revision does not exist and when the selected format has no signature published. operationId: downloadArtifactSignatureByVersion parameters: - name: uuid in: path required: true description: UUID of TEA Artifact in the TEA server schema: "$ref": "#/components/schemas/uuid" - name: artifactVersion in: path required: true description: Version of TEA Artifact schema: type: integer - $ref: "#/components/parameters/artifact-signature-media-type" responses: '200': $ref: "#/components/responses/artifact-signature-content" '302': $ref: "#/components/responses/artifact-content-redirect" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" '406': $ref: "#/components/responses/406-no-acceptable-format" tags: - TEA Artifact /token: post: description: | Exchange credentials for a TEA access token. A TEA server that requires authentication on any of its endpoints shall implement this endpoint, and shall support the `client_credentials` grant type with HTTP Basic client authentication (RFC 6749 section 2.3.1, RFC 7617): the API key identifier is sent as the user-id and the API key secret as the password. A server that requires no authentication need not implement it. Clients do not probe this endpoint to discover whether authentication is required: they issue the resource request, and a `401` response carrying a `WWW-Authenticate: Bearer` challenge is the signal to obtain a token here. A `404` from this endpoint means only that it is not implemented. Servers may support additional grant types for federated identity, for example SAML 2.0 assertions (RFC 7522) or JWT assertions (RFC 7523), and may authenticate the client with mutual TLS (RFC 8705) instead of Basic. Whichever grant type is used, the token returned by this endpoint is the only credential accepted on the other TEA endpoints. RFC 8693 token exchange (`urn:ietf:params:oauth:grant-type:token-exchange`) is outside the scope of the TEA 1.0 interoperable authentication profile. TEA 1.0 does not specify the request or response contract for this grant. Implementations may support it as an extension by separate agreement, but clients shall not assume its availability based solely on TEA 1.0 conformance. Such extensions do not remove the requirement for servers requiring authentication to support the `client_credentials` baseline. The access token is opaque to the client: clients shall not inspect, parse, or depend on its contents. operationId: requestToken security: - basicAuth: [] - {} requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/token-request" responses: '200': $ref: "#/components/responses/token-issued" '400': $ref: "#/components/responses/400-token-error" '401': $ref: "#/components/responses/401-token-error" tags: - TEA Authentication /discovery: get: description: | Discovery endpoint which resolves an identifier into product release UUID. Exactly one of the `tei` and `purl` query parameters shall be provided. A request with neither, or with both, is rejected with `400`. OpenAPI cannot express this constraint on query parameters, so both are declared optional here. Discovery by TEI resolves the product across TEA servers, using the domain carried by the TEI. Discovery by PURL resolves the product within the inventory of the TEA server that receives the request. Parameter values are the identifier itself (not a pre-encoded wire form). Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step. Escapes that are part of a PURL value are preserved by that single decode. Example request lines after serialization: - `.../discovery?tei=tei%3A%2F%2Fproducts.example.com%2Fuuid%2F47f51950-b0e2-11f1-adc2-1a52914d44b2` - `.../discovery?purl=pkg%3Amaven%2Forg.apache.logging.log4j%2Flog4j-core%402.24.3` operationId: discoveryByTei parameters: - name: tei in: query required: false description: | Transparency Exchange Identifier (TEI) for the product being discovered, as the logical TEI string. Do not pre-encode for the schema example or client model; apply query-parameter encoding once when forming the HTTP request. schema: type: string examples: - tei://products.example.com/uuid/47f51950-b0e2-11f1-adc2-1a52914d44b2 - name: purl in: query required: false description: | Package URL (PURL) of the product being discovered, resolved within this TEA server's inventory, as the logical PURL string. Do not pre-encode for the schema example or client model; apply query-parameter encoding once when forming the HTTP request. schema: type: string examples: - pkg:maven/org.apache.logging.log4j/log4j-core@2.24.3 responses: '200': $ref: "#/components/responses/discovery-response" '400': $ref: "#/components/responses/400-invalid-request" '404': $ref: "#/components/responses/404-object-by-id-not-found" tags: - TEA Discovery components: schemas: # # Definitions reused in multiple domain objects # date-time: type: string description: Timestamp format: date-time pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" example: '2024-03-20T15:30:00Z' token-request: type: object description: | Token request for the `client_credentials` grant, as defined in RFC 6749 section 4.4.2, or an optional assertion grant identified below. The `scope` parameter applies to both. The `assertion` parameter applies only to assertion grants. RFC 8693 token exchange is outside the TEA 1.0 profile (see `/token` description). required: - grant_type properties: grant_type: type: string description: | OAuth 2.0 grant type. Servers shall support `client_credentials`. Servers may support assertion grants (`urn:ietf:params:oauth:grant-type:saml2-bearer`, `urn:ietf:params:oauth:grant-type:jwt-bearer`). Token exchange (`urn:ietf:params:oauth:grant-type:token-exchange`) is outside the TEA 1.0 interoperable authentication profile; see `/token`. example: client_credentials scope: type: string description: | Optional space-delimited scope request (RFC 6749 section 3.3). TEA does not define scope values; servers may ignore this parameter. assertion: type: string description: Assertion value, when an assertion grant type is used (RFC 7521 section 4.1). token-response: type: object description: Successful token response, as defined in RFC 6749 section 5.1. required: - access_token - token_type properties: access_token: type: string description: | The issued access token, presented on other TEA endpoints as `Authorization: Bearer `. Opaque to the client. example: 2YotnFZFEjr1zCsicMWpAA token_type: type: string description: Token type. Always `Bearer` in TEA. const: Bearer expires_in: type: integer description: | Lifetime of the access token in seconds. Servers should include this so that clients can re-authenticate before expiry rather than on failure. example: 3600 scope: type: string description: Granted scope, when it differs from the scope requested. token-error-response: type: object description: Token error response, as defined in RFC 6749 section 5.2. required: - error properties: error: type: string description: Error code as defined in RFC 6749 section 5.2. enum: - invalid_request - invalid_client - invalid_grant - unauthorized_client - unsupported_grant_type - invalid_scope error_description: type: string description: Human-readable text providing additional information about the error. error_uri: type: string format: uri description: URI of a human-readable web page with information about the error. identifier: type: object description: An identifier with a specified type properties: idType: description: Type of identifier, e.g. `TEI`, `PURL`, `CPE` "$ref": "#/components/schemas/identifier-type" idValue: description: Identifier value type: string identifier-type: type: string description: Enumeration of identifiers types enum: - CPE - TEI - PURL - COMPLIANCE_DOCUMENT compliance-document-type: type: string description: > Well-known compliance document types. When idType is COMPLIANCE_DOCUMENT, the idValue SHOULD be one of these values. enum: - SOC_2_TYPE_I - SOC_2_TYPE_II - SOC_3 - ISO_27001 - ISO_27017 - ISO_27018 - ISO_27701 - ISO_42001 - PCI_DSS - HIPAA - FedRAMP - GDPR - CSA_STAR - NIST_800_53 - NIST_800_171 - CMMC - HITRUST - TISAX - CYBER_ESSENTIALS - CYBER_ESSENTIALS_PLUS uuid: type: string description: A UUID format: uuid pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" # # TEA Product # product: type: object description: A TEA product properties: uuid: description: A unique identifier for the TEA product "$ref": "#/components/schemas/uuid" name: type: string description: | Product name. Within a TEA server, product names SHOULD be unique among products. Uniqueness is an implementation recommendation, not a hard API requirement. Product and component names are separate namespaces; a product and a component MAY share the same name. identifiers: type: array description: | List of identifiers for the product, like TEI, CPE, PURL or other identifiers items: "$ref": "#/components/schemas/identifier" required: - uuid - name - identifiers examples: - 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 # # TEA Product Release # productRelease: type: object description: A specific release of a TEA product properties: uuid: description: A unique identifier for the TEA Product Release "$ref": "#/components/schemas/uuid" product: description: UUID of the TEA Product this release belongs to "$ref": "#/components/schemas/uuid" productName: description: Name of the TEA Product this release belongs to type: string example: Apache Log4j 2 version: description: Version number of the product release type: string example: 2.24.3 createdDate: description: Timestamp when this Product Release was created in TEA (for sorting purposes) "$ref": "#/components/schemas/date-time" releaseDate: description: Timestamp of the product release "$ref": "#/components/schemas/date-time" preRelease: type: boolean description: | 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: type: array description: List of identifiers for the product release items: "$ref": "#/components/schemas/identifier" components: type: array description: | List 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. items: "$ref": "#/components/schemas/component-ref" required: - uuid - version - createdDate - components examples: - uuid: 123e4567-e89b-12d3-a456-426614174000 version: "2.24.3" createdDate: 2025-04-01T15:43:00Z releaseDate: 2025-04-01T15:43:00Z 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 # # TEA Component and related objects # component: type: object description: A TEA component properties: uuid: description: A unique identifier for the TEA component "$ref": "#/components/schemas/uuid" name: type: string description: | Component name. Within a TEA server, component names SHOULD be unique among components. Uniqueness is an implementation recommendation, not a hard API requirement. Product and component names are separate namespaces; a product and a component MAY share the same name. identifiers: type: array description: List of identifiers for the component items: "$ref": "#/components/schemas/identifier" required: - uuid - name - identifiers examples: - 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 # # Reference to a component, in some cases directly to a specific release # # The release reference (release UUID) is only used in cases where a product # name includes a version and this version of the product always includes # the same releases of the component. component-ref: type: object description: A reference to a TEA component or specific component release properties: uuid: description: A unique identifier for the TEA component "$ref": "#/components/schemas/uuid" release: description: | Optional UUID of a specific release included in the product in the case where the product always include a specific release of a component. The product name should include a version identifier in this case. "$ref": "#/components/schemas/uuid" required: - uuid # # TEA Component Release and related objects # release: type: object description: A TEA Component Release properties: uuid: description: A unique identifier for the TEA Component Release "$ref": "#/components/schemas/uuid" component: description: UUID of the TEA Component this release belongs to "$ref": "#/components/schemas/uuid" componentName: description: Name of the TEA Component this release belongs to type: string example: tomcat version: description: Version number type: string example: 1.2.3 createdDate: description: Timestamp when this Release was created in TEA (for sorting purposes) "$ref": "#/components/schemas/date-time" releaseDate: description: Timestamp of the release "$ref": "#/components/schemas/date-time" preRelease: type: boolean description: | 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: type: array description: List of identifiers for the component items: "$ref": "#/components/schemas/identifier" distributions: type: array description: List of different formats of this component release items: "$ref": "#/components/schemas/release-distribution" required: - uuid - version - createdDate examples: # Apache Tomcat 11.0.7 - uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345 version: "11.0.7" 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.zip.asc - distributionId: de45ffaf-e4b5-47b5-be28-444a76df098e description: Core binary distribution, Windows Service Installer (MSI) 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 # A pre-release of Apache Tomcat - uuid: 95f481df-f760-47f4-b2f2-f8b76d858450 version: "11.0.0-M26" createdDate: 2024-09-13T17:49:00Z preRelease: true identifiers: - idType: PURL idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26 release-distribution: type: object properties: distributionId: description: A unique identifier for the TEA Distribution object "$ref": "#/components/schemas/uuid" description: type: string description: Free-text description of the distribution. identifiers: type: array description: List of identifiers specific to this distribution. items: $ref: "#/components/schemas/identifier" url: type: string description: Direct download URL for the distribution. format: url signatureUrl: type: string description: Direct download URL for the distribution's external signature. format: url checksums: type: array description: | List of checksums for the distribution payload retrieved from `url` (the distribution bytes, not the signature at `signatureUrl`). items: "$ref": "#/components/schemas/checksum" required: - distributionId examples: - 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 (MSI) 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 component-release-with-collection: type: object description: A TEA Component Release combined with its latest collection properties: release: description: The TEA Component Release information $ref: "#/components/schemas/release" latestCollection: description: The latest TEA Collection for this component release $ref: "#/components/schemas/collection" required: - release - latestCollection examples: - release: uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345 version: "11.0.7" 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 latestCollection: uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345 version: 2 date: 2025-05-12T18:08:00Z belongsTo: COMPONENT_RELEASE updateReason: type: INITIAL_RELEASE comment: Initial collection for this release artifacts: - uuid: 1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce name: Build SBOM type: BOM formats: - mediaType: application/vnd.cyclonedx+xml description: CycloneDX SBOM (XML) url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-cyclonedx.xml checksums: - algType: SHA-256 algValue: 9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1 - uuid: dfa35519-9734-4259-bba1-3e825cf4be06 name: Vulnerability Disclosure Report type: VULNERABILITIES formats: - mediaType: application/vnd.cyclonedx+xml description: CycloneDX VDR (XML) url: https://tomcat.apache.org/cyclonedx/vdr.xml checksums: - algType: SHA-256 algValue: 75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a # # TEA Collection and related objects # collection: type: object description: A collection of security-related documents properties: uuid: description: | UUID of the TEA Collection object. This matches the UUID of the associated TEA Component Release or TEA Product Release object. When updating a collection, only the `version` is changed. "$ref": "#/components/schemas/uuid" version: type: integer description: | TEA Collection version, incremented each time its content changes. Versions start with 1. date: description: The date when the TEA Collection version was created. "$ref": "#/components/schemas/date-time" belongsTo: description: Indicates whether this collection belongs to a Component Release or a Product Release "$ref": "#/components/schemas/collection-belongs-to-type" updateReason: description: Reason for the update/release of the TEA Collection object. "$ref": "#/components/schemas/collection-update-reason" artifacts: type: array description: List of TEA Artifact objects. items: "$ref": "#/components/schemas/artifact" examples: # Documents in the latest release of Log4j Core - uuid: 4c72fe22-9d83-4c2f-8eba-d6db484f32c8 version: 10 date: 2024-12-13T00:00:00Z updateReason: type: ARTIFACT_UPDATED comment: VDR file updated artifacts: - uuid: 1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce 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: MD5 algValue: 2e1a525afc81b0a8ecff114b8b743de9 - algType: SHA-1 algValue: 5a7d4caef63c5c5ccdf07c39337323529eb5a770 - uuid: dfa35519-9734-4259-bba1-3e825cf4be06 version: 7 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 collection-update-reason: type: object description: Reason for the update to the TEA collection properties: type: description: Type of update reason. "$ref": "#/components/schemas/collection-update-reason-type" comment: type: string description: Free text description collection-update-reason-type: type: string description: Type of TEA collection update enum: - INITIAL_RELEASE - VEX_UPDATED - ARTIFACT_UPDATED - ARTIFACT_ADDED - ARTIFACT_REMOVED collection-belongs-to-type: type: string description: Indicates whether a collection belongs to a component release or a product release enum: - COMPONENT_RELEASE - PRODUCT_RELEASE # # TEA Artifact and related objects # artifact: type: object description: A security-related document properties: uuid: description: The UUID of the TEA Artifact object. Together with *version* uniquely identifies the TEA Artifact. "$ref": "#/components/schemas/uuid" version: description: | An integer with default value 1. Together with *uuid* uniquely identifies the TEA Artifact. This field can be used to designate successive, immutable revisions of an artefact content (e.g. an updated VEX file). type: integer default: 1 name: type: string description: Name of TEA Artifact type: description: Type of TEA Artifact "$ref": "#/components/schemas/artifact-type" createdDate: description: The date when the TEA Artifact revision was created. "$ref": "#/components/schemas/date-time" distributionIds: type: array description: | List of TEA Component Release distributions that this TEA Artifact applies to. If absent or empty, the TEA Artifact applies to all distributions. items: "$ref": "#/components/schemas/uuid" description: | The distribution IDs of the TEA component release distributions that this TEA Artifact applies to. formats: type: array description: | List of objects with the same content, but in different formats. The order of the list has no significance. items: "$ref": "#/components/schemas/artifact-format" required: - uuid - type - formats examples: - uuid: 1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce 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: MD5 algValue: 2e1a525afc81b0a8ecff114b8b743de9 - algType: SHA-1 algValue: 5a7d4caef63c5c5ccdf07c39337323529eb5a770 - uuid: dfa35519-9734-4259-bba1-3e825cf4be06 version: 7 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 artifact-type: type: string description: Specifies the type of external reference. enum: - ATTESTATION - BOM - BUILD_META - CERTIFICATION - FORMULATION - LICENSE - RELEASE_NOTES - SECURITY_TXT - THREAT_MODEL - VULNERABILITIES - OTHER artifact-format: type: object description: A security-related document in a specific format required: - mediaType properties: mediaType: type: string description: | The Media Type of the document. A media type shall appear at most once across the `formats` of a single TEA Artifact revision, so that every format can be selected unambiguously by media type when downloading its content or its signature. description: type: string description: A free text describing the TEA Artifact url: type: string description: | External download URL for this format of the TEA Artifact. This is always a location 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}/{artifactVersion}/download`, selecting this format by its `mediaType`. A TEA access token is sent only to the TEA server's own API base URL, never to an external URL: external locations are either openly accessible, pre-signed, or covered by credentials the client arranges separately. When the URL is pre-signed it may expire; clients should not retain it beyond the freshness lifetime of the response that carried it. format: url signatureUrl: type: string description: | External download URL for a detached signature of this format of the TEA Artifact. As with `url`, this is always a location outside the TEA API. When present, clients shall retrieve the signature from it. When absent, clients shall retrieve it from the artifact signature download endpoint, `/artifact/{uuid}/{artifactVersion}/signature/download`, selecting this format by its `mediaType`; that endpoint returns `404` when no signature is published for the format. The same access token and pre-signed URL rules as for `url` apply. This specification does not define which signature technology is used, nor model the signing algorithm, key, or certificate chain. format: url checksums: type: array description: | List of checksums for this artifact format's content bytes (the payload retrieved from `url` or from the artifact download endpoint for this `mediaType`), not the detached signature. items: "$ref": "#/components/schemas/checksum" checksum: type: object description: | Integrity digest for identified content bytes. `algValue` is the lowercase hexadecimal encoding of the digest produced by `algType` over those bytes. The hex length shall match the algorithm's digest size (for example 32 for MD5, 40 for SHA-1, 64 for SHA-256 / SHA3-256 / BLAKE2b-256 / BLAKE3, 96 for SHA-384 / SHA3-384 / BLAKE2b-384, 128 for SHA-512 / SHA3-512 / BLAKE2b-512). properties: algType: description: Checksum algorithm "$ref": "#/components/schemas/checksum-type" algValue: type: string description: | Lowercase hexadecimal digest value for `algType`. Do not use Base64 or uppercase hex. pattern: '^[0-9a-f]+$' minLength: 32 maxLength: 128 example: 9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1 required: - algType - algValue checksum-type: type: string description: Checksum algorithm enum: - MD5 - SHA-1 - SHA-256 - SHA-384 - SHA-512 - SHA3-256 - SHA3-384 - SHA3-512 - BLAKE2b-256 - BLAKE2b-384 - BLAKE2b-512 - BLAKE3 unknown-error-type: type: string description: Classification of TEA error response enum: - OBJECT_UNKNOWN - OBJECT_NOT_SHAREABLE # # Types used in API responses # error-response: type: object description: Error response additionalProperties: false properties: error: $ref: "#/components/schemas/unknown-error-type" required: - error tea-server-info: type: object description: TEA server information including URL, versions, and optional priority additionalProperties: false properties: rootUrl: description: Root URL of the TEA server for this TEI without trailing slash type: string format: uri example: https://api.teaexample.com versions: description: Supported TEA API versions at this server without v prefix type: array minItems: 1 items: type: string example: ["0.2.0-beta.2", "1.0.0"] priority: description: Optional priority for this server (0.0 to 1.0, where 1.0 is highest priority) type: number format: float minimum: 0.0 maximum: 1.0 example: 0.8 required: - rootUrl - versions discovery-info: type: object description: Discovery information for a TEI additionalProperties: false properties: productReleaseUuid: description: UUID of the resolved TEA Product Release $ref: "#/components/schemas/uuid" example: d4d9f54a-abcf-11ee-ac79-1a52914d44b1 servers: description: Array of TEA server information type: array minItems: 1 items: $ref: "#/components/schemas/tea-server-info" required: - productReleaseUuid - servers # # CLE (Common Lifecycle Enumeration) objects # Based on ECMA-428 TC54 TG3 CLE Specification v1.0.0 # cle-event-type: type: string description: The type of CLE lifecycle event enum: - released - endOfDevelopment - endOfSupport - endOfLife - endOfDistribution - endOfMarketing - supersededBy - componentRenamed - withdrawn cle-version-specifier: type: object description: A version specifier that can be either a single version or a version range properties: version: type: string description: A specific version string range: type: string description: A version range in vers format (e.g. "vers:npm/>=1.0.0|<2.0.0") cle-event: type: object description: A discrete lifecycle event from the CLE specification properties: id: type: integer description: A unique, auto-incrementing integer identifier for the event type: description: The type of lifecycle event $ref: "#/components/schemas/cle-event-type" effective: type: string format: date-time description: ISO 8601 timestamp (UTC) when the event takes effect published: type: string format: date-time description: ISO 8601 timestamp (UTC) when the event was first published version: type: string description: Version string (used by released event type) versions: type: array description: List of version specifiers affected by this event items: $ref: "#/components/schemas/cle-version-specifier" supportId: type: string description: Reference to a support policy ID defined in the definitions section license: type: string description: License identifier (used by released event type) supersededByVersion: type: string description: Version string that supersedes the affected versions (used by supersededBy event type) identifiers: type: array description: New identifiers for the component (used by componentRenamed event type) items: $ref: "#/components/schemas/identifier" eventId: type: integer description: ID of the event being withdrawn (used by withdrawn event type) reason: type: string description: Human-readable explanation (used by withdrawn event type) description: type: string description: Human-readable description of the event references: type: array description: List of URLs to supporting documentation items: type: string format: uri required: - id - type - effective - published examples: - id: 1 type: released effective: "2024-01-01T00:00:00Z" version: "1.0.0" license: MIT published: "2023-06-01T00:00:00Z" - id: 3 type: endOfSupport effective: "2024-01-01T00:00:00Z" versions: - version: "1.0.0" supportId: standard published: "2023-06-01T00:00:00Z" cle-support-definition: type: object description: A support policy definition from CLE properties: id: type: string description: Unique identifier for the support policy description: type: string description: Human-readable description of the policy url: type: string format: uri description: URL to detailed documentation about this support policy required: - id - description examples: - id: standard description: Standard product support policy url: https://example.com/support/standard cle-definitions: type: object description: Container for reusable CLE policy definitions properties: support: type: array description: List of support policies items: $ref: "#/components/schemas/cle-support-definition" cle: type: object description: | Common Lifecycle Enumeration (CLE) object based on ECMA-428 TC54 TG3 CLE Specification v1.0.0. Contains lifecycle events and optional reusable definitions for a component or product. properties: events: type: array description: | Ordered array of CLE Event objects representing lifecycle events. MUST be ordered by ID in descending order (newest events with highest IDs first). items: $ref: "#/components/schemas/cle-event" definitions: description: Container for reusable policy definitions referenced by events $ref: "#/components/schemas/cle-definitions" required: - events examples: - events: - id: 3 type: endOfSupport effective: "2025-06-01T00:00:00Z" versions: - range: "vers:npm/>=1.0.0|<2.0.0" supportId: standard published: "2025-01-01T00:00:00Z" - id: 2 type: endOfDevelopment effective: "2025-01-01T00:00:00Z" versions: - version: "1.0.0" supportId: standard published: "2024-06-01T00:00:00Z" - id: 1 type: released effective: "2024-01-01T00:00:00Z" version: "1.0.0" license: Apache-2.0 published: "2024-01-01T00:00:00Z" definitions: support: - id: standard description: Standard product support policy url: https://example.com/support/standard pagination-details: type: object properties: hasNext: type: boolean description: | A flag indicating whether there is another page of results to fetch. When `hasNext` is `true`, `nextPageToken` MUST be present. When `hasNext` is `false`, `nextPageToken` MUST NOT be included. default: false nextPageToken: type: string description: | An opaque token that can be used in a following request to retrieve the next page of results. This field MUST be present when `hasNext` is `true`. This field MUST NOT be included when `hasNext` is `false`. required: - hasNext examples: - hasNext: true nextPageToken: eyJwYWdlIjoiY29udGludWF0aW9uIn0 - hasNext: false paginated-product-response: description: A paginated response containing TEA Products allOf: - $ref: "#/components/schemas/pagination-details" - type: object properties: results: type: array items: $ref: "#/components/schemas/product" required: - results examples: - hasNext: true nextPageToken: eyJwYWdlIjoiY29udGludWF0aW9uIn0 results: [] - hasNext: false results: [] paginated-product-release-response: description: A paginated response containing TEA Product Releases allOf: - $ref: "#/components/schemas/pagination-details" - type: object properties: results: type: array items: $ref: "#/components/schemas/productRelease" required: - results examples: - hasNext: true nextPageToken: eyJwYWdlIjoiY29udGludWF0aW9uIn0 results: [] - hasNext: false results: [] paginated-component-response: description: A paginated response containing TEA Components allOf: - $ref: "#/components/schemas/pagination-details" - type: object properties: results: type: array items: $ref: "#/components/schemas/component" required: - results examples: - hasNext: true nextPageToken: eyJwYWdlIjoiY29udGludWF0aW9uIn0 results: [] - hasNext: false results: [] paginated-component-release-response: description: A paginated response containing TEA Component Releases allOf: - $ref: "#/components/schemas/pagination-details" - type: object properties: results: type: array items: $ref: "#/components/schemas/release" required: - results examples: - hasNext: true nextPageToken: eyJwYWdlIjoiY29udGludWF0aW9uIn0 results: [] - hasNext: false results: [] paginated-collection-response: description: A paginated response containing TEA Collections allOf: - $ref: "#/components/schemas/pagination-details" - type: object properties: results: type: array items: $ref: "#/components/schemas/collection" required: - results examples: - hasNext: true nextPageToken: eyJwYWdlIjoiY29udGludWF0aW9uIn0 results: [] - hasNext: false results: [] headers: artifact-content-disposition: description: | Suggested filename for the artifact content, as an `attachment` disposition per RFC 6266. schema: type: string examples: - attachment; filename="log4j-core-2.24.3-cyclonedx.json" artifact-etag: description: | Strong entity tag for the content. A TEA Artifact revision is immutable, so the entity tag for a given uuid, version and format never changes. schema: type: string artifact-repr-digest: description: | Digest of the content as defined in RFC 9530, allowing a client to verify the bytes against the `checksums` published in the artifact metadata. schema: type: string artifact-cache-control-immutable: description: | Servers should mark the content of a specific revision as immutable and cacheable: the bytes for a given uuid, version and format never change. schema: type: string examples: - 'public, max-age=31536000, immutable' artifact-cache-control-latest: description: | The latest revision is a moving target: which revision it resolves to changes when a new revision is published. Servers shall not mark it immutable and should require revalidation, so that a cache reuses stored content only after confirming, through the `ETag`, that the latest revision has not changed. schema: type: string examples: - 'no-cache' artifact-content-location: description: | The versioned download URL of the revision this response was resolved to, per RFC 9110 section 8.7. A client that needs a stable, reproducible reference to the bytes it received uses this URL rather than the `latest` URL. schema: type: string format: uri-reference examples: - /artifact/2ff3ae7c-8eab-4e0b-9b8b-1a0c4c4c1c2d/3/download signature-content-disposition: description: | Suggested filename for the signature, as an `attachment` disposition per RFC 6266. schema: type: string examples: - attachment; filename="log4j-core-2.24.3-cyclonedx.json.sig" signature-etag: description: | Strong entity tag for the signature. A signature belongs to one format of one immutable revision, so it is fixed with the revision: content that is re-signed is published as a new revision. schema: type: string signature-content-location: description: | The versioned signature download URL of the revision this response was resolved to, per RFC 9110 section 8.7. schema: type: string format: uri-reference examples: - /artifact/2ff3ae7c-8eab-4e0b-9b8b-1a0c4c4c1c2d/3/signature/download responses: 204-common-delete: description: Object deleted successfully content: application/json: {} 400-invalid-request: description: | Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting `pageToken` values, including conflicts with continuation parameters or path parameters. content: application/json: {} 401-unauthorized: description: | Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a `WWW-Authenticate` header as defined in RFC 6750 section 3. On the `invalid_token` error a client may obtain a fresh token from `/token` and retry the request once (RFC 6750 section 3.1). headers: WWW-Authenticate: description: Bearer challenge, as defined in RFC 6750 section 3. schema: type: string example: Bearer realm="tea", error="invalid_token", error_description="The access token expired" content: application/json: {} artifact-content: description: | The content of the requested TEA Artifact format. The `Content-Type` is the `mediaType` of the format returned. headers: Content-Disposition: $ref: "#/components/headers/artifact-content-disposition" ETag: $ref: "#/components/headers/artifact-etag" Cache-Control: $ref: "#/components/headers/artifact-cache-control-immutable" Repr-Digest: $ref: "#/components/headers/artifact-repr-digest" content: application/octet-stream: schema: type: string format: binary artifact-content-latest: description: | The content of the selected format of the latest revision of the TEA Artifact, as resolved at the time of the request. Identical to `artifact-content` except for its cache policy: the latest revision changes when a new revision is published, so the response is not immutable and a cache shall revalidate it before reuse. The `ETag` is that of the resolved revision's content, so revalidation succeeds with `304 Not Modified` until a new revision is published. `Content-Location` names the versioned URL the request was resolved to. headers: Content-Disposition: $ref: "#/components/headers/artifact-content-disposition" ETag: $ref: "#/components/headers/artifact-etag" Cache-Control: $ref: "#/components/headers/artifact-cache-control-latest" Content-Location: $ref: "#/components/headers/artifact-content-location" Repr-Digest: $ref: "#/components/headers/artifact-repr-digest" content: application/octet-stream: schema: type: string format: binary artifact-signature-content: description: | The detached signature for the selected format of the TEA Artifact revision. The `Content-Type` is `application/octet-stream` unless the server knows a more specific media type for the signature it holds, in which case it returns that. This specification does not require servers to identify the signature technology. headers: Content-Disposition: $ref: "#/components/headers/signature-content-disposition" ETag: $ref: "#/components/headers/signature-etag" Cache-Control: $ref: "#/components/headers/artifact-cache-control-immutable" content: application/octet-stream: schema: type: string format: binary artifact-signature-content-latest: description: | The detached signature for the selected format of the latest revision of the TEA Artifact, as resolved at the time of the request. Identical to `artifact-signature-content` except for its cache policy: the latest revision changes when a new revision is published, so the response is not immutable and a cache shall revalidate it before reuse. `Content-Location` names the versioned URL the request was resolved to. headers: Content-Disposition: $ref: "#/components/headers/signature-content-disposition" ETag: $ref: "#/components/headers/signature-etag" Cache-Control: $ref: "#/components/headers/artifact-cache-control-latest" Content-Location: $ref: "#/components/headers/signature-content-location" content: application/octet-stream: schema: type: string format: binary artifact-content-redirect: description: | The artifact content is available at another location, for example object storage addressed by a pre-signed URL. The client follows the `Location` header. A client shall not send its TEA access token when following a redirect to a different origin. headers: Location: description: Location the artifact content can be retrieved from. required: true schema: type: string format: uri 406-no-acceptable-format: description: | The artifact revision exists, but has no format matching the requested `mediaType` or `Accept` header. content: application/json: schema: $ref: "#/components/schemas/error-response" token-issued: description: Credentials accepted, access token issued headers: Cache-Control: description: Servers shall set `no-store` on token responses (RFC 6749 section 5.1). schema: type: string example: no-store content: application/json: schema: $ref: "#/components/schemas/token-response" 400-token-error: description: | The token request was malformed, used an unsupported grant type, or the credentials presented were not valid for the requested grant. content: application/json: schema: $ref: "#/components/schemas/token-error-response" 401-token-error: description: | Client authentication failed. Returned instead of 400 when the client attempted to authenticate using the `Authorization` header (RFC 6749 section 5.2). headers: WWW-Authenticate: description: Challenge indicating the client authentication methods supported by the token endpoint. schema: type: string example: Basic realm="tea" content: application/json: schema: $ref: "#/components/schemas/token-error-response" 404-object-by-id-not-found: description: Object requested by identifier not found content: application/json: schema: $ref: "#/components/schemas/error-response" discovery-response: description: Discovery information for the requested TEI content: application/json: schema: type: array items: $ref: "#/components/schemas/discovery-info" paginated-product: description: A paginated response containing TEA Products content: application/json: schema: $ref: "#/components/schemas/paginated-product-response" paginated-product-release: description: A paginated response containing TEA Product Releases content: application/json: schema: $ref: "#/components/schemas/paginated-product-release-response" paginated-component: description: A paginated response containing TEA Components content: application/json: schema: $ref: "#/components/schemas/paginated-component-response" paginated-component-release: description: A paginated response containing TEA Component Releases content: application/json: schema: $ref: "#/components/schemas/paginated-component-release-response" paginated-collection: description: A paginated response containing TEA Collections content: application/json: schema: $ref: "#/components/schemas/paginated-collection-response" parameters: # Artifact content artifact-media-type: name: mediaType description: | Selects which of the artifact revision's `formats` to return, by its `mediaType`. The parameter value is the media type itself (for example `application/vnd.cyclonedx+json`), not a pre-encoded wire form. Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step. When omitted, the server selects a format using the request's `Accept` header per RFC 9110 section 12, and falls back to a format of its choice when `Accept` does not constrain the result. In either case the `Content-Type` of the response states which format was returned. Example after serialization: `.../download?mediaType=application%2Fvnd.cyclonedx%2Bjson` in: query required: false schema: type: string examples: - application/vnd.cyclonedx+json artifact-signature-media-type: name: mediaType description: | Selects which of the artifact revision's `formats` the returned signature applies to, by that format's `mediaType`. This is the media type of the signed content, not of the signature. The parameter value is the media type itself, not a pre-encoded wire form. Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step. When omitted, the server selects a format of its choice. Requests that need a specific format's signature should always supply this parameter, since the response does not otherwise state which format was signed. Example after serialization: `.../download/signature?mediaType=application%2Fvnd.cyclonedx%2Bjson` in: query required: false schema: type: string examples: - application/vnd.cyclonedx+json # Pagination page-size: name: pageSize description: The maximum number of results to return. in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 25 page-token: name: pageToken description: | An opaque continuation token produced by a previous response. This token MUST be copied verbatim from the `nextPageToken` value returned by the previous response. Clients MUST NOT parse, construct, or modify this token. The token represents continuation state for the original query, including `sortField`, `sortOrder`, result-affecting filters such as `idType` and `idValue`, and path parameters such as parent `uuid`. When `pageToken` is supplied, clients MUST NOT change those result-affecting query parameters. Servers MUST return `400 Bad Request` if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients MUST start a new pagination sequence without `pageToken`. A `pageToken` is only valid with the same request path and same path parameter values used to obtain it. Clients MUST NOT reuse a `pageToken` across different parent resource paths or different path `uuid` values. Servers MUST return `400 Bad Request` when a `pageToken` is used with a different path or different path parameter values. Servers MUST return `400 Bad Request` for malformed, invalid, expired, or conflicting `pageToken` values. in: query required: false schema: type: string sort-order: name: sortOrder description: | The direction of the sort. The default is `asc` for all paginated resources. Clients that need newest release or collection versions first can request `sortOrder=desc`. The selected sort order applies to both the primary `sortField` and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is `uuid`. For collections, the secondary key is `version` if additional tie-breaking is needed. in: query required: false schema: type: string enum: - asc - desc default: asc # Pagination Sort Fields per TEA Object Type sort-field-collection: name: sortField description: | The field by which to sort the results. Paginated collection results MUST be ordered first by the selected `sortField`, then by `version` as the deterministic secondary key if additional tie-breaking is needed. Collection UUIDs are not used as tie-breakers because collection UUIDs match the associated release UUID and can be shared across collection revisions. The only currently supported collection `sortField` is `version`, so the secondary `version` key is redundant unless additional collection sort fields are added later. in: query required: false schema: type: string enum: - version default: version sort-field-component: name: sortField description: | The field by which to sort the results. Paginated results MUST be ordered first by the selected `sortField`, then by `uuid` as a deterministic secondary tie-breaker. in: query required: false schema: type: string enum: - name default: name sort-field-component-release: name: sortField description: | The field by which to sort the results. Paginated results MUST be ordered first by the selected `sortField`, then by `uuid` as a deterministic secondary tie-breaker. When `version` is selected, ordering is by the stored version string according to the server's documented string collation; semantic-version precedence is not implied. Servers MUST apply a stable and deterministic string collation for version sorting, and the same collation MUST be used consistently across pages for a pagination sequence. When `releaseDate` is selected, releases without a `releaseDate` MUST be ordered consistently. Missing `releaseDate` values sort after populated `releaseDate` values for ascending order and before populated `releaseDate` values for descending order. in: query required: false schema: type: string enum: - createdDate - releaseDate - version default: createdDate sort-field-product: name: sortField description: | The field by which to sort the results. Paginated results MUST be ordered first by the selected `sortField`, then by `uuid` as a deterministic secondary tie-breaker. in: query required: false schema: type: string enum: - name default: name sort-field-product-release: name: sortField description: | The field by which to sort the results. Paginated results MUST be ordered first by the selected `sortField`, then by `uuid` as a deterministic secondary tie-breaker. When `version` is selected, ordering is by the stored version string according to the server's documented string collation; semantic-version precedence is not implied. Servers MUST apply a stable and deterministic string collation for version sorting, and the same collation MUST be used consistently across pages for a pagination sequence. When `releaseDate` is selected, releases without a `releaseDate` MUST be ordered consistently. Missing `releaseDate` values sort after populated `releaseDate` values for ascending order and before populated `releaseDate` values for descending order. in: query required: false schema: type: string enum: - createdDate - releaseDate - version default: createdDate # # Query by identifier # # Since OpenAPI 3.0 it is possible to use RFC 6570-based serialization for JSON parameters of type array or object: # https://swagger.io/docs/specification/v3_0/serialization/ # # Unfortunately many tools don't support it, for example, # the `openapi-generator` for Java does not handle this correctly. # https://github.com/OpenAPITools/openapi-generator/issues/4808 # # This can be uncommented, when RFC 6570-base serialization reaches a wider adoption: # # identifier-param: # name: identifierParam # description: If present, only the objects with the given identifier will be returned. # in: query # schema: # $ref: "#/components/schemas/identifier" # style: form # explode: true # # In the meantime we explode the object manually: id-type: # To allow RFC 6570 in the future without breaking changes to the HTTP API, # the name of this parameter should be identical to the equivalent property in /components/schemas/identifier name: idType description: Type of identifier specified in the `idValue` parameter in: query schema: $ref: "#/components/schemas/identifier-type" id-value: # To allow RFC 6570 in the future without breaking changes to the HTTP API, # the name of this parameter should be identical to the equivalent property in /components/schemas/identifier name: idValue description: If present, only the objects with the given identifier value will be returned. in: query schema: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: | A TEA access token obtained from `/token`, presented as `Authorization: Bearer ` (RFC 6750). This is the only credential accepted on TEA endpoints other than `/token`. basicAuth: type: http scheme: basic description: | API key credentials, presented to `/token` only: the API key identifier as the user-id and the API key secret as the password (RFC 7617, RFC 6749 section 2.3.1). Servers shall not accept API key credentials directly on other TEA endpoints; clients shall exchange them for an access token first. security: - bearerAuth: [] tags: - name: TEA Authentication - name: TEA Product - name: TEA Product Release - name: TEA Component - name: TEA Component Release - name: TEA Artifact - name: TEA Discovery - name: CLE externalDocs: description: Transparency Exchange API specification url: https://github.com/CycloneDX/transparency-exchange-api