fix: aligned TEI examples to specification

CycloneDX / transparency-exchange-api

A standard API specification for exchanging supply chain artifacts and intelligence

https://tc54.org/

Apache License 2.0

59 stars 9 forks source link

fix: aligned TEI examples to specification #88

Open madpah opened 2 days ago

madpah commented 2 days ago

Resolves #87

ppkarwasz commented 2 days ago

Maybe the examples are right and the specification should be modified. The first element you might expect in a URN is the authority.

madpah commented 2 days ago

Fair comment @ppkarwasz - @oej - thoughts on the order of the items in TEI?

We are questioning the current urn:tei:<type>:<domain-name>:<unique-identifier> vs urn:tei:<domain-name>:<type>:<unique-identifier>

oej commented 1 day ago

The TYPE needs to come first as we can come up with TEI types that has another resolution than DNS in the future.

ppkarwasz commented 1 day ago

Aren't there two <type>s then?

One tells us how to find the TEA service.
One is part of the identifier

For example:

urn:tei:dns:logging.apache.org:purl:pkg:maven/org.apache.logging/log4j-core tells the user to use the DNS discovery mechanism we were talking about.
urn:tei:purl:pkg:maven/org.apache.logging/log4j-core tells the user to use an ecosystem-dependent mechanism to find the TEA server.

Alternatively, to keep it simple:

The TEI identifier only refers to the DNS mechanism and we have: urn:tei:logging.apache.org:purl:pkg:maven/org.apache.logging/log4j-core.
If a user doesn't find a TEI, but find the PURL pkg:maven/org.apache.logging/log4j-core, he can still use a TEA service, but the resolution mechanism is ecosystem-dependent.

oej commented 1 day ago

I don't like restricting the TEI to ONLY DNS resolution. There will be a lot of work establishing the TEI as a common identifier and having to restart that work for new non-DNS types will be hard. Better to have one single identifier and be able to extend it.

But you are not wrong that the PURL could be used for TEA discovery too, especially for stuff that is not packaged. That is a discussion we need to bring up in the PURL wg, I just haven't had time for it. We mentioned it briefly as an option in the SBOM forum vulnerabilities wg meeting. I'm thinking of commercial software and open source projects not primarily being distributed as packages (like C code).

ppkarwasz commented 1 day ago

I don't like restricting the TEI to ONLY DNS resolution. There will be a lot of work establishing the TEI as a common identifier and having to restart that work for new non-DNS types will be hard. Better to have one single identifier and be able to extend it.

In that case shouldn't <type> be fixed to dns for now? The way I see it we have:

urn:tei:<authority>:<opaque_identifier>

For now the authority is dns:<domain-name>, which means "the owner of <domain-name>", but in the future we could have tin:PL1234567890 to identify a company by their Tax Identification Number. If we want extensibility, IMHO it is premature to define the structure of all future TEIs. URNs don't need to be resolvable, so a TEA client that gets urn:tei:purl can say "Sorry, I don't know how to find the TEA server for this identifier".

I was also wondering: shouldn't we pass the entire TEI to the TEA server? E.g. GET /product/urn:tei:apache.org:<some-id>?

oej commented 1 day ago

I was also wondering: shouldn't we pass the entire TEI to the TEA server? E.g. GET /product/urn:tei:apache.org:<some-id>?

I have been asking that in a few conversations.

oej commented 1 day ago

I don't like restricting the TEI to ONLY DNS resolution. There will be a lot of work establishing the TEI as a common identifier and having to restart that work for new non-DNS types will be hard. Better to have one single identifier and be able to extend it.

In that case shouldn't <type> be fixed to dns for now? The way I see it we have:

No, type indicates a specific syntax for a product identifier defined in our TEI document. For each type we define whether DNS is used or not. If DNS is NOT used, there has to be another way to discover the web site to find the API to.

Having a type that is a company registration number doesn't really point to a specific product from that company. If there was a global database of registration numbers that resolves to DNS it could be an alternative resolution for a specific type. I have been looking at medical device IDs where the device ID actually has a company identifier embedded. If there's an ENUM-like way to resolve that in DNS, it could be a type with no DNS name.

oej commented 1 day ago

We really need to clarify the intent of the TEI. But that's another PR

oej commented 1 day ago

Created issue #89 to clarify the TEI URN more. It's definitely needed for registration with IANA/IETF

madpah commented 7 hours ago

Requested changes made @oej