Skip to content
ADR-0010Architecture decisionAcceptedversion 1.0.012 November 2026

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:

SourceWhat it says
IETF draft-ietf-oauth-sd-jwt-vc-19 §2.2.2.1vct is a collision-resistant name: an HTTPS URL or a URN (example urn:example:eudi:pid:…)
same, §5.3Type 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/03vct must point to Type Metadata; vct#integrity is mandatory
ARF PID Rulebook v2.4.0PID type urn:eudi:pid:1; domestic urn:eudi:pid:<cc>:1; metadata in the catalogue (PID_15)
ARF Attestation Rulebook templatevct must be unique in the ecosystem; no format imposed
ETSI TS 119 472-1 §4.2.2The 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:qualified

schemaId = 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 version field; every publication gets a new metadata_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 the vct#integrity in 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 classcategory claimEU counterpartWho
PUBurn:tamga:eaa:pubPuB-EAAA member-state institution or on behalf of an authentic source (civil registry, higher-education council, trade registry…) — registered by the state (onlyOwnerState)
QUALIFIEDurn:tamga:eaa:qualifiedQEAAAn I3 issuer accredited under the Trust Framework (qualified e-seal/HSM/audit/insurance)
EAAnoneEAA (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 ​

  1. Domain independence = hand-over independence. This applies the multi-state principle to the type identifier: just as ca_id and issuer_id are independent of the operator, so must vct be. An HTTPS vct makes the tamga.network domain part of the type identifier forever.
  2. 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 as urn:eudi:… + catalogue.
  3. 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 #integrity makes us stronger than the ARF catalogue (no hash requirement) (R-13).
  4. 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.
  5. 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 ​

  1. DECISIONS: D-SCHEMA-1 → the changed-decisions table; new D-SCHEMA-4 (vct URN + catalogue), D-CRED-4 (category signal, never holder LoA).
  2. SPEC-SCHEMA-0001: §1 "URL scheme" → "URN scheme + catalogue"; §1.4 resolution; §7 Ş3; §9 versioning; D1 reworded; category_allowed in the tamga block.
  3. SPEC-SCHEMA-0002, SPEC-SCHEMA-0003: vct values.
  4. SPEC-CRED-0002: category claim (optional, must match the record), new invariant C18 "category is accepted only if it equals the class in the record; there is no holder assurance claim".
  5. SPEC-API-0001: step C4 (category ↔ record), issuer.class in the result object.
  6. PM-ASSUR-0001: a class column in the axis B table; policy example "type × class".
  7. 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.