feat: clarify fields of TEA Collection

Updates the fields in `tea-collection.md` using those defined in the OpenAPI spec and synchronizes the descriptions between the two documents.

Signed-off-by: Piotr P. Karwasz <[email protected]>

Author: ppkarwasz

spec/openapi.yaml

@@ -366,24 +366,33 @@ components:
       description: A collection of security-related documents
       properties:
         uuid:
+          description: |
+            UUID of the TEA Collection object.
+            Note that this is equal to the UUID of the associated TEA Component Release object.
+            When updating a collection, only the `version` is changed.
           "$ref": "#/components/schemas/uuid"
-          description: Must match the UUID of the corresponding `release` object
         version:
           type: integer
-          description: Collection version, incremented each time its content changes.
+          description: |
+            TEA Collection version, incremented each time its content changes.
+            Versions start with 1.
         release_date:
+          description: TEA Collection version release date.
           "$ref": "#/components/schemas/date-time"
         update_reason:
+          description: Reason for the update/release of the TEA Collection object.
           "$ref": "#/components/schemas/collection-update-reason"
         artifacts:
           type: array
+          description: List of TEA artifact objects.
           items:
             "$ref": "#/components/schemas/artifact"
     collection-update-reason:
       type: object
       description: Reason for the update to the TEA collection
       properties:
         type:
+          description: Type of update reason.
           "$ref": "#/components/schemas/collection-update-reason-type"
         comment:
           type: string
@@ -406,16 +415,22 @@ components:
       description: A security-related document
       properties:
         uuid:
+          description: UUID of the TEA Artifact object.
           "$ref": "#/components/schemas/uuid"
         name:
           type: string
           description: Artifact name
         author:
+          description: Author of the TEA Artifact object
           "$ref": "#/components/schemas/artifact-author"
         type:
+          description: Type of artifact
           "$ref": "#/components/schemas/artifact-type"
         formats:
           type: array
+          description: |
+            List of objects with the same content, but in different formats.
+            The order of the list has no significance.
           items:
             "$ref": "#/components/schemas/artifact-format"
     artifact-author:
@@ -483,19 +498,19 @@ components:
       type: object
       description: A security-related document in a specific format
       properties:
-        mimeType:
+        mime_type:
           type: string
           description: The MIME type of the document
         description:
           type: string
           description: A free text describing the artifact
         url:
           type: string
-          description: A download URL for the artifact
+          description: Direct download URL for the artifact
           format: url
         signature_url:
           type: string
-          description: A download URL for an external signature of the artifact
+          description: Direct download URL for an external signature of the artifact
           format: url
         checksums:
           type: array
@@ -506,6 +521,7 @@ components:
       type: object
       properties:
         algType:
+          description: Checksum algorithm
           "$ref": "#/components/schemas/artifact-checksum-type"
         algValue:
           type: string

tea-collection/tea-collection.md

@@ -50,56 +50,54 @@ to implement this:
 
 ### Collection object
 
-The TEA Collection object has the following parts
-
-* Preamble
-  * UUID of the TEA collection release object (TCO). Note that this
-    is the same UUID as the release object for this version. When updating
-    a collection, the version is changed.
-  * Product Release date (timestamp)
-  * Collection version release date (timestamp)
-  * _Version_ of this collection object. Starting with 1.
-  * Reason for update/release of TCO
-    * ENUM reason
-      See below
-    * clear text description of change
-      * "New product release"
-      * "Corrected dependency in SBOM that was faulty"
-      * "Added missing In-Toto build attestation"
-* List of artifact objects (see below)
-* Optional Signature of the collection object
-
-The artifact object has the following parts
-
-* Artifact UUID
-* Artifact name
-* Author of the artifact object
-  * Name
-  * Email
-  * Organisation
-* List of objects with the same content, but in different formats.
+The TEA Collection object has the following parts:
+
+- Preamble
+  - __uuid__: UUID of the TEA Collection object.
+    Note that this is equal to the UUID of the associated TEA Component Release object.
+    When updating a collection, only the `version` is changed.
+  - __version__: TEA Collection version, incremented each time its content changes.
+    Versions start with 1.
+  - __release_date__: TEA Collection version release date.
+  - __update_reason__: Reason for the update/release of the TEA Collection object.
+    - __type__: Type of update reason.
+      See [reasons for TEA Collection update](#the-reason-for-tco-update-enum) below.
+    - __comment__: Free text description.
+- __artifacts__: List of TEA artifact objects.
+  See [below](#artifact-object).
+
+### Artifact object
+
+The TEA Artifact object has the following parts:
+
+- __uuid__: UUID of the TEA Artifact object.
+- __name__: Artifact name.
+- __author__: Author of the TEA Artifact object:
+  - __name__: The name of the author.
+  - __email__: The e-mail address of the author.
+  - __organization__: Organization
+- __type__: Type of artifact.
+  See [TEA Artifact types](../tea-artifact/tea-artifact.md) for a list.
+- __formats__: List of objects with the same content, but in different formats.
   The order of the list has no significance.
-  * UUID for subdoc
-  * Optional BOM identifier
-    * SPDX or CycloneDX reference to BOM
-  * MIME media type
-  * Artifact category (enum)
-    * <https://cyclonedx.org/docs/1.6/json/#externalReferences_items_type>
-  * Description in clear text
-  * Direct URL for downloads of artefact
-  * Direct URL for download of external signature
-  * Size in bytes
-  * SHA384 checksum
+  - __mime_type__: 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
+  - __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.
+    - __algValue__: Checksum value
 
 ### The reason for TCO update enum
 
-| ENUM        | Explanation                    |
-|-------------|--------------------------------|
-| INITIAL_RELEASE | Initial release of the collection |
-| VEX_UPDATED   | Updated the VEX artifact(s)    |
-| ARTIFACT_UPDATED  | Updated the artifact(s) other than VEX |
-| ARTIFACT_REMOVED | Removal of artifact       |
-| ARTIFACT_ADDED | Addition of an artifact |
+| ENUM             | Explanation                            |
+|------------------|----------------------------------------|
+| INITIAL_RELEASE  | Initial release of the collection      |
+| VEX_UPDATED      | Updated the VEX artifact(s)            |
+| ARTIFACT_UPDATED | Updated the artifact(s) other than VEX |
+| ARTIFACT_REMOVED | Removal of artifact                    |
+| ARTIFACT_ADDED   | Addition of an artifact                |
 
 Updates of VEX (CSAF) files may be handled in a different way by a TEA client,
 producing different alerts than other changes of a collection.