diff --git a/discovery/readme.md b/discovery/readme.md index f7184a8..e87d73e 100644 --- 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,6 +50,9 @@ 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 @@ -55,13 +60,15 @@ identifiers like EAN codes, PURL and other identifiers. It is based on a DNS nam 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::: ```` @@ -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