diff --git a/README.md b/README.md index 0bea225..b797f76 100644 --- a/README.md +++ b/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. diff --git a/spec/README.md b/spec/README.md index 4eff65a..f4f7e4f 100644 --- a/spec/README.md +++ b/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: diff --git a/tea-index/tea-index.md b/spec/product.md similarity index 82% rename from tea-index/tea-index.md rename to spec/product.md index 748ef58..84c1d81 100644 --- a/tea-index/tea-index.md +++ b/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. diff --git a/spec/tea.schema.yaml b/spec/tea.schema.yaml new file mode 100644 index 0000000..177ab15 --- /dev/null +++ b/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