Merge pull request #68 from madpah/patch/dns-record-update-to-svcb

Updated Discovery to cater for move to SVCB DNS records

discovery/readme.md

@@ -2,6 +2,17 @@
 
 **NOTE**: _This is a proposal for the WG_
 
+- [From product identifier to API endpoint](#from-product-identifier-to-api-endpoint)
+- [TEA Discovery - defining an extensible identifier](#tea-discovery---defining-an-extensible-identifier)
+- [The TEI URN: An extensible identifier](#the-tei-urn-an-extensible-identifier)
+  - [TEI syntax](#tei-syntax)
+  - [TEI types](#tei-types)
+  - [TEI resolution using DNS](#tei-resolution-using-dns)
+  - [Finding the Index using DNS result](#finding-the-index-using-dns-result)
+- [The TEA Version Index](#the-tea-version-index)
+- [References](#references)
+
+
 ## From product identifier to API endpoint
 
 TEA Discovery is the connection between a product identifier and the API endpoint.
@@ -19,11 +30,8 @@ TEA discovery is the process where a user with a product identifier can discover
 artifacts automatically, with or without authentication. A globally unique identifier is
 required for a given product. This identifier is called the Transparency Exchange Identifier (TEI).
 
-The TEI identifier is based on DNS, which assures a
-uniqueness per vendor (or open source project) and gives the vendor a name space to
-define product identifiers based on existing or new identifiers like EAN 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 TEI identifier is based on DNS, which assures a uniqueness per vendor (or open source project) 
+and gives the vendor a name space to define product identifiers based on existing or new identifiers like EAN 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 TEI URN: An extensible identifier
 
@@ -34,70 +42,82 @@ 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
 
-- The **type** which defines the syntax of the unique identifier part
-- The **domain name** part does not have to exist as a web server (HTTPS).
-- The uniqueness of the name is the domain name part that has to be registred at creation of the TEI.
-- The **unique identifier** has to be unique within the domain. Recommendation is to use UUID,
-  but it can be an existing article code too.
+- The **`type`** which defines the syntax of the unique identifier part
+- The **`domain-name`** part does not have to exist as a web server (HTTPS), but may do
+  - The uniqueness of the name is the domain name part that has to be registred at creation of the TEI.
+- The **`unique-identifier`** has to be unique within the `domain-name`. Recommendation is to use a UUID but it can be an existing article code too
 
 A TEI belongs to a single product. A product can have multiple TEIs - like one with a EAN
-bar code and one with the vendor's product number.
+barcode and one with the vendor's product number.
 
 ### TEI syntax
 
-
 ```
-urn:tei:<type>:<domain>:<data>
+urn:tei:<type>:<domain-name>:<unique-identifier>
 ````
 
-**Note**: this requires a registration of the TEI URN schema with IANA.
+**Note**: this requires a registration of the TEI URN schema with IANA - [see here](https://github.com/CycloneDX/transparency-exchange-api/issues/18)
 
-### TEI examples
+### TEI types
 
-- `urn:tei:uuid:`    for a company specific name and product identifier as UUID
-- Example: `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
-- Syntax: `urn:tei:uuid:<name based on domain>:<unique identifier>`
+The below show examples of TEI where the types are specific known formats or types.
 
-### TEI types
+Reminder: the `unique-identifer` component of the TEI needs only be unique within the `domain-name`.
 
 #### PURL - Package URL
 
+Where the `unique-identifier` is a PURL in it's canonical string form.
+
 Syntax:
 
 ```text
-urn:tei:purl:<domain or host>:<purl>
+urn:tei:purl:<domain-name>:<purl>
 ````
 
+Example:
+```text
+urn:tei:org.cyclonedx:pkg:pypi/[email protected]?extension=whl&qualifier=py3-none-any
+```
+
 #### SWID
 
+Where the `unique-identifier` is a SWID.
+
 Syntax:
 
 ```text
-urn:tei:swid:<domain or host>:<swid>
+urn:tei:swid:<domain-name>:<swid>
 ````
 
 Note that there is a TEI SWID type as well as a PURL SWID type.
 
 #### HASH
 
-Supports the following hash values:
+Where the `unique-identifier` is a Hash. Supports the following hash types:
 
 * SHA256
 * SHA384
 * SHA512
 
 ```text
-urn:tei:hash:<domain or host>:<hashtype>:<hash>
+urn:tei:hash:<domain-name>:<hashtype>:<hash>
 ````
 
+Example:
+```text
+urn:tei:cyclonedx.org:SHA256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9
+```
+
 The origin of the hash is up to the vendor to define.
 
 #### UUID
 
+Where the `unique-identifier` is a UUID.
+
 Syntax:
 
 ```text
-urn:tei:uuid:<domain or host>:<uuid>
+urn:tei:uuid:<domain-name>:<uuid>
 ````
 
 Has to be a valid UUID.
@@ -108,6 +128,7 @@ Has to be a valid UUID.
 - GS1
 - STD
 
+
 ### TEI resolution using DNS
 
 The name part of the TEI is used in a DNS query to find one or multiple locations for product transparency exchange information.
@@ -146,7 +167,7 @@ Append the product part of the TEI to the URI found
 
 - TEI: `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
 - DNS record: `_tei._tcp.products.example.com`
-- URI in DNS: `https://www.example.com/transparency/`
+- URI in DNS: `://www.example.com/transparency/`
 - URL: `https://www.example.com/transparency/d4d9f54a-abcf-11ee-ac79-1a52914d44b1/`
 
 If no DNS URI records are found the resolution defaults to A and AAAA records.