Updating discovery to use TEI: URL

[oej]

Moving away from URN based on feedback from IETF expert group

[oej]

Discussion in meeting: Should we skip the BASE64URL encoding?

[Mehrn0ush]

Mandatory Base64 for UUID/EAN/GTIN/etc. seems to obscure identifiers that are already path-safe, so I’d propose we scope it down. For PURL (and, as noted below, SWID), some encoding is still needed when moving from urn:tei:type:domain:id (positional slots) to tei://domain/type/id (path segments), so those two are a different case.
My preference would be to avoid percent-encoding those identifiers in-path, for a few reasons:

• the percent-encoded form isn’t really any more readable than Base64 would be
• % in the identifier segment ends up double-encoded once the whole TEI is placed in /discovery?tei= (% → %25), which is a subtle failure mode
• %2F inside what’s meant to be a “single segment” is a known interop headache across CDNs, Apache, WAFs, etc.
• Base64URL, by contrast, composes cleanly when the full TEI gets URL-encoded again downstream.

So here's what I'd propose:

Type	Shape	Encoding
uuid, eanupc, gtin, asin, udi	…/<type>/<id>	Raw single leaf segment
hash	…/hash/<hashtype>/<hex>	Raw — two fixed sub-path segments (not one leaf like uuid); <hashtype> is a token from the documented list (currently SHA256/SHA384/SHA512); <hex> is the digest
purl, swid	…/<type>/<id>	BASE64URL without = padding of the canonical UTF-8 identifier string; decoders should accept unpadded input (re-pad to a multiple of 4 before decoding, or accept both padded and unpadded forms)

I looked into NISTIR 8060 to check whether tagId could safely be treated as raw. It turns out @regid is explicitly defined there as an RFC 3986 URI, but @tagId isn’t given any documented character restriction — and NIST’s own multi-language example in §4.3 actually uses a tagId with a literal space and non-ASCII characters (jp.largecomputerco.タグ番号 1). So if TEA’s swid type ends up embedding a tagId (or similar free-text SWID identifier), I don’t think we can assume it’s path-safe, and it’d probably be safer to give it the same Base64URL treatment as PURL rather than passing it through raw.

Curious what others think.

[oej]

I don't have access to the SWID ISO standard but it seems complex to include an XML document into a URL... Anyone that knows more? Is there a simplified tag we can use to indicate a product release?

[oej]

I've removed BASE64URL on everything except PURLs now. Thanks for the feedback @Mehrn0ush

[Mehrn0ush]

Good question — TEI doesn't put a SWID XML document in the URL.

In the discovery readme, the swid type works like uuid or purl: one identifier string in urn:tei:swid:<domain-name>:<swid>, not an XML blob. The obvious thing to put there is the SWID @tagId — the short unique ID every tag already has (NISTIR 8060 has examples like com.acme.rms-ce-v4-1-5-0). The full SWID tag, or CoSWID on constrained devices, would be something you fetch after discovery, not something embedded in the TEI itself.

One follow-up on the latest push, though: since db2a754 removes BASE64URL from everything except PURL, swid is now in the "raw" bucket too. I don't think that's safe — @tagId has no documented character restriction, and NIST's own §4.3 example includes a space and non-ASCII characters (jp.largecomputerco.タグ番号 1). So swid probably needs to stay alongside purl with BASE64URL, not join the raw group.

Also, the readme doesn't explicitly say <swid> = bare @tagId — worth pinning that down in the same pass.

And unrelated to all this: the readme already notes there's a TEI-native swid type and a separate PURL SWID form (pkg:swid/...) — easy to conflate, worth keeping distinct.

[oej]

RIght, I did not touch SWID because I had no example. I can do that now.

[taleodor]

Some inconsistency issues:

• The only end-to-end /discovery examples don't follow the new grammar. One mixes a literal <domain-name> placeholder with URN-style colons and then encodes to a different string than it shows; the other glues a URN body onto a tei:// prefix with the PURL raw, although the text above makes BASE64URL mandatory for PURL.
• The UUID example appears in three renderings: raw in the UUID section, BASE64URL in the DNS overview, raw again in the TLS section. The text says UUIDs are raw.
• 404 is overloaded. The new error-handling section defines 404 as "discovery endpoint not present", while the unchanged text further down and the OpenAPI spec define a /discovery 404 as "TEI unknown". A client can't tell "fail over to the next endpoint" from "stop" -> I would recommend sticking with TEI unknown. Otherwise, let's discuss.
• The port sentence survives, but its justification (URN location-independence) was deleted, and tei://host:8443/... is now a syntactically valid authority with no stated handling.
• The rest of the repository stays on the URN form: the /discovery example in spec/openapi.yaml, the normative grammar in doc/tea-uuid-scope.md, "TEI URNs" in tea-component.md, and the {tei_urn} path in the publisher spec. The doc's own table of contents still links to the old heading.

Also some issues vs #258 that would need to be addressed:

• It says an expired token means new versions won't be accessed and should be surfaced to users. Under feat: token exchange endpoint and documentation #258 an expired access token is routine: 401 with error="invalid_token", fetch a new token, retry once. Only an expired API key is user-facing.
• The error list omits the 401 Bearer challenge, which feat: token exchange endpoint and documentation #258 makes the signal that authentication is required.
• "Validate TLS certificates" is a SHOULD here; feat: token exchange endpoint and documentation #258 says clients shall verify the server certificate.
• The touched line "sometimes with an associated authentication token" should say API key.

One pre-existing security note we can address here

Redirect handling on the .well-known/tea fetch and on /discovery is unspecified. /discovery sits under bearer auth, so a cross-origin redirect could leak the access token. #262 already states that a client never sends its token when following a redirect to a different origin; discovery should state or reference the same rule, since it's the first authenticated call.