diff --git a/discovery/readme.md b/discovery/readme.md index 4ce3cc8..63e7d1c 100644 --- a/discovery/readme.md +++ b/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::: +urn:tei::: ```` -**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::` +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:: +urn:tei:purl:: ```` +Example: +```text +urn:tei:org.cyclonedx:pkg:pypi/cyclonedx-python-lib@8.4.0?extension=whl&qualifier=py3-none-any +``` + #### SWID +Where the `unique-identifier` is a SWID. + Syntax: ```text -urn:tei:swid:: +urn:tei: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::: +urn:tei: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:: +urn:tei: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.