Clarify TEA Product fields

README.md

@@ -39,7 +39,7 @@ The working group has produced a list of use cases and requirements for the prot
 
 ## Data model
 
-- [TEA Product index](tea-index/tea-index.md): This is the starting point. A "product" is something for sale. The [Transparency Exchange Identifier, TEI](/discovery/readme.md) points to a single product.
+- [TEA Product index](spec/product): This is the starting point. A "product" is something for sale. The [Transparency Exchange Identifier, TEI](/discovery/readme.md) points to a single product.
 - [TEA Leaf index](tea-leaf/tea-leaf.md): A leaf is a version entry. The leaf index has one entry per version of the product.
 - [TEA Collection](tea-collection/tea-collection.md): The collection is a list of artefacts for a specific version. The collection can be dynamic or static, depending on the implemenation.
 

spec/README.md

@@ -1,10 +1,20 @@
-# TEA OpenAPI Spec
+# TEA Specification
+
+## TEA domain objects
+
+- [TEA Product](product.md)
+
+## TEA Schema
+
+The domain objects above are described in the JSON schema is [`tea.schema.yaml`](tea.schema.yaml)
+
+## TEA OpenAPI Spec
 
 The OpenAPI 3.1 specification for the Transparency Exchange API is available in [openapi.json](./openapi.json).
 
 - [Generating API Clients from OpenAPI Spec](#generating-api-clients-from-openapi-spec)
 
-## Generating API Clients from OpenAPI Spec
+### Generating API Clients from OpenAPI Spec
 
 We use the OpenAPI Generator with configuration per language/framework in the `generators` folder. An example is:
 
@@ -16,7 +26,7 @@ docker run \
     batch --clean /local/spec/generators/typescript.yaml
 ```
 
-## Preview Specs
+### Preview Specs
 
 Fire up the `swagger-ui` with Docker from the root of the repository:
 

tea-index/tea-index.md → spec/product.md

@@ -29,13 +29,15 @@ same vendor.
 
 ## TEA Product object
 
+Schema: https://raw.githubusercontent.com/CycloneDX/transparency-exchange-api/refs/heads/main/spec/tea.schema.yaml#/$defs/product
+
 - __uuid__: A unique identifier for this product
-- __name__: Product name in clear text (str)
-- __identifiers__: A list of TEIs that apply to this product
-   - __type__: Type of identifier - one of "tei", "purl", or "cpe"
-   - __id__: The complete identifier (str)
-- __leaves__: A list of product leaves
-   - __uuid__: TEA LEAF UUID
+- __name__: Product name in clear text
+- __identifiers__: A list of identifiers that apply to this product
+   - __type__: Type of identifier, e.g., `cpe`, `purl`, or `tei`
+   - __id__: The complete identifier
+- __leaves__: A list of TEA Leaves
+   - __uuid__: The unique identifier of the TEA Leaf
 
 The TEA LEAF UUID is used in the LEAF API to find out which versions
 of the LEAF that exists.

spec/tea.schema.yaml

@@ -0,0 +1,88 @@
+---
+"$schema": http://json-schema.org/draft-07/schema#
+"$id": https://raw.githubusercontent.com/CycloneDX/transparency-exchange-api/refs/heads/main/spec/tea.schema.yaml
+title: Transparency Exchange API Schema
+description: Schema for the domain objects of the Transparency Exchange API
+"$defs":
+  #
+  # General types
+  #
+  uuid:
+    type: string
+    description: A UUID
+    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+  identifier_type:
+    type: string
+    description: Enumeration of identifiers types
+    enum:
+      - cpe
+      - tei
+      - purl
+  identifier:
+    type: object
+    description: An identifier with a specified type
+    properties:
+      type:
+        "$ref": "#/$defs/identifier_type"
+        description: Type of identifier, e.g., `cpe`, `purl`, or `tei`
+      id:
+        type: string
+        id: The complete identifier
+  #
+  # Domain objects
+  #
+  product:
+    type: object
+    title: TEA Product
+    description: A TEA product
+    properties:
+      uuid:
+        "$ref": "#/$defs/uuid"
+        description: A unique identifier for this product
+      name:
+        type: string
+        description: Product name in clear text
+      identifiers:
+        type: array
+        description: A list of identifiers that apply to this product
+        items:
+          "$ref": "#/$defs/identifier"
+      leaves:
+        type: array
+        description: A list of TEA Leaves
+        items:
+          "$ref": "#/$defs/uuid"
+          description: The unique identifier of the TEA Leaf
+    required:
+      - uuid
+      - name
+      - identifiers
+      - leaves
+  leaf:
+    type: object
+    description: A TEA leaf
+    properties:
+      uuid:
+        "$ref": "#/$defs/uuid"
+    required:
+      - uuid
+  collection:
+    type: object
+    description: A TEA collection
+    properties:
+      uuid:
+        "$ref": "#/$defs/uuid"
+      version:
+        type: integer
+        default: 1
+        description: Collection version, incremented each time its content changes.
+    required:
+      - uuid
+  artifact:
+    type: object
+    description: A security-related document
+    properties:
+      uuid:
+        "$ref": "#/$defs/uuid"
+    required:
+      - uuid