Merge branch 'main' into 2025-08-add-product-release-on-pr-186

taleodor · web-flow · commit 46ab21183091 · 2025-08-17T18:16:07.000-04:00
Signed-off-by: Pavel Shukhman &lt;taleodor@users.noreply.github.com&gt;
diff --git a/.github/workflows/test-generate-api-clients.yaml b/.github/workflows/test-generate-api-clients.yaml
@@ -14,6 +14,9 @@ env:
     PYTHON_VERSION_DEFAULT: '3.12'
     POETRY_VERSION: '1.8.1'
 
+# see https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token
+permissions: {}
+
 jobs:
     generate-library-code:
         name: Generate Library Code ${{ matrix.language }}
diff --git a/discovery/readme.md b/discovery/readme.md
@@ -1,7 +1,5 @@
 # Transparency Exchange API - Discovery
 
-**NOTE**: _This is a proposal for the WG_
-
 - [From product identifier to API endpoint](#from-product-identifier-to-api-endpoint)
 - [Advertising the TEI](#advertising-the-tei)
 - [TEA Discovery - defining an extensible identifier](#tea-discovery---defining-an-extensible-identifier)
@@ -17,9 +15,10 @@
 ## From product identifier to API endpoint
 
 TEA Discovery is the connection between a product identifier and the API endpoint.
-A "product" is something that the customer aquires or downloads. It can be a bundle
-of many digital devices or software applications. A "product" normally also has an
-entry in a large corporation's asset inventory system.
+A "product" is something that the customer aquires or downloads - hardware and/or software.
+
+It can be a bundle of many digital devices or software applications.
+A "product" normally also has an entry in a large corporation's asset inventory system.
 
 A product identifier is embedded in a URN where the identifier is one of many existing
 identifiers or a random string - like an EAN or UPC bar code, UUID, product
@@ -37,6 +36,9 @@ The TEI for a product can be communicated to the user in many ways.
 - On the invoice or delivery note
 - For software with a GUI, in an "about" box
 
+The user needs to get the TEI from the manufacturer, through a reseller or directly. The TEI
+is defined by the manufacturer and can normally not be derived from known information.
+
 ## TEA Discovery - defining an extensible identifier
 
 TEA discovery is the process where a user with a product identifier can discover and download
@@ -48,20 +50,25 @@ and gives the vendor a name space to define product identifiers based on existin
 like EAN/UPC bar code, PURLs or other existing schemes. A given product may have multiple identifiers
 as long as they all resolve into the same destination.
 
+The vendor needs to make sure that the TEI is unique within the vendor's name space. There is no
+intention to create any TEI registries.
+
 ## The TEI URN: An extensible identifier
 
 The TEI, Transparency Exchange Identifier, is a URN schema that is extensible based on existing
 identifiers like EAN codes, PURL and other identifiers. It is based on a DNS name, which leads
 to global uniqueness without new registries.
 
 The TEI can be shown in the software itself, in shipping documentation, in web pages and app stores.
-TEI is unique for a product, not a version of a software. The TEI consist of three core parts
+TEI is unique for a product, not a version of a product.
 
 A TEI belongs to a single product. A product can have multiple TEIs - like one with a EAN/UPC
 barcode and one with the vendor's product number.
 
 ### TEI syntax
 
+The TEI consists of three core parts
+
 ```text
 urn:tei:<type>:<domain-name>:<unique-identifier>
 ````
@@ -149,6 +156,11 @@ urn:tei:uuid:cyclonedx.org:d4d9f54a-abcf-11ee-ac79-1a52914d44b1
 - GS1
 - STD
 
+Note that if an identifier, like EAN, is used for multiple different products then this
+EAN code will not be unique for a given product and should not be used as an identifier.
+In this case, the vendor is recommended to create a separate identifier for each unique
+product sold by other means, like UUID or hash.
+
 ### TEI resolution using DNS
 
 The `domain-name` part of the TEI is used in a DNS query to find one or multiple locations for
@@ -200,11 +212,6 @@ Always prefix with the https:// scheme. http (unencrypted) is not valid.
 
 **NOTE:** The `/.well-known/tea` names space needs to be registred.
 
-## The TEA Version Index
-
-The resulting URL leads to the TEA version index, which is documented in another document.
-One redirect (302) is allowed in order to provide for aliasing, where a single product
-has many identifiers. The redirect should not lead to a separate web server.
 
 ## References
 
diff --git a/spec/openapi.yaml b/spec/openapi.yaml
@@ -547,6 +547,7 @@ components:
     #
     release:
       type: object
+      description: A TEA Component Release
       properties:
         uuid:
           description: A unique identifier for the TEA Component Release
@@ -574,28 +575,63 @@ components:
           description: List of identifiers for the component
           items:
             "$ref": "#/components/schemas/identifier"
+        distributions:
+          type: array
+          description: List of different formats of this component release
+          items:
+            "$ref": "#/components/schemas/release-distribution"
         # add lifecycle here
       required:
         - uuid
         - version
         - createdDate
       examples:
-        # Apache Tomcat 11.0.6
+        # Apache Tomcat 11.0.7
         - uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345
-          version: "11.0.6"
-          createdDate: 2025-04-01T15:43:00Z
-          releaseDate: 2025-04-01T15:43:00Z
+          version: "11.0.7"
+          createdDate: 2025-05-07T18:08:00Z
+          releaseDate: 2025-05-12T18:08:00Z
           identifiers:
             - idType: PURL
-              idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6
-        # Different release of Apache Tomcat
-        - uuid: da89e38e-95e7-44ca-aa7d-f3b6b34c7fab
-          version: "10.1.40"
-          createdDate: 2025-04-01T18:20:00Z
-          releaseDate: 2025-04-01T18:20:00Z
-          identifiers:
-            - idType: PURL
-              idValue: pkg:maven/org.apache.tomcat/tomcat@10.1.40
+              idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.7
+          distributions:
+            - distributionType: zip
+              description: Core binary distribution, zip archive
+              identifiers:
+                - idType: PURL
+                  idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?type=zip
+              checksums:
+                - algType: SHA_256
+                  algValue: 9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1
+              url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip
+              signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc
+            - distributionType: tar.gz
+              description: Core binary distribution, tar.gz archive
+              identifiers:
+                - idType: PURL
+                  idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?type=tar.gz
+              checksums:
+                - algType: SHA_256
+                  algValue: 2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9
+              url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz
+              signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz.asc
+            - distributionType: windows-x64.zip
+              description: Core binary distribution, Windows x64 zip archive
+              identifiers:
+                - idType: PURL
+                  idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?classifier=windows-x64&type=zip
+              checksums:
+                - algType: SHA_256
+                  algValue: 62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4
+              url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6-windows-x64.zip
+              signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc
+            - distributionType: windows-x64.exe
+              description: Core binary distribution, Windows Service Installer (MSI)
+              checksums:
+                - algType: SHA_512
+                  algValue: 1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96
+              url: https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe
+              signatureUrl: https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc
         # A pre-release of Apache Tomcat
         - uuid: 95f481df-f760-47f4-b2f2-f8b76d858450
           version: "11.0.0-M26"
@@ -604,6 +640,74 @@ components:
           identifiers:
             - idType: PURL
               idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26
+    release-distribution:
+      type: object
+      properties:
+        distributionType:
+          type: string
+          description: Unique identifier for the distribution type.
+        description:
+          type: string
+          description: Free-text description of the distribution.
+        identifiers:
+          type: array
+          description: List of identifiers specific to this distribution.
+          items:
+            $ref: "#/components/schemas/identifier"
+        url:
+          type: string
+          description: Direct download URL for the distribution.
+          format: url
+        signatureUrl:
+          type: string
+          description: Direct download URL for the distribution's external signature.
+          format: url
+        checksums:
+          type: array
+          description: List of checksums for the distribution.
+          items:
+            "$ref": "#/components/schemas/checksum"
+      required:
+        - id
+      examples:
+        - distributionType: zip
+          description: Core binary distribution, zip archive
+          identifiers:
+            - idType: PURL
+              idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?type=zip
+          checksums:
+            - algType: SHA_256
+              algValue: 9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1
+          url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip
+          signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc
+        - distributionType: tar.gz
+          description: Core binary distribution, tar.gz archive
+          identifiers:
+            - idType: PURL
+              idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?type=tar.gz
+          checksums:
+            - algType: SHA_256
+              algValue: 2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9
+          url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz
+          signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz.asc
+        - distributionType: windows-x64.zip
+          description: Core binary distribution, Windows x64 zip archive
+          identifiers:
+            - idType: PURL
+              idValue: pkg:maven/org.apache.tomcat/tomcat@11.0.6?classifier=windows-x64&type=zip
+          checksums:
+            - algType: SHA_256
+              algValue: 62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4
+          url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6-windows-x64.zip
+          signatureUrl: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc
+        - distributionType: windows-x64.exe
+          description: Core binary distribution, Windows Service Installer (MSI)
+          checksums:
+            - algType: SHA_512
+              algValue: 1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96
+          url: https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe
+          signatureUrl: https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc
+
 
     #
     # TEA Collection and related objects
@@ -713,6 +817,15 @@ components:
         type:
           description: Type of artifact
           "$ref": "#/components/schemas/artifact-type"
+        distributionTypes:
+          type: array
+          description: |
+            List of component distributions types that this artifact applies to.
+            If absent, the artifact applies to all distributions.
+          items:
+            type: string
+            description: |
+              The `id` of the component format that this artifact applies to.
         formats:
           type: array
           description: |
@@ -757,17 +870,17 @@ components:
           type: array
           description: List of checksums for the artifact
           items:
-            "$ref": "#/components/schemas/artifact-checksum"
-    artifact-checksum:
+            "$ref": "#/components/schemas/checksum"
+    checksum:
       type: object
       properties:
         algType:
           description: Checksum algorithm
-          "$ref": "#/components/schemas/artifact-checksum-type"
+          "$ref": "#/components/schemas/checksum-type"
         algValue:
           type: string
           description: Checksum value
-    artifact-checksum-type:
+    checksum-type:
       type: string
       description: Checksum algorithm
       enum:
diff --git a/tea-collection/tea-collection.md b/tea-collection/tea-collection.md
@@ -33,14 +33,14 @@ A TEA Component Release object contains the following fields:
 - __preRelease__: Boolean flag indicating if this is a pre-release (e.g., beta).
   This flag can be disabled after creation, but not enabled.
 - __identifiers__: List of identifiers for the component.
-  - __idType__: Type of identifier (e.g., `TEI`, `PURL`, `CPE`).
-  - __idValue__: Value of the identifier.
+- __idType__: Type of identifier (e.g., `TEI`, `PURL`, `CPE`).
+- __idValue__: Value of the identifier.
 - __distributions__: List of release distributions, each with:
   - __distributionType__: Unique identifier for the distribution type.
   - __description__: Free-text description of the distribution.
   - __identifiers__: List of identifiers specific to this distribution.
-    - __idType__: Type of identifier (e.g., `TEI`, `PURL`, `CPE`).
-    - __idValue__: Value of the identifier.
+  - __idType__: Type of identifier (e.g., `TEI`, `PURL`, `CPE`).
+  - __idValue__: Value of the identifier.
   - __url__: Direct download URL for the distribution.
   - __signatureUrl__: Direct download URL for the distribution's external signature.
   - __checksums__: List of checksums for the distribution.
