From bc40acebd4d4458b0475d337f6eda5a0e114c427 Mon Sep 17 00:00:00 2001 From: "Olle E. Johansson" Date: Wed, 18 Jun 2025 13:50:16 +0200 Subject: [PATCH 1/4] Add a note about not deriving TEIs, or guessing Signed-off-by: Olle E. Johansson --- discovery/readme.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/discovery/readme.md b/discovery/readme.md index f7184a8..704edc3 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) @@ -37,6 +35,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 From 09efd263776cf54edc9145efea371d399a93970a Mon Sep 17 00:00:00 2001 From: "Olle E. Johansson" Date: Wed, 18 Jun 2025 13:54:13 +0200 Subject: [PATCH 2/4] Add a note about required uniqueness of the TEI Signed-off-by: Olle E. Johansson --- discovery/readme.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/discovery/readme.md b/discovery/readme.md index 704edc3..5cda1a6 100644 --- a/discovery/readme.md +++ b/discovery/readme.md @@ -49,6 +49,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 @@ -56,13 +59,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 consist of three core parts + ```text urn:tei::: ```` @@ -150,6 +155,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 @@ -201,11 +211,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 From f18cd388aefb4e64d494d236737b4ff47ef2706b Mon Sep 17 00:00:00 2001 From: "Olle E. Johansson" Date: Wed, 18 Jun 2025 14:32:56 +0200 Subject: [PATCH 3/4] Clarify that a "product" can be both hardware and software Signed-off-by: Olle E. Johansson --- discovery/readme.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/discovery/readme.md b/discovery/readme.md index 5cda1a6..9d3f1f4 100644 --- a/discovery/readme.md +++ b/discovery/readme.md @@ -15,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 From 963ebde3ef4caded1bccea1ebaab907921fe6e28 Mon Sep 17 00:00:00 2001 From: "Olle E. Johansson" Date: Wed, 18 Jun 2025 14:53:15 +0200 Subject: [PATCH 4/4] Spelling error Signed-off-by: Olle E. Johansson --- discovery/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/discovery/readme.md b/discovery/readme.md index 9d3f1f4..e87d73e 100644 --- a/discovery/readme.md +++ b/discovery/readme.md @@ -67,7 +67,7 @@ barcode and one with the vendor's product number. ### TEI syntax -The TEI consist of three core parts +The TEI consists of three core parts ```text urn:tei:::