Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 21 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
A schema registry is a centralized repository for managing credential schemas based on namespaces. In KERI/ACDC systems, Self-Addressing Identifiers (SAIDs) and verifiable data structures have eliminated the need for centrally controlled schema registries, enabling decentralized schema management through cryptographic self-addressing.
A schema registry is traditionally a centralized service that stores, manages, and provides access to data schemas—particularly credential schemas in identity systems. In conventional verifiable credential architectures, schema registries serve as authoritative sources where:
The core properties of traditional schema registries include:
Centralized Authority: A single entity or coordinated set of entities controls schema publication and namespace allocation
Namespace Management: Schemas are organized hierarchically, with organizations claiming exclusive rights to specific namespace prefixes
Version Control: The registry tracks schema versions and manages backward compatibility
Discovery Mechanism: Provides lookup services so verifiers can retrieve schemas by identifier
The scope of a schema registry extends beyond mere storage—it functions as a coordination point for ecosystem-wide interoperability, ensuring all participants reference consistent schema definitions.
Schema registries emerged from the broader need for data format coordination in distributed systems. The concept has roots in:
XML Schema Registries: Early web services used centralized XML schema repositories to ensure consistent data exchange formats across organizational boundaries.
JSON Schema Ecosystems: As JSON became the dominant data interchange format, schema registries evolved to manage JSON Schema definitions, particularly in API ecosystems where multiple services needed to validate data structures consistently.
Verifiable Credential Systems: The W3C Verifiable Credentials Data Model initially assumed schema registries would be necessary infrastructure. Organizations like schema.org provided centralized vocabularies, and various credential ecosystems established their own schema registries to coordinate credential formats.
When creating schemas for KERI/ACDC systems:
Cryptographic Strength: Use digest algorithms with approximately 128 bits of cryptographic strength (e.g., Blake3-256)
CESR Encoding: Encode the SAID using CESR format to indicate the digest algorithm type
Content Stability: Ensure schema content is finalized before SAID generation—any change produces a new SAID
Collision Resistance: The strong collision resistance of the digest algorithm guarantees that different schemas will have different SAIDs
For schema distribution without centralized registries:
Well-Known URIs: Publish schemas at .well-known endpoints for HTTP-based discovery (see Document 6)
Direct Transmission: Include schemas in credential presentations when verifiers may not have them cached
OOBI-Based Discovery: Use Out-Of-Band Introductions to provide schema location information
Version Management: Follow Semantic Versioning 2.0.0 for schema evolution, with backward incompatible changes requiring MAJOR version increments
When verifying credentials with SAID-based schemas:
Extract Schema SAID: Retrieve the schema SAID from the credential's schema field
Obtain Schema Content: Retrieve schema from cache, well-known URI, or direct transmission
Verify SAID: Compute the digest of the schema content and verify it matches the SAID
Validate Credential: Use the verified schema to validate the credential structure
This process ensures schema integrity without requiring trust in a centralized registry operator.
Namespace Collision Problems: Traditional approaches faced challenges when multiple organizations wanted similar namespace identifiers, requiring governance processes to arbitrate conflicts and allocate namespace rights.
The evolution of schema registries reflected a fundamental tension: the need for decentralized identity systems conflicted with the centralized coordination required for schema interoperability. This tension motivated the search for alternatives that could achieve interoperability without centralized infrastructure.
KERI and ACDC fundamentally transform schema management through cryptographic self-addressing, eliminating the need for centralized schema registries.
The core innovation is using SAIDs (Self-Addressing Identifiers) to identify schemas. As specified in Document 1 and Document 5, each schema version has a universally unique SAID generated through:
Cryptographic Digest: The SAID is a cryptographic hash of the schema content with approximately 128 bits of cryptographic strength
CESR Encoding: SAIDs are encoded using CESR (Composable Event Streaming Representation), with the encoding indicating the digest algorithm type
Content Addressability: The SAID cryptographically binds to the schema content—any modification produces a different SAID
Collision Resistance: Strong collision resistance guarantees that any schema copy verifying against a SAID is identical to any other copy with the same SAID
Rather than requiring a centralized registry, KERI enables multiple distribution mechanisms:
Direct Distribution: Schemas can be transmitted directly between parties as verifiable data structures
Well-Known URIs: As shown in Document 6, schemas can be published at .well-known endpoints for discovery
Graph Fragments: Document 3 and Document 4 explain that ACDC uses graph fragments and KERI-based verifiable data structures as an alternative to centralized registries
Percolated Discovery: Schemas can be discovered through percolated information discovery mechanisms without centralized coordination
KERI's approach maintains compatibility with existing standards while adding cryptographic verifiability. Document 1 and Document 5 specify:
JSON Schema 2020-12 Compliance: All vLEI credential schemas MUST comply with JSON Schema 2020-12, ensuring standard validation semantics and tooling compatibility
Composition Operators: ACDC leverages JSON Schema composition operators (allOf, anyOf, oneOf) to enable schema extensibility and backward compatibility
Semantic Versioning: Schemas follow Semantic Versioning 2.0.0, with backward incompatible changes requiring MAJOR version increments
While KERI eliminates the requirement for centralized registries, Document 1 and Document 5 show that organizations may still choose to publish authoritative schema lists for governance purposes. GLEIF maintains a normative schema table for six official vLEI credential types:
Critically, this "registry" is not required for cryptographic verification—it serves governance and discovery functions. The SAIDs themselves provide verification, and schemas are hosted on GitHub, not a proprietary registry service.
KERI's schema management differs fundamentally from centralized registries:
No Central Coordination Required: Parties can create and use schemas without permission from or registration with a central authority
Cryptographic Verification: Schema integrity is verified through SAIDs rather than trust in a registry operator
Namespace Independence: Organizations don't need to reserve namespaces—SAIDs provide globally unique identifiers without coordination
Offline Verification: Verifiers can validate schemas without network access to a registry, as long as they have the schema content and SAID
Immutable Versioning: Each schema version has a unique SAID, making version identification unambiguous and tamper-evident
The KERI approach provides several advantages:
Decentralization: Eliminates single points of failure and control in schema management
Censorship Resistance: No central authority can prevent schema publication or revoke schema identifiers
Reduced Infrastructure: Organizations don't need to operate or depend on registry services
Improved Privacy: Schema usage doesn't require queries to centralized services that could track credential verification patterns
Stronger Integrity: Cryptographic binding between schema content and identifier prevents substitution attacks
Interoperability by Design: As noted in Document 8, Document 18, and Document 19, ACDC's graph-based architecture provides interoperability without centralized coordination
Credential Issuance: Issuers embed schema SAIDs in ACDCs, allowing verifiers to retrieve and validate schemas from any source
Schema Evolution: Organizations can publish new schema versions with new SAIDs, and credentials explicitly reference which version they conform to
Multi-Issuer Ecosystems: Different issuers can use the same schemas (identified by SAID) without coordinating through a central registry
Offline Verification: Verifiers can cache schemas and validate credentials without network connectivity
Cross-Ecosystem Interoperability: Schemas can be shared across different credential ecosystems without requiring registry federation
Reduced Operational Costs: Organizations avoid the expense of operating or subscribing to registry services
Faster Deployment: New schemas can be deployed immediately without registration delays
Enhanced Security: Cryptographic verification provides stronger guarantees than registry-based trust
Regulatory Compliance: Decentralized schema management aligns with data sovereignty requirements
Ecosystem Resilience: Schema availability doesn't depend on registry uptime
Discovery Challenges: Without a central registry, discovering available schemas requires alternative mechanisms like OOBIs or well-known URIs
Governance Complexity: Ecosystems must establish governance processes for schema standardization without relying on registry gatekeeping
Tooling Maturity: Developers may need to adapt to SAID-based schema references rather than familiar URL-based registry patterns
Caching Requirements: Verifiers must implement schema caching strategies since schemas aren't retrieved from a canonical registry
Despite these trade-offs, KERI's approach represents a fundamental improvement in schema management for decentralized identity systems, eliminating centralized infrastructure while maintaining—and enhancing—the integrity guarantees required for credential verification.