ADR-0010 — Type identifier URN and EAA category signal
Status: Accepted ✅ (2026-09-24). On acceptance, DECISIONS D-SCHEMA-1 → D-SCHEMA-4 (superseded) and a new D-CRED-4 (category signal).
Context
The existing decision and why it was reopened
ADR-0007 decision 1 / DECISIONS D-SCHEMA-1: vct (vct (Verifiable Credential Type)The permanent identifier of a credential type in SD-JWT VC; in Tamga it is a URN such as urn:tamga:edu:Diploma:1.) is a stable HTTPS URL (https://schema.tamga.network/v1/edu/DiplomaCredential/1.0.0), Type Metadata is fetched directly from that URL, and vct#integrity is mandatory and equal to the contentHash on the ledger.
A check against the primary texts on 2026-09-23/24 showed:
| Source | What it says |
|---|---|
| IETF draft-ietf-oauth-sd-jwt-vc-19 §2.2.2.1 | vct is a collision-resistant name: an HTTPS URL or a URN (example urn:example:eudi:pid:…) |
| same, §5.3 | Type Metadata can be obtained (1) from the URL, (2) from a trusted registry, (3) by an ecosystem-defined method, (4) from a cache |
| ETSI TS 119 472-1 V1.2.1 EAA-5.2.1.2-02/03 | vct must point to Type Metadata; vct#integrity is mandatory |
| ARF PID Rulebook v2.4.0 | PID type urn:eudi:pid:1; domestic urn:eudi:pid:<cc>:1; metadata in the catalogue (PID_15) |
| ARF Attestation Rulebook template | vct must be unique in the ecosystem; no format imposed |
| ETSI TS 119 472-1 §4.2.2 | The EAA category is a class signal "in the context of issuance"; the EU URNs (urn:etsi:esi:eaa:eu:qualified / …:pub) are for the EU; "an EAA may contain a category" |
So the existing HTTPS decision conforms to the standard; so would a URN. The choice is not technical but governance-related. Direction from project management (2026-09-24): the beta is set up as if it already worked with the Organization of Turkic States. That settles the open question: the credential type identifier of a multi-state consortium cannot depend on a foundation's domain name (tamga.network). The SPEC-SCHEMA-0001 §10.3 section on "domain risk" had already recorded this dependency as an "ecosystem-wide event".
Second topic: how is the issuer class visible in a credential?
Under eIDAS (electronic IDentification, Authentication and trust Services)The EU regulation on electronic identification and trust services; eIDAS 2.0 introduces the European Digital Identity Wallet., QEAA (Qualified Electronic Attestation of Attributes)An EAA issued by a qualified trust service provider (QTSP); it has the strongest legal effect among attestations. and PuB-EAA (Public-Body Electronic Attestation of Attributes)An attestation issued by or on behalf of a public body responsible for an authentic source. carry a category signal inside the credentialA digital document signed by an issuer and held in the person's wallet; the person shows only the fields that are asked for. (Annex V/VII "an indication suitable for automated processing"); non-qualified EU EAAsThe eIDAS term for a credential that attests attributes of a person, such as a degree or a membership. do not. In Tamga's canonical model the issuerThe institution that signs and issues credentials: a university, a professional body, a public institution or a company. grade (I1–I3) is kept only in the registry; there is no class signal in the credential. In the multi-state set-up the Tamga ecosystem should mirror the eIDAS structure: a document issued by a state institution or on behalf of an authentic source and a document from an institution accredited under the Trust Framework must be distinguishable for the verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party. from inside the credential. HolderThe person who keeps a credential in their wallet and decides whom to show it to. LoA (Level of Assurance)How much confidence can be placed in an identity or a credential; Tamga uses separate levels for proofing (T), issuer (I) and wallet (W)., by contrast (PR7), does not enter the credential — nor does it in eIDAS.
Decision
Decision 1 — vct is a URN
urn:tamga:<domain>:<Type>:<major>
domain ∈ {core, edu, org, health, mobility, travel, trade, …} (SPEC-SCHEMA-0001 §1.2 domain list)
Type = PascalCase type name (DiplomaCredential, StudentCredential, TamgaBaseCredential)
major = integer; increases on breaking changes
Examples:
urn:tamga:core:TamgaBaseCredential:1
urn:tamga:edu:StudentCredential:1
urn:tamga:edu:DiplomaCredential:1
Phase 1, state-specific (domestic) types:
urn:tamga:<cc>:<domain>:<Type>:<major> e.g. urn:tamga:tr:edu:TranscriptCredential:1
Category signals (decision 5):
urn:tamga:eaa:pub · urn:tamga:eaa:qualifiedschemaId = keccak256(bytes(vct)) does not change (SPEC-SCHEMA-0001 §5.1).
Decision 2 — Type Metadata resolution route = catalogue (registry)
The IETF §5.3.2 "trusted registry" route is primary. The record (ledger SchemaRegistry / phase B lotl › schemas[]) holds for every type: vct, metadata_url, content_hash, status, status_history. Verifier/wallet:
Ş1. read vct + vct#integrity (missing → REJECT)
Ş2. schemaId = keccak256(vct); is there a record, and its status (ACTIVE/DEPRECATED by iat)
Ş3. Type Metadata: cache(vct#integrity) → GET record.metadata_url → (fallback) catalogue bundle
Ş4. SHA-256(bytes) == vct#integrity == record.content_hash; document.vct == credential.vct
Ş5–Ş7 unchanged (extends, JSON Schema, authorisation)schema.tamga.network is no longer the type identifier but the catalogue and hosting address; if the domain changes only the metadata_urls change, while vcts and issued documents are unaffected. The catalogue is also the counterpart of the ARF "Catalogue of attestation schemes"; the bundle (catalogue.jws) serves the wallet's bulk fetch (CMP8/WL9).
Decision 3 — vct#integrity stays mandatory; D1/D2 are reworded
SPEC-SCHEMA-0001/D1 "the content at a published vct URL never changes" → "the content at a published metadata_url never changes"; D2 "contentHash = vct#integrity = SHA-256(published bytes)" unchanged; D3 unchanged. vct#integrity is mandatory in credentials (ETSI 472-1 EAA-5.2.1.2-03; optional in IETF — we stay strict).
Decision 4 — Versioning
- major is in the URN; a breaking change = a new URN = a new
schemaId; old documents keep being verified with the old URN (SC3 DEPRECATED window). - minor/patch are in the Type Metadata
versionfield; every publication gets a newmetadata_url+content_hash(the old URL does not change, per D1); the record marks the "current" one; one URN may have several metadata versions, and thevct#integrityin the credential pins down which one is meant. The SPEC-SCHEMA-0001 §9 semver rules are rewritten accordingly.
Decision 5 — Tamga EAA category signal
In the credential (an SD-JWT VC claim, sd: never, not subject to selective disclosure):
Issuer record class | category claim | EU counterpart | Who |
|---|---|---|---|
PUB | urn:tamga:eaa:pub | PuB-EAA | A member-state institution or on behalf of an authentic source (civil registry, higher-education council, trade registry…) — registered by the state (onlyOwnerState) |
QUALIFIED | urn:tamga:eaa:qualified | QEAA | An I3 issuer accredited under the Trust Framework (qualified e-seal/HSM/audit/insurance) |
EAA | none | EAA (non-qualified) | I1–I2 issuers |
Rules: (a) an issuer may only use the signal of the class in its record; the verifier compares it with the record in layer C, a mismatch → REJECTED (new step code C4, a new code per SPEC-API-0001 AP1); (b) holder assurance (T0–T3) is never written into the credential — PR7 kept, the level is a precondition of the type (DB-6); (c) the EU URNs (urn:etsi:esi:eaa:eu:*) may not be used by Tamga issuers (we are outside the EU context); (d) if a state defines its own qualified class in phase 1, the sub-namespace urn:tamga:<cc>:eaa:qualified is opened.
Implementation note (2026-11-12; approved by project management) — the class signal in mdoc and ZK presentations. The category signal is the category claim of the SD-JWT VC; an mdoc (ISO/IEC 18013-5) credential and a ZK presentation have no such element. For these formats the verifier does not apply C4 and shows it in checks_skipped in the result. In every format the issuer class is returned in the result object (issuer.class) from the record in the trust list; the relying party always reads the class from the same place. C4 is a consistency check against a forged signal: a format that carries no signal cannot carry a forged one, so not applying the step does not weaken trust. Today mdoc is issued only for identity types (ADR-0013) and the issuer of those types is of class EAA (no signal is expected anyway). Before an institution of class PUB or QUALIFIED starts issuing mdoc, a separate decision settles whether the class signal is carried in mdoc (if it is, a new element name is needed). No code change.
Decision 6 — Managing the urn:tamga namespace
Informal in the beta (like EUDI's urn:eudi). In phase 1, a formal IANA URN NID registration (RFC 8141) is Trust Framework work. Allocation of sub-namespaces (edu, eaa, <cc>) is in the Trust Framework; from phase 0 on, Governance 2/3 on the ledger.
Decision 7 — Migration
No credential has been issued yet; no dual support. SPEC-SCHEMA-0001, SPEC-SCHEMA-0002 (vct values, Type Metadata examples), SPEC-SCHEMA-0003 (skeleton vcts), SPEC-CRED-0002 (category claim + new C rule), SPEC-API-0001 (step C4), SPEC-PROTO-0001 (PR2 text "every vct in the metadata is registered" unchanged). The list format in the operator's internal record is already in this form.
Rationale
- Domain independence = hand-over independence. This applies the multi-state principle to the type identifier: just as
ca_idandissuer_idare independent of the operator, so mustvctbe. An HTTPS vct makes thetamga.networkdomain part of the type identifier forever. - The same look as EUDI. PID
urn:eudi:pid:1+ catalogue; ETSI categories are URNs. For an EUDI verifier,urn:tamga:…+ catalogue is the same processing path asurn:eudi:…+ catalogue. - No loss of standards conformance. The IETF §5.3.2 and ETSI 472-1 "point to the metadata" requirement is met through the catalogue; mandatory
#integritymakes us stronger than the ARF catalogue (no hash requirement) (R-13). - The cost is close to zero now. No code; specification texts only. After code had been written, this change would affect every wallet, verifier and issuer.
- The category signal mirrors the eIDAS structure and lets the credential answer the verifier's question "state institution, accredited, or registered?"; the cross-check against the record (C4) prevents a fake signal.
Alternatives considered
A — Stay with HTTPS URLs (D-SCHEMA-1) — rejected (on governance grounds)
Conforms to the standard, self-resolving for an outside verifier (IETF §5.3.1 is in every library), with the §10.3 mitigations in place. But the type identifier stays bound to a domain name, which conflicts with the multi-state principle. Technically it was not wrong; this ADR supersedes it as "not fitting the set-up", not as "faulty".
B — A .well-known/vct route — not applicable
It is not in draft-19 (it was in interim drafts). Defining a non-standard route breaks interoperability.
C — A DID-based type identifier (did:…) — rejected
ADR-0004 superseded the DID entity profile; bringing DIDs back for type identity would be inconsistent.
D — No category signal (the earlier DB-15) — rejected
It is true that in the EU's eyes we are non-qualified EAA; but ETSI 472-1 allows a context-specific category, and the multi-state set-up needs its own classes. Leaving it out keeps the PUB/QUALIFIED distinction only in the registry and makes the credential less self-describing than its EU counterparts.
E — Putting holder LoA into the credential — rejected (again)
eIDAS does not; PR7 does not; the PM-TRUST-0001 rationale holds. The level is a precondition of the type.
Consequences
Binding
- DECISIONS: D-SCHEMA-1 → the changed-decisions table; new D-SCHEMA-4 (vct URN + catalogue), D-CRED-4 (category signal, never holder LoA).
- SPEC-SCHEMA-0001: §1 "URL scheme" → "URN scheme + catalogue"; §1.4 resolution; §7 Ş3; §9 versioning; D1 reworded;
category_allowedin thetamgablock. - SPEC-SCHEMA-0002, SPEC-SCHEMA-0003: vct values.
- SPEC-CRED-0002:
categoryclaim (optional, must match the record), new invariant C18 "categoryis accepted only if it equals theclassin the record; there is no holder assurance claim". - SPEC-API-0001: step C4 (category ↔ record),
issuer.classin the result object. PM-ASSUR-0001: aclasscolumn in the axis B table; policy example "type × class".- Index sync: INVARIANTS D1 text, C18, C4; MASTER_INDEX versions.
Accepted trade-offs
- A verifier outside Tamga cannot resolve
urn:tamga:…metadata without knowing the Tamga catalogue (with HTTPS a GET was enough). Mitigation: the catalogue URL is announced in the Trust Framework; the SDK carries it by default; EUDI verifiers do the same for EU URNs. - The category claim is one more assertion; without the C4 cross-check it is meaningless (which is why it cannot be skipped).
Relations
Supersedes (in part): ADR-0007 decision 1 (vct HTTPS URL); D-SCHEMA-1 Keeps: ADR-0007 K2–K6 (off-chain metadata + anchor, #integrity, two tiers, allow-list) Builds on: ADR-0009 decision 5 (multi-state first) · RS-EIDAS-0001 §4.4/§5.1 · IETF SD-JWT VC-19 · ETSI TS 119 472-1 Changes: SPEC-SCHEMA-0001, SPEC-SCHEMA-0002, SPEC-SCHEMA-0003, SPEC-CRED-0002, SPEC-API-0001, PM-ASSUR-0001Analysis source: the operator's internal record.
Status
Accepted ✅ — 2026-09-24. Recorded in DECISIONS as D-SCHEMA-4 and D-CRED-4; the follow-up specification updates are tracked in the DECISIONS §10 list of open commitments.