docs: update documentation to support TEA Product Release

taleodor · taleodor · commit 96b60002cbb8 · 2025-08-17T18:01:08.000-04:00
Signed-off-by: Pavel Shukhman &lt;pavel@reliza.io&gt;
diff --git a/README.md b/README.md
@@ -54,15 +54,12 @@ The working group has produced a list of use cases and requirements for the prot
 
 ## Data model
 
-- [TEA Product](tea-product/tea-product): This is the starting point. A "product" is something for sale or distributed as an Open Source project. The [Transparency Exchange Identifier, TEI](/discovery/readme.md) points to a single product. A product can have multiple TEIs.
-- [TEA Component](tea-component/tea-component.md): A Component is a versioned part of the product. In many cases, the product has a single component,
-  and in other cases a product consists of multiple components.
-  - TEA Components has a list of "releases" for each component.
-- [TEA Collection](tea-collection/tea-collection.md): The collection is a list of artifacts for a specific release. The collection can be
-  dynamic or static, depending on the implemenation. TEA collections are versioned to indicate a change for a specific release,
-  like an update of a VEX file or a correction of an SBOM.
-- [TEA Artifacts](tea-artifact/tea-artifact.md): The artifact is a file associated with the collection. One artifact can be part of many collections,
-  for multiple components.
+- [TEA Product Release](tea-product/tea-product-release.md): The primary entry point. The [Transparency Exchange Identifier, TEI](/discovery/readme.md) resolves to a specific Product Release. A Product Release may optionally belong to a [TEA Product](tea-product/tea-product.md).
+- [TEA Product](tea-product/tea-product.md): An optional higher-level object that groups a set of Product Releases for a product line or family. Products can be discovered and browsed; releases are accessed via `/product/{uuid}/releases`.
+- [TEA Component](tea-component/tea-component.md): Represents a component lineage. A Component is a collection of Component Releases (accessible via `/component/{uuid}/releases`).
+- [TEA Release](/tea-component/tea-release.md: A Component Release object. Each Component Release may have its own TEA Collection.
+- [TEA Collection](tea-collection/tea-collection.md): A versioned list of artifacts for a specific Release (Component Release) or Product Release. Collections are versioned to indicate changes, e.g., an updated VEX or corrected SBOM.
+- [TEA Artifacts](tea-artifact/tea-artifact.md): Files associated with a Collection. A single Artifact can appear in multiple Collections.
 
 ## artifacts available of the API
 
diff --git a/tea-collection/tea-collection.md b/tea-collection/tea-collection.md
@@ -15,7 +15,7 @@ A TEA Component Release object has the following parts:
 - __preRelease__: A flag indicating pre-release (or beta) status.
   May be disabled after the creation of the release object, but can't be enabled after creation of an object.
 - __identifiers__: List of identifiers for the component
-  - __idType__: Type of identifier, e.g. `tei`, `purl`, `cpe`
+  - __idType__: Type of identifier, e.g. `TEI`, `PURL`, `CPE`
   - __idValue__: Identifier value
 
 ### Examples
@@ -29,7 +29,7 @@ A TEA Component Release object of the binary distribution of Apache Tomcat 11.0.
   "releaseDate": "2025-04-01T15:43:00Z",
   "identifiers": [
     {
-      "idType": "purl",
+      "idType": "PURL",
       "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.6"
     }
   ]
@@ -45,7 +45,7 @@ Different versions of Apache Tomcat should have separate TEA Component Release o
   "releaseDate": "2025-04-01T18:20:00Z",
   "identifiers": [
     {
-      "idType": "purl",
+      "idType": "PURL",
       "idValue": "pkg:maven/org.apache.tomcat/tomcat@10.1.4"
     }
   ]
@@ -63,7 +63,7 @@ and does not require users to know the version naming scheme adopted by the proj
   "preRelease": true,
   "identifiers": [
     {
-      "idType": "purl",
+      "idType": "PURL",
       "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26"
     }
   ]
@@ -129,12 +129,12 @@ The TEA Artifact object has the following parts:
 - __name__: Artifact name.
 - __type__: Type of artifact.
   See [TEA Artifact types](#tea-artifact-types) for a list.
-- __formats__: List of objects with the same content, but in different formats.
+  - __formats__: List of objects with the same content, but in different formats.
   The order of the list has no significance.
-  - __mime_type__: The MIME type of the document
+  - __mimeType__: The MIME type of the document
   - __description__: A free text describing the artifact
   - __url__: Direct download URL for the artifact
-  - __signature_url__: Direct download URL for an external signature of the artifact
+  - __signatureUrl__: Direct download URL for an external signature of the artifact
   - __checksums__: List of checksums for the artifact
     - __algType__: Checksum algorithm
       See [CycloneDX checksum algorithms](https://cyclonedx.org/docs/1.6/json/#components_items_hashes_items_alg) for a list of supported values.
@@ -184,13 +184,13 @@ producing different alerts than other changes of a collection.
     {
       "uuid": "1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce",
       "name": "Build SBOM",
-      "type": "bom",
+      "type": "BOM",
       "formats": [
         {
-          "mime_type": "application/vnd.cyclonedx+xml",
+          "mimeType": "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",
-          "signature_url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml.asc",
+          "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",
@@ -207,10 +207,10 @@ producing different alerts than other changes of a collection.
     {
       "uuid": "dfa35519-9734-4259-bba1-3e825cf4be06",
       "name": "Vulnerability Disclosure Report",
-      "type": "vulnerability-assertion",
+      "type": "VULNERABILITIES",
       "formats": [
         {
-          "mime_type": "application/vnd.cyclonedx+xml",
+          "mimeType": "application/vnd.cyclonedx+xml",
           "description": "CycloneDX VDR (XML)",
           "url": "https://logging.apache.org/cyclonedx/vdr.xml",
           "checksums": [
diff --git a/tea-component/tea-component.md b/tea-component/tea-component.md
@@ -1,20 +1,18 @@
 # The TEA Component API
 
-The TEA Component object is the object that indicates a product component. The product may
-be constructed with one or multiple Tea Components, each with their own set of
-related artefacts.
+The TEA Component represents a component lineage. A product release may
+be constructed with one or multiple TEA Components, each with their own set of
+releases and related artifacts.
 
-For each TEA COMPONENT there is a TEA COMPONENT INDEX, which is a list of all versions
-for that component.
+Each TEA Component has a list of Component Releases (see `/component/{uuid}/releases`),
+which enumerates all known versions for that component.
 
 The API should be very agnostic as to how a "version" is indicated - semver, vers,
 name, hash or anything else.
 
-## Major and minor versions
+## Versions and TEIs
 
-Each component is for a sub-version or minor version (using semver definitions). A new
-major version counts as a new product with a separate product object (TPO). Each
-product object has one or multiple TEI URNs.
+Each product object has one or multiple TEI URNs.
 
 For the API to be able to present a list of versions in a cronological order,
 a timestamp for a release is required.
@@ -42,7 +40,7 @@ Some examples of Maven artifacts as TEA Components:
   "name": "Apache Log4j API",
   "identifiers": [
     {
-      "idType": "purl",
+      "idType": "PURL",
       "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
     }
   ]
@@ -55,11 +53,11 @@ Some examples of Maven artifacts as TEA Components:
   "name": "Apache Log4j Core",
   "identifiers": [
     {
-      "idType": "cpe",
+      "idType": "CPE",
       "idValue": "cpe:2.3:a:apache:log4j"
     },
     {
-      "idType": "purl",
+      "idType": "PURL",
       "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core"
     }
   ]
diff --git a/tea-component/tea-release.md b/tea-component/tea-release.md
@@ -0,0 +1,68 @@
+# TEA Component Release
+
+## Overview
+
+A TEA Component Release represents a specific version of a TEA Component lineage. It is the concrete, versioned entity which has collections of security-related artifacts (SBOM, VDR/VEX, attestations, etc.).
+
+Key attributes:
+- uuid: Unique identifier of the component release
+- component: UUID of the TEA Component this release belongs to
+- version: Human-readable version string
+- createdDate: Timestamp when the release was created in TEA
+- releaseDate: Upstream release timestamp
+- preRelease: Indicates pre-release/beta status
+- identifiers: Array of identifiers (idType: CPE/TEI/PURL; idValue: string)
+
+Collections for a release contain artifacts relevant to that specific release.
+
+## JSON examples
+
+The following examples are reused from the OpenAPI schema (`components/schemas/release.examples`), ensuring exact field names and casing.
+
+```json
+{
+  "uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
+  "version": "11.0.6",
+  "createdDate": "2025-04-01T15:43:00Z",
+  "releaseDate": "2025-04-01T15:43:00Z",
+  "identifiers": [
+    {
+      "idType": "PURL",
+      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.6"
+    }
+  ]
+}
+```
+
+```json
+{
+  "uuid": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab",
+  "version": "10.1.40",
+  "createdDate": "2025-04-01T18:20:00Z",
+  "releaseDate": "2025-04-01T18:20:00Z",
+  "identifiers": [
+    {
+      "idType": "PURL",
+      "idValue": "pkg:maven/org.apache.tomcat/tomcat@10.1.40"
+    }
+  ]
+}
+```
+
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
+Notes:
+- Use uppercase idType values exactly as defined by the schema enum: CPE, TEI, PURL.
diff --git a/tea-product/tea-product-release.md b/tea-product/tea-product-release.md
@@ -0,0 +1,51 @@
+# TEA Product Release
+
+## Overview
+
+A TEA Product Release represents a specific versioned release of a TEA Product. It is the primary resolvable entity via TEI and the entry point for discovery of included components and related collections of security artifacts.
+
+Key attributes:
+- uuid: Unique identifier of the product release
+- product: UUID of the TEA Product this release belongs to
+- version: Human-readable version string of the product release
+- createdDate: Timestamp when the product release was created in TEA
+- releaseDate: Upstream product release timestamp
+- preRelease: Indicates pre-release/beta status
+- identifiers: Array of identifiers (idType: CPE/TEI/PURL; idValue: string)
+- components: Array of component references included in this product release
+  - uuid: UUID of the TEA Component
+  - release: Optional UUID of a specific component release to pin an exact version
+
+Collections for a product release contain artifacts relevant to that product release.
+
+## JSON examples
+
+The following example is reused from the OpenAPI schema (`components/schemas/productRelease.examples`), ensuring exact field names and casing.
+
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
+Notes:
+- Property `product` exists in the schema and links a product release to its parent product; it may not be present in all examples.
+- Use uppercase idType values exactly as defined by the schema enum: CPE, TEI, PURL.
diff --git a/tea-product/tea-product.md b/tea-product/tea-product.md
@@ -1,12 +1,10 @@
 # The TEA product API
 
-After TEA discovery, a user has a URL to the TEA product API where
-the TEI is used to query for data. The TEI marks the product sold,
-which can be a single unit or multiple units in a bundle.
+After TEA discovery, the [Transparency Exchange Identifier (TEI)](/discovery/readme.md) resolves to a specific TEA Product Release, which represents a concrete, versioned offering. A TEA Product is an optional higher-level object that groups multiple Product Releases for a product line or family and can be browsed via `/product/{uuid}/releases`.
 
-- For a single product, the output will be metadata about the
-  product and a TEA COMPONENT object.
-- For a composed product consisting of a bundle, the response
+- A product release may consist of a single component, the output will be metadata about the
+  product and the TEA COMPONENT object.
+- For a composed product release consisting of a bundle of components or component releases, the response
   will be multiple TEA COMPONENT objects.
 
 In addition, all known TEIs for the product will be returned,
@@ -20,9 +18,8 @@ which products and versions are supported for a specific user.
 
 ## Composite products
 
-If a product consists of a set of products, each with a different
-version number and update scheme, a TEA "bundle" will be the starting
-point of discovery. The TEA product will list all included components
+A TEA Product Release will be the starting
+point of discovery. The TEA product release will list all included components
 with the UUID of the TEA component. The reference list may also include
 a UUID of a specific release of a component in the case where a product
 always includes a single release of the component.
@@ -60,37 +57,27 @@ An example of a product consisting of an OSS project and all its Maven artifacts
   "name": "Apache Log4j 2",
   "identifiers": [
     {
-      "idType": "cpe",
+      "idType": "CPE",
       "idValue": "cpe:2.3:a:apache:log4j"
     },
     {
-      "idType": "purl",
+      "idType": "PURL",
       "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
     },
     {
-      "idType": "purl",
+      "idType": "PURL",
       "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core"
     },
     {
-      "idType": "purl",
+      "idType": "PURL",
       "idValue": "pkg:maven/org.apache.logging.log4j/log4j-layout-template-json"
     }
-  ],
-  "components": [
-    {
-      "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0",
-      "release": "c1f2f9c4-d86e-4007-b61c-a53dc36f3e72"
-    },
-    {
-      "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3"
-    },
-    {
-      "uuid": "d6d3f754-d4f4-4672-b096-b994b064ca2d"
-    }
   ]
 }
 ```
 
+Releases for this Product can be browsed via the API endpoint `/product/{uuid}/releases`.
+
 ### API usage
 
 The user will find this API end point using TEA discovery.
