Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 27 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 compact variant is a compressed representation of an [ACDC](/concept/acdc) where top-level section fields contain either the [SAID](/concept/said) (Self-Addressing Identifier) of associated sections or the full SAD (Self-Addressed Data), enabling graduated disclosure while maintaining cryptographic commitment to all variants through the issuer's signature.
The compact variant represents a fundamental structural optimization in the ACDC (Authentic Chained Data Container) specification, serving as a compressed representation that balances data minimization with cryptographic verifiability. Within the KERI ecosystem, compact variants enable graduated disclosure mechanisms that progressively reveal credential information while maintaining end-to-end cryptographic integrity.
The compact variant serves multiple critical purposes in the ACDC architecture:
According to Document 3, the compact variant exists on a spectrum between two extremes:
Insertion Order Preservation: All serialization implementations MUST preserve insertion order of field maps. Use OrderedDict in Python, Map in JavaScript (ES6+), or equivalent ordered structures.
Compact Serialization: When computing SAIDs, serialize to compact JSON with NO whitespace: json.dumps(data, separators=(',', ':')). Any whitespace differences will produce different SAIDs.
Self-Referential SAID: The d field SAID must be computed over the structure containing itself. Implementation pattern:
d to empty string or placeholderd fieldoneOf Composition: Use JSON Schema oneOf operator to support both SAID strings and full object blocks:
"a": {
"oneOf": [
{"type": "string", "description": "SAID reference"},
{"$ref": "#/$defs/attributeBlock"}
]
}
Schema Immutability: Once a schema is published and its SAID is used in credentials, the schema MUST NOT change. Version schemas rather than modifying them.
Sign Fully Compact Form: The issuer signature should be computed over the fully compact variant (all sections as SAIDs). This signature then commits to all possible expansions.
Cross-Variant Verification: When verifying an expanded variant:
TEL Anchoring: Anchor the signature in a Transaction Event Log for issuance/revocation tracking. The TEL entry should reference the fully compact variant's top-level SAID.
UUID Field for Private ACDCs: Include a u field with ≥128 bits of cryptographic-strength random data to prevent rainbow table attacks on SAIDs. Without this, attackers can precompute SAIDs for common attribute values.
Most Compact Form: The minimal representation where all optional sections are represented solely by their SAIDs. This form discloses the absolute minimum information necessary while maintaining verifiability through cryptographic commitments.
Fully Compact Form: A complete but condensed representation where all sections are present but may be represented as SAIDs rather than expanded content. Document 24 clarifies that this is the only signed variant of an ACDC, with the signature cryptographically anchored in a Transaction Event Log (TEL).
The key architectural insight from Document 8 is that all ACDC variants are various degrees of expansion of the compact variant. This means the compact form serves as the canonical base representation, with other variants (partially expanded, fully expanded) building upon this foundation.
The compact variant's structure centers on top-level section fields, which Document 4 defines as fields shared across all variants of an ACDC. Each top-level section field contains one of two possible values:
This dual-value approach enables flexible disclosure patterns. A credential holder can present a compact variant with some sections as SAIDs (undisclosed) and others as full SADs (disclosed), creating what Document 26 describes as a "most compact" form for that specific disclosure level.
The compact variant maintains the standard ACDC top-level field structure defined in Document 9:
Core Identity Fields:
Content Section Fields (may be SAIDs or full content):
Privacy Field:
u (UUID): High-entropy nonce enabling private/public ACDC variantsThe critical distinction in compact variants is that content section fields (s, a, A, e, r) are represented as SAIDs rather than expanded content, while core identity fields remain fully specified.
Compact variants support multiple serialization formats as specified in Document 11:
All serialization formats must preserve insertion order of field maps, as this is critical for reproducible SAID computation. The specification explicitly states that lexicographic (alphabetical) ordering is NOT required—only insertion order matters.
Document 2 demonstrates that when computing a SAID, the ACDC must be serialized to compact JSON (no whitespace) to ensure consistent digest computation. The computed SAID then appears in the $id field of schemas or the d field of ACDCs.
The compact variant's size depends on the number of sections represented as SAIDs versus expanded content. A SAID in CESR encoding is a fixed-length qualified cryptographic digest, typically 44 characters in Base64 URL-safe encoding.
Size Optimization: By replacing potentially large attribute blocks, edge sections, or rule sections with their SAIDs, compact variants can achieve significant size reduction. For example, a credential with a 2KB attribute section can be reduced to a 44-character SAID, yielding over 97% size reduction for that section.
Constraint Requirements:
d field SAID must be computed over the entire compact variant structureu field with ≥128 bits of entropy to prevent rainbow table attacksCreating a compact variant involves several steps as outlined in Document 9:
oneOf composition operatorsd fieldd field SAID over the entire compact structureDocument 2 provides detailed Python-to-JSON mapping guidance:
True/False map to JSON true/falseNone maps to JSON nullCompact variants are immutable by design. The SAID-based architecture means any modification to content invalidates all SAIDs in the chain. However, the compact variant enables progressive disclosure without modification:
Expansion Operations: A compact variant can be expanded by replacing SAIDs with their corresponding SAD content. Document 26 explains that this creates different "most compact" forms at each disclosure level:
Each level maintains verifiability through the original issuer signature on the fully compact form.
Compaction Operations: Conversely, a fully expanded ACDC can be compacted by replacing SAD content with SAIDs. This operation is useful for:
Verification of compact variants involves multiple layers as described in Document 3:
Signature Verification:
SAID Verification:
Schema Validation:
Cross-Variant Commitment Verification: Document 6 emphasizes that compact variants maintain cross-variant Issuer commitment verifiability. This means:
Compact variants are integral to several KERI ecosystem protocols:
IPEX (Issuance and Presentation Exchange): Document 10 defines IPEX as the protocol for exchanging ACDCs, with compact variants enabling:
ACDC Chaining: Document 17 demonstrates how compact variants enable credential chaining in the vLEI ecosystem:
TEL (Transaction Event Log): Document 24 explains that the fully compact variant is anchored in TELs, providing:
The compact variant lifecycle follows these stages:
Issuance Phase:
Presentation Phase: Document 22 describes graduated disclosure:
Verification Phase:
Revocation Phase:
Compact variants interact with several related ACDC structures:
Fully Expanded Variant: Document 26 explains that when all SAIDs in a compact variant are replaced with their full SAD content, the result is a fully expanded variant. This represents maximum disclosure.
Metadata Variant: Contains only top-level fields without attribute, edge, or rule sections. Useful for credential discovery and catalog operations.
Partial Variant: Document 23 describes partial disclosure where some field maps are expanded while others remain as SAIDs. This creates intermediate disclosure levels.
Selective Variant: Enables unbundled disclosure of specific attributes from the A (Attribute Aggregate) section while keeping others blinded.
Private vs. Public Variants: Document 12 distinguishes:
u field with high-entropy UUID, making SAIDs resistant to rainbow table attacksu field, suitable for non-confidential data where discoverability is acceptableThe compact variant architecture enables seamless transitions between these related structures while maintaining cryptographic integrity through SAID-based commitments and issuer signatures that bind all variants together.
Graduated Disclosure Strategy: Design disclosure flows that start with highly compact forms and progressively expand only as needed. Never disclose more than necessary for the current transaction.
Correlation Resistance: Be aware that SAIDs are deterministic—identical content produces identical SAIDs. Use UUIDs and careful schema design to prevent unwanted correlation.
SAID Caching: Cache computed SAIDs to avoid redundant digest computation. SAIDs are immutable once computed.
Lazy Expansion: Don't expand all sections when receiving a compact variant. Expand only the sections needed for the current verification or presentation.
Streaming Support: For large ACDCs, consider streaming CESR encoding which supports efficient parsing of compact variants without loading entire structures into memory.
SAID Mismatch: If a disclosed section's computed SAID doesn't match the SAID in the compact variant, reject the credential immediately—this indicates tampering or corruption.
Schema Validation Failures: Validate both compact and expanded forms against the schema. A credential that validates in one form but not another indicates a schema design error.
Missing Sections: When expanding a compact variant, ensure all referenced SAIDs can be resolved to actual content. Missing sections should be treated as verification failures unless the use case explicitly supports partial disclosure.
Round-Trip Testing: Verify that compact → expanded → compact transformations preserve all SAIDs and structural integrity.
Cross-Variant Signature Testing: Test that signatures on compact variants successfully verify against all expanded forms.
Schema Compliance Testing: Validate that all compact and expanded variants conform to the schema's oneOf definitions.
Graduated Disclosure Scenarios: Test multi-step disclosure flows where different sections are progressively revealed across multiple presentations.