Merge pull request #186 from oej/add-link-to-release

Adding a "componentref" structure in the product definition

Author: stevespringett

README.md

@@ -32,16 +32,16 @@ tags in the repository as well as in the slack channel.
 ## Introduction
 
 This specification defines a standard, format agnostic, API for the exchange of
-product related artefacts, like BOMs, between systems. The work includes:
+product related artifacts, like BOMs, between systems. The work includes:
 
 - [Discovery of servers](/discovery/readme.md): Describes discovery using the Transparency Exchange Identifier (TEI)
-- Retrieval of artefacts
-- Publication of artefacts
+- Retrieval of artifacts
+- Publication of artifacts
 - Authentication and authorization
 - Querying
 
 System and tooling implementors are encouraged to adopt this API standard for
-sending/receiving transparency artefacts between systems. 
+sending/receiving transparency artifacts between systems. 
 This will enable more widespread
 "out of the box" integration support in the BOM ecosystem.
 
@@ -54,13 +54,19 @@ The working group has produced a list of use cases and requirements for the prot
 
 ## Data model
 
-- [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.
+- [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. A product can have multiple TEIs.
+- [TEA Component](tea-component/tea-component.md): A Component is a versioned part of the product. In many cases, the product has a single component,
+  and in other cases a product consists of multiple components.
+  - TEA Components has a list of "releases" for each component.
+- [TEA Collection](tea-collection/tea-collection.md): The collection is a list of artifacts for a specific release. The collection can be
+  dynamic or static, depending on the implemenation. TEA collections are versioned to indicate a change for a specific release,
+  like an update of a VEX file or a correction of an SBOM.
+- [TEA Artifacts](tea-artifact/tea-artifact.md): The artifact is a file associated with the collection. One artifact can be part of many collections,
+  for multiple components.
 
-## Artefacts available of the API
+## artifacts available of the API
 
-The Transparency Exchange API (TEA) supports publication and retrieval of a set of transparency exchange artefacts. The API itself should not be restricting the types of the artefacts. A few examples:
+The Transparency Exchange API (TEA) supports publication and retrieval of a set of transparency exchange artifacts. The API itself should not be restricting the types of the artifacts. A few examples:
 
 ### xBOM
 
@@ -78,7 +84,7 @@ Vulnerability Disclosure Reports (VDR) and Vulnerability Exploitability eXchange
 
 Product lifecycle events that are captured and communicated through the Common Lifecycle Enumeration will be supported. This includes product rebranding, repackaging, mergers and acquisitions, and product milestone events such as end-of-life and end-of-support.
 
-### Insights
+## Insights
 
 Much of the focus on Software Transparency from the U.S. Government and others center around the concept of “full transparency”. Consumers often need to ingest, process, and analyze SBOMs or VEXs just to be able to answer simple questions such as:
 

spec/openapi.yaml

@@ -266,14 +266,18 @@ components:
           description: Product name
         identifiers:
           type: array
-          description: List of identifiers for the product
+          description: |
+            List of identifiers for the product, like TEI, CPE, PURL or other identifiers
           items:
             "$ref": "#/components/schemas/identifier"
         components:
           type: array
-          description: List of TEA components for the product
+          description: |
+            List of TEA component-refs for the product. The component-ref by default just 
+            includes the UUID of the component, but in some cases also include a reference
+            to the UUID of a specific release.
           items:
-            description: Unique identifier of the TEA component
+            description: Unique identifier of the TEA component-ref
             "$ref": "#/components/schemas/uuid"
       required:
         - uuid
@@ -288,10 +292,6 @@ components:
               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
@@ -334,6 +334,32 @@ components:
             - idType: PURL
               idValue: pkg:maven/org.apache.logging.log4j/log4j-core
 
+#
+    # Reference to a component, in some cases directly to a specific release
+    # 
+    # The release reference (release UUID) is only used in cases where a product
+    # name incldues a version and this version of the product always include
+    # the same releases of the component.
+    component-ref:
+      type: object
+      description: A reference to a TEA component or specific component release
+      properties:
+        uuid:
+          description: A unique identifier for the TEA component
+          "$ref": "#/components/schemas/uuid"
+        release:
+          type: string
+          description: |
+            Optional UUID of a specific release included in the product in the case where the product
+            always include a specific release of a component. The product name should include a version
+            identifier in this case.
+          items:
+            "$ref": "#/components/schemas/uuid"
+      required:
+        - uuid
+
+
+
     #
     # TEA Release and related objects
     #

tea-product/tea-product.md

@@ -10,7 +10,8 @@ which can be a single unit or multiple units in a bundle.
   will be multiple TEA COMPONENT objects.
 
 In addition, all known TEIs for the product will be returned,
-in order for a TEA client to avoid duplication.
+in order for a TEA client to avoid duplication. This list can
+also include known Package URLs (PURL) and CPEs for the product.
 
 ## Authorization
 
@@ -20,9 +21,11 @@ which products and versions are supported for a specific user.
 ## Composite products
 
 If a product consists of a set of products, each with a different
-version number and update scheme, a TEA bundle will be the starting
-point of discovery. The TEA bundle will list all included parts
-and include pointers (URLs) to the TEA index for these.
+version number and update scheme, a TEA "bundle" will be the starting
+point of discovery. The TEA product will list all included components
+with the UUID of the TEA component. The reference list may also include
+a UUID of a specific release of a component in the case where a product
+always includes a single release of the component.
 
 The URL can be to a different vendor or different site with the
 same vendor.
@@ -38,6 +41,7 @@ A TEA Product object has the following parts:
    - __idValue__: Identifier value
 - __components__: List of TEA components for the product
    - __uuid__: Unique identifier of the TEA component
+   - __release__: Optional UUID of a TEA component release
 
 The TEA Component UUID is used in the Component API to find out which versions
 of the Component that exists.
@@ -73,9 +77,16 @@ An example of a product consisting of an OSS project and all its Maven artifacts
     }
   ],
   "components": [
-    "3910e0fd-aff4-48d6-b75f-8bf6b84687f0",
-    "b844c9bd-55d6-478c-af59-954a932b6ad3",
-    "d6d3f754-d4f4-4672-b096-b994b064ca2d"
+    {
+      "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0",
+      "release": "c1f2f9c4-d86e-4007-b61c-a53dc36f3e72"
+    },
+    {
+      "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3"
+    },
+    {
+      "uuid": "d6d3f754-d4f4-4672-b096-b994b064ca2d"
+    }
   ]
 }
 ```