Merge pull request #111 from ppkarwasz/feat/clarify-product

Clarify TEA Product fields

Author: oej

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](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.
 - [TEA Component index](tea-component/tea-component.md): A Component index is a version entry. The Component version 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/openapi.yaml

@@ -232,8 +232,10 @@ components:
       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
@@ -256,6 +258,7 @@ components:
       description: A TEA product
       properties:
         uuid:
+          description: A unique identifier for the TEA product
           "$ref": "#/components/schemas/uuid"
         name:
           type: string
@@ -269,12 +272,30 @@ components:
           type: array
           description: List of TEA components for the product
           items:
+            description: Unique identifier of the TEA component
             "$ref": "#/components/schemas/uuid"
       required:
         - uuid
         - name
         - identifiers
         - components
+      examples:
+        log4j2:
+          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
+            - idType: purl
+              idValue: pkg:maven/org.apache.logging.log4j/log4j-core
+            - idType: purl
+              idValue: pkg:maven/org.apache.logging.log4j/log4j-layout-template-json
+          components:
+            - 3910e0fd-aff4-48d6-b75f-8bf6b84687f0
+            - b844c9bd-55d6-478c-af59-954a932b6ad3
+            - d6d3f754-d4f4-4672-b096-b994b064ca2d
 
     #
     # TEA Component and related objects

tea-index/tea-index.md tea-product/tea-product.mdtea-index/tea-index.md renamed to tea-product/tea-product.md

@@ -29,21 +29,57 @@ same vendor.
 
 ## TEA Product object
 
-- __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 COMPONENT UUID
+A TEA Product object has the following parts:
+
+- __uuid__: A unique identifier for the TEA product
+- __name__: Product name
+- __identifiers__: List of identifiers for the product
+   - __idType__: Type of identifier, e.g. `tei`, `purl`, `cpe`
+   - __idValue__: Identifier value
+- __components__: List of TEA components for the product
+   - __uuid__: Unique identifier of the TEA component
 
 The TEA Component UUID is used in the Component API to find out which versions
 of the Component that exists.
 
-The goal of the TEA index is to provide a selection of product
+The goal of the TEA Product API is to provide a selection of product
 versions to assist the user software in finding a match for the
 owned version.
 
+### Example
+
+An example of a product consisting of an OSS project and all its Maven artifacts:
+
+```json
+{
+  "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"
+    },
+    {
+      "idType": "purl",
+      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core"
+    },
+    {
+      "idType": "purl",
+      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-layout-template-json"
+    }
+  ],
+  "components": [
+    "3910e0fd-aff4-48d6-b75f-8bf6b84687f0",
+    "b844c9bd-55d6-478c-af59-954a932b6ad3",
+    "d6d3f754-d4f4-4672-b096-b994b064ca2d"
+  ]
+}
+```
+
 ### API usage
 
 The user will find this API end point using TEA discovery.