Public Metadata and Discovery
Interoperable participants need an approved way to discover identifiers, public verification material, supported credential profiles, protocol capabilities, schemas, and status information. Public metadata reduces manual configuration, but it does not grant authorization or establish trust by itself.
Metadata categories
| Category | Public purpose | Important limitation |
|---|---|---|
| Institutional identifiers | Identify an issuer, verifier, or service controller | Resolution does not prove authority for every claim |
| Verification material | Publish public keys or certificates and their intended relationships | Private material and internal key operations remain protected |
| Issuer metadata | Describe supported issuance capabilities and profiles | Availability may vary by product, tenant, and onboarding status |
| Authorization metadata | Describe compatible authorization services and security features | Discovery does not register a client or grant scopes |
| Credential configurations | Identify credential types, formats, claims, display data, and proof requirements | Public summaries may omit partner-specific schemas and policies |
| Verifier metadata | Identify a requester and supported presentation behavior | A holder must still validate purpose and request context |
| Schemas and vocabularies | Define claim structure and semantics | Structural validity does not prove claim truth |
| Status information | Support expiry, suspension, revocation, or replacement checks | Public status should not expose sensitive reasons or holder history |
| Trust-framework references | Point to governance, accreditation, or federation context | Trust must be validated against the verifier's policy |
| Service capabilities | Describe supported standards and versions | Advertisement is not a universal conformance claim |
Discovery sequence
A relying participant should:
- obtain the metadata location through an approved bootstrap path;
- retrieve it over an authenticated and integrity-protected channel;
- validate provenance and expected controller;
- confirm the exact profile and version;
- apply local trust and algorithm policy;
- cache only within the approved freshness window;
- detect unexpected changes;
- fail safely when required metadata cannot be resolved.
Metadata should never be accepted solely because it was returned by an untrusted redirect or included inside an unverified transaction.
Public keys and verification material
Public verification material may be exposed through DID documents, JWKS, certificates, or another approved profile. Consumers should verify:
- issuer and controller relationship;
- key identifier and intended purpose;
- allowed algorithm and key type;
- activation, retirement, or revocation state;
- certificate or DID validation path;
- cache and rotation behavior;
- historical verification requirements.
A public key must never be accompanied by a private exponent, recovery secret, seed, or internal key-management credential.
Credential capability metadata
Credential metadata can help a wallet or partner understand:
- credential configuration identifier;
- format and profile;
- display name and supported languages;
- claim names and value expectations;
- proof or holder-binding requirements;
- authorization and delivery patterns;
- status and validity model;
- version and deprecation state.
The public representation should be descriptive enough for discovery without exposing customer data mappings, internal validation logic, or production approval rules.
Schemas and semantics
A schema should be immutable or clearly versioned after publication. Breaking changes require a new version and migration plan.
A schema registry or reference should distinguish:
- structural constraints;
- semantic meaning;
- issuer authority;
- disclosure classification;
- privacy sensitivity;
- lifecycle and compatibility.
Consumers should not assume that two similarly named fields have the same meaning across credential types or jurisdictions.
Status metadata
Status mechanisms should provide the minimum current-state information required for verification. Good status design avoids publishing:
- revocation reasons tied to a person;
- complete credential or holder inventories;
- stable correlation identifiers across contexts;
- internal case or incident data;
- administrative operations.
Verifier behavior during a status outage must be defined by policy rather than improvised at runtime.
Provenance and integrity
Metadata consumers should use controls such as:
- HTTPS origin validation;
- DID or certificate validation where applicable;
- signed metadata where the profile supports it;
- pinned issuer or trust-framework relationships;
- expected content type and schema validation;
- redirect restrictions;
- cache expiry and refresh rules;
- monitoring for unexpected key or capability changes.
Metadata that is syntactically correct but inconsistent with the approved partner profile should be treated as a controlled compatibility event.
Versioning and change
Public metadata should identify version, effective state, and deprecation where the profile supports them. Partners should receive advance notice for changes that affect:
- credential identifiers or schemas;
- endpoints or authorization behavior;
- algorithms, keys, or certificates;
- proof and holder-binding requirements;
- status mechanisms;
- required claims or presentation formats;
- error semantics;
- conformance expectations.
Key rotation can be routine, but consumers still need correct overlap, cache refresh, and historical verification behavior.
Privacy and abuse resistance
Public metadata should publish capabilities, not operational secrets. It should be reviewed for:
- personal data and tenant leakage;
- internal hostnames or topology;
- administrative endpoints;
- anti-abuse thresholds;
- unpublished customer relationships;
- operational health details that increase attack value;
- excessive fingerprinting or enumeration.
Rate control and monitoring can protect discovery services without preventing legitimate interoperability.
Public and partner discovery surfaces
The public surface can describe stable identifiers, standards, product capabilities, public verification material, and general credential profiles.
The controlled partner surface can additionally include approved environment metadata, exact schemas, client registration, test configurations, trust-framework membership, and compatibility notes.
Public documentation boundary
This page does not publish production endpoints, client identifiers, redirect locations, tenant inventories, private schemas, administrative interfaces, internal health data, unreleased capabilities, or cryptographic key-management details.
See Decentralized Identifiers, OpenID for Verifiable Credentials, and Partner Onboarding.