Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 13 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.
Semantic Versioning (semver) is a formal versioning specification that uses a three-part version number format: MAJOR.MINOR.PATCH. In the KERI/ACDC ecosystem, semver provides the standardized versioning mechanism for ACDC credential schemas, CESR code tables, and protocol specifications. The Semantic Versioning 2.0.0 specification defines how version numbers increment based on the nature of changes:
Within the KERI suite, semver plays a critical role in managing schema evolution and protocol compatibility:
vLEI Credential Schema Versioning: The GLEIF vLEI Ecosystem Governance Framework mandates semantic versioning for all official vLEI credential schemas. As documented in the Technical Requirements Part 3, a new schema version is considered backward incompatible when any credential instance validating against the previous version cannot guarantee validation against the new version. This triggers a MAJOR version increment. The current official vLEI schemas (QualifiedvLEIIssuervLEICredential, LegalEntityvLEICredential, etc.) are all at version 1.0.0.
ACDC Extensibility: ACDCs leverage JSON Schema composition operators that enable extensibility, allowing newer schema versions to potentially maintain backward compatibility with older versions. This design philosophy aligns with semver's MINOR version increments for additive changes that don't break existing validation.
Governance Requirement: The GLEIF vLEI Ecosystem Governance Framework mandates semantic versioning for all official credential schemas. Implementers must increment MAJOR version numbers when introducing backward-incompatible changes.
Backward Compatibility Testing: A schema version is backward incompatible when credentials validating against the previous version cannot guarantee validation against the new version. This requires careful testing of validation behavior across versions.
SAID Integration: Each semver version generates a new SAID due to content changes. The combination of human-readable semver and cryptographic SAID provides both compatibility signaling and integrity verification.
JSON Schema Composition: Leverage JSON Schema composition operators (allOf, anyOf, oneOf) to enable backward-compatible extensions that justify MINOR version increments rather than MAJOR version breaks.
Registry Management: The official vLEI Credential Schema Registry maintains a table mapping semver versions to SAIDs and GitHub URLs, providing authoritative version tracking.
Version String Field: KERI data structures include a version string field (v) that appears as the first field in top-level field maps. While KERI's version string format (ACDCMmmGggKKKKSSSS.) is more complex than pure semver, it incorporates versioning principles to indicate protocol type, version numbers, and serialization details.
CESR Version Management: The CESR-version uses special Count Codes to specify which version of CESR code tables applies to a given stream or stream section, enabling protocol evolution while maintaining backward compatibility where possible.
Schema Registry Integration: The vLEI Credential Schema Registry combines semver with SAID-based schema identification. Each schema version has a unique SAID, and the semver number provides human-readable compatibility information. The registry table lists schemas with both their semver version (e.g., "1.0.0") and their cryptographic SAID for integrity verification.