Align markdown docs with OpenAPI specfication

spec/openapi.yaml

@@ -118,7 +118,7 @@ paths:
         - name: uuid
           in: path
           required: true
-          description: UUID of TEA Product Release in the TEA server
+          description: Unique UUID of TEA Product Release in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
       responses:
@@ -1053,7 +1053,7 @@ components:
           description: URI of a human-readable web page with information about the error.
     identifier:
       type: object
-      description: An identifier with a specified type
+      description: An identifier of a TEA object with a specified type
       properties:
         idType:
           description: Type of identifier, e.g. `TEI`, `PURL`, `CPE`
@@ -1098,6 +1098,7 @@ components:
         - TISAX
         - CYBER_ESSENTIALS
         - CYBER_ESSENTIALS_PLUS
+        - EU_DECLARATION_OF_CONFORMITY
     uuid:
       type: string
       description: A UUID in lower case (RFC 9562)
@@ -1157,7 +1158,7 @@ components:
           type: string
           example: Apache Log4j 2
         version:
-          description: Version number of the product release
+          description: Human-readable version string of the product release
           type: string
           example: 2.24.3
         createdDate:
@@ -1173,13 +1174,14 @@ components:
             May be disabled after the creation of the release object, but can't be enabled after creation of an object.
         identifiers:
           type: array
-          description: List of identifiers for the product release
+          description: |
+            Array of identifiers for the product release (idType: CPE/TEI/PURL; idValue: string)
           items:
             "$ref": "#/components/schemas/identifier"
         components:
           type: array
           description: |
-            List of component references that compose this product release. A component reference can optionally include
+            Array of component references that compose this product release. A component reference can optionally include
             the UUID of a specific component release to pin the exact version.
           items:
             "$ref": "#/components/schemas/component-ref"
@@ -1275,7 +1277,7 @@ components:
       description: A TEA Component Release
       properties:
         uuid:
-          description: A unique identifier for the TEA Component Release
+          description: A unique identifier of the TEA Component Release
           "$ref": "#/components/schemas/uuid"
         component:
           description: UUID of the TEA Component this release belongs to
@@ -1285,7 +1287,7 @@ components:
           type: string
           example: tomcat
         version:
-          description: Version number
+          description: Human-readable version string
           type: string
           example: 1.2.3
         createdDate:
@@ -1301,7 +1303,7 @@ components:
             May be disabled after the creation of the release object, but can't be enabled after creation of an object.
         identifiers:
           type: array
-          description: List of identifiers for the component
+          description: Array of identifiers for the component
           items:
             "$ref": "#/components/schemas/identifier"
         distributions:
@@ -1375,14 +1377,14 @@ components:
       type: object
       properties:
         distributionId:
-          description: A unique identifier for the TEA Distribution object
+          description: A unique identifier for the TEA Distribution object (uuid)
           "$ref": "#/components/schemas/uuid"
         description:
           type: string
-          description: Free-text description of the distribution.
+          description: Free-text description of the distribution
         identifiers:
           type: array
-          description: List of identifiers specific to this distribution.
+          description: Array of identifiers specific to this distribution
           items:
             $ref: "#/components/schemas/identifier"
         url:
@@ -1404,7 +1406,7 @@ components:
         checksums:
           type: array
           description: |
-            List of checksums for the distribution payload retrieved from `url`
+            Array of checksums for the distribution payload retrieved from `url`
             (the distribution bytes, not the signature at `signatureUrl`).
           items:
             "$ref": "#/components/schemas/checksum"
@@ -1541,7 +1543,7 @@ components:
           "$ref": "#/components/schemas/collection-update-reason"
         artifacts:
           type: array
-          description: List of TEA Artifact objects (may be empty).
+          description: Array of TEA Artifact objects (may be empty).
           items:
             "$ref": "#/components/schemas/artifact"
       required:
@@ -1635,17 +1637,17 @@ components:
           default: 1
         name:
           type: string
-          description: Name of TEA Artifact
+          description: A human-readable name for the artefact
         type:
           description: Type of TEA Artifact
           "$ref": "#/components/schemas/artifact-type"
         createdDate:
-          description: The date when the TEA Artifact revision was created.
+          description: The date and time the TEA Artifact revision was created.
           "$ref": "#/components/schemas/date-time"
         distributionIds:
           type: array
           description: |
-            List of TEA Component Release distributions that this TEA Artifact applies to.
+            Array of TEA Component Release distributions that this TEA Artifact applies to.
             If absent or empty, the TEA Artifact applies to all distributions.
           items:
             "$ref": "#/components/schemas/uuid"
@@ -1764,7 +1766,7 @@ components:
         checksums:
           type: array
           description: |
-            List of checksums for this artifact format's content bytes (the payload
+            Array of checksums for this artifact format's content bytes (the payload
             retrieved from `url` or from the artifact download endpoint for this
             `mediaType`), not the detached signature.
           items: