# $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.3.0-beta.2
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-offset"
        - $ref: "#/components/parameters/page-size"
      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:
        - $ref: "#/components/parameters/page-offset"
        - $ref: "#/components/parameters/page-size"
        - $ref: "#/components/parameters/id-type"
        - $ref: "#/components/parameters/id-value"
      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:
        - $ref: "#/components/parameters/page-offset"
        - $ref: "#/components/parameters/page-size"
        - $ref: "#/components/parameters/id-type"
        - $ref: "#/components/parameters/id-value"
      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"
      responses:
        '200':
          description: Requested Releases of TEA Component found and returned
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/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
  /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"
      responses:
        '200':
          description: Requested TEA Collection found and returned
          content:
            application/json:
              schema:
                type: array
                items:
                  "$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}/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"
      responses:
        '200':
          description: Requested TEA Collection found and returned
          content:
            application/json:
              schema:
                type: array
                items:
                  "$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
  /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}:
    get:
      description: Get metadata for specific TEA Artifact
      operationId: getArtifact
      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
  /discovery:
    get:
      description: Discovery endpoint which resolves TEI into product release UUID.
      operationId: discoveryByTei
      parameters:
        - name: tei
          in: query
          required: true
          description: Transparency Exchange Identifier (TEI) for the product being discovered. Provide the TEI as a URL-encoded string per RFC 3986, RFC 3987.
          schema:
            type: string
            example: urn%3Atei%3Auuid%3Aproducts.example.com%3Ad4d9f54a-abcf-11ee-ac79-1a52914d44b
      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'
    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
    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
        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:product@2.24.3
          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
        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:
            - distributionType: zip
              description: Core binary distribution, zip archive
              identifiers:
                - idType: PURL
                  idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?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.6.zip
              signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc
            - distributionType: tar.gz
              description: Core binary distribution, tar.gz archive
              identifiers:
                - idType: PURL
                  idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?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.6.tar.gz
              signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz.asc
            - distributionType: windows-x64.zip
              description: Core binary distribution, Windows x64 zip archive
              identifiers:
                - idType: PURL
                  idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?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.6-windows-x64.zip
              signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc
            - distributionType: windows-x64.exe
              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:
        distributionType:
          type: string
          description: Unique identifier for the distribution type.
        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.
          items:
            "$ref": "#/components/schemas/checksum"
      required:
        - id
      examples:
        - distributionType: zip
          description: Core binary distribution, zip archive
          identifiers:
            - idType: PURL
              idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?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.6.zip
          signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc
        - distributionType: tar.gz
          description: Core binary distribution, tar.gz archive
          identifiers:
            - idType: PURL
              idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?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.6.tar.gz
          signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz.asc
        - distributionType: windows-x64.zip
          description: Core binary distribution, Windows x64 zip archive
          identifiers:
            - idType: PURL
              idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?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.6-windows-x64.zip
          signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc
        - distributionType: windows-x64.exe
          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: 3
          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
              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: UUID of the TEA Artifact object.
          "$ref": "#/components/schemas/uuid"
        name:
          type: string
          description: Name of TEA Artifact
        type:
          description: Type of TEA Artifact
          "$ref": "#/components/schemas/artifact-type"
        distributionTypes:
          type: array
          description: |
            List of component distributions types that this TEA Artifact applies to.
            If absent, the TEA Artifact applies to all distributions.
          items:
            type: string
            description: |
              The `id` of the component format 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"
    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
      properties:
        mediaType:
          type: string
          description: The MIME type of the document
        description:
          type: string
          description: A free text describing the TEA Artifact
        url:
          type: string
          description: Direct download URL for the TEA Artifact
          format: url
        signatureUrl:
          type: string
          description: Direct download URL for an external signature of the TEA Artifact
          format: url
        checksums:
          type: array
          description: List of checksums for the TEA Artifact
          items:
            "$ref": "#/components/schemas/checksum"
    checksum:
      type: object
      properties:
        algType:
          description: Checksum algorithm
          "$ref": "#/components/schemas/checksum-type"
        algValue:
          type: string
          description: Checksum value
    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-1a52914d44b
        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:
        timestamp:
          type: string
          format: date-time
          example: '2024-03-20T15:30:00Z'
        pageStartIndex:
          type: integer
          format: int64
          default: 0
        pageSize:
          type: integer
          format: int64
          default: 100
        totalResults:
          type: integer
          format: int64
      required:
        - timestamp
        - pageStartIndex
        - pageSize
        - totalResults
    
    paginated-product-response:
      type: object
      description: A paginated response containing TEA Products
      allOf:
        - $ref: "#/components/schemas/pagination-details"
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: "#/components/schemas/product"
    
    paginated-product-release-response:
      type: object
      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"
  responses:
    204-common-delete:
      description: Object deleted successfully
      content:
        application/json: {}
    400-invalid-request:
      description: Request was Invalid
      content:
        application/json: {}
    401-unauthorized:
      description: Authentication required
      content:
        application/json: {}
    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"
  parameters:
    # Pagination
    page-offset:
      name: pageOffset
      description: Pagination offset
      in: query
      required: false
      schema:
        type: integer
        format: int64
        default: 0
    page-size:
      name: pageSize
      description: Pagination offset
      in: query
      required: false
      schema:
        type: integer
        format: int64
        default: 100
    #
    # 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
    basicAuth:
      type: http
      scheme: basic
security:
  - bearerAuth: []
  - basicAuth: []
tags:
  - 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