Merge pull request #187 from oej/tei-update

Update the discovery

Author: oej

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