Merge pull request #128 from ppkarwasz/feat/clarify-component

Clarify TEA Component fields

Author: oej

spec/openapi.yaml

@@ -103,7 +103,7 @@ paths:
             application/json:
               schema:
                 type: array
-                items: 
+                items:
                   "$ref": "#/components/schemas/release"
         '400':
           $ref: "#/components/responses/400-invalid-request"
@@ -128,7 +128,7 @@ paths:
           description: Requested TEA Collection found and returned
           content:
             application/json:
-              schema: 
+              schema:
                 "$ref": "#/components/schemas/collection"
         '400':
           $ref: "#/components/responses/400-invalid-request"
@@ -155,7 +155,7 @@ paths:
             application/json:
               schema:
                 type: array
-                items: 
+                items:
                   "$ref": "#/components/schemas/collection"
         '400':
           $ref: "#/components/responses/400-invalid-request"
@@ -304,6 +304,7 @@ components:
       description: A TEA component
       properties:
         uuid:
+          description: A unique identifier for the TEA component
           "$ref": "#/components/schemas/uuid"
         name:
           type: string
@@ -318,6 +319,20 @@ components:
         - name
         - identifiers
         - versions
+      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
+
     #
     # TEA Release and related objects
     #
@@ -342,7 +357,7 @@ components:
       required:
         - uuid
         - version
-        - release_date    
+        - release_date
     #
     # TEA Collection and related objects
     #

tea-component/tea-component.md

@@ -1,6 +1,6 @@
-# The TEA Component Index Object (TCO)
+# The TEA Component API
 
-The TEA COMPONENT INDEX is the object that indicates a product component. The product may
+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.
 
@@ -19,18 +19,53 @@ 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.
 
-## The Tea Component Object
+## TEA Component Object
 
-- __Uuid__ unique for this object
-- __Product name__: A text field
-- __Product version__: A text field, no required syntax
-- __Release date__: A unix timestamp
-- __Pre-release__: A boolean flag indicating a pre-release (beta, rc)
-- __Tco_uuid__: A reference to the TEA Collection objet for this release
+A TEA Component object has the following parts:
+
+- __uuid__: A unique identifier for the TEA component
+- __name__: Component name
+- __identifiers__: List of identifiers for the component
+  - __idType__: Type of identifier, e.g. `tei`, `purl`, `cpe`
+  - __idValue__: Identifier value
 
 Note: In coming versions, there may be a flag indicating lifecycle status
 for a component.
 
+### Examples
+
+Some examples of Maven artifacts as TEA Components:
+
+```json
+{
+  "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0",
+  "name": "Apache Log4j API",
+  "identifiers": [
+    {
+      "idType": "purl",
+      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
+    }
+  ]
+}
+```
+
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
 ## Handling the Pre-Release flag
 
 The "Pre-release" flag is used to indicate that this is not a final release.