This ordering requirement is "non-existent in much of the Javascript world and many other credential formats" but is essential for KERI's security model. Modern programming languages support ordered dictionaries/hash tables that maintain insertion order, making this requirement implementable.

Schema Composition

ACDC schemas leverage JSON Schema composition operators (oneOf, allOf, anyOf) to support multiple variants of the same credential type:

• Compact variant: Top-level sections represented solely by their SAIDs
• Partially expanded variant: Some sections expanded while others remain compact
• Fully expanded variant: All sections and nested structures fully detailed

This composition approach enables graduated disclosure - the ability to progressively reveal credential information while maintaining cryptographic integrity across all disclosure levels.

Data Format

JSON Schema 2020-12 Compliance

All vLEI credential schemas MUST be compliant with JSON Schema 2020-12, the official specification maintained by the JSON Schema organization. This ensures:

• Standard validation semantics across implementations
• Interoperability with JSON Schema tooling ecosystems
• Support for composition operators enabling extensibility
• Consistent schema validation behavior

Schema Structure Components

A complete ACDC schema document contains several key components:

Top-Level Metadata:

• $id: The schema's SAID, computed through the SAIDification process
• $schema: Reference to JSON Schema specification version ("https://json-schema.org/draft/2020-12/schema")
• title: Human-readable schema name
• description: Schema purpose and usage documentation
• type: Always "object" for ACDC schemas
• credentialType: Specific credential type identifier (e.g., "LegalEntityvLEICredential")

Required Fields Array: Specifies which top-level fields are mandatory for a valid ACDC instance. Typically includes:

• v (version string)
• d (credential SAID)
• i (issuer AID)
• ri (registry identifier)
• s (schema SAID)

Properties Object: Defines each field's structure, type, and constraints. For ACDC schemas, this includes:

• Version field (v): String type with specific format requirements
• SAID fields (d, s): String type representing cryptographic digests
• Identifier fields (i, ri): String type for AIDs and registry references
• Section fields (a, e, r): Complex objects or SAID references using oneOf composition

Nested Section Schemas: Each major ACDC section (attributes, edges, rules) has its own nested schema definition with:

• Its own $id (SAID)
• Required fields specific to that section
• Type definitions for section-specific data
• Constraints on additional properties (additionalProperties: false)

SAIDification Process

The schema SAIDification process is recursive, proceeding from innermost blocks outward:

1. Preparation: Schema file contains empty $id fields ("") at all levels
2. Leaf-level SAID calculation: Innermost blocks (e.g., individual attribute definitions) have their SAIDs computed first
3. SAID embedding: Computed SAIDs are embedded into their parent structures
4. Parent-level SAID calculation: Parent blocks compute their SAIDs, incorporating the already-embedded child SAIDs
5. Recursive progression: Process continues upward until the top-level schema SAID is computed

This recursive approach ensures that:

• Each nested structure has its own stable SAID
• Parent SAIDs cryptographically commit to all child content
• Any modification at any level produces a new SAID at that level and all parent levels

Field Ordering and Canonicalization

The schema document itself defines the canonical field ordering through the sequence in which properties are declared in the properties object. When serializing an ACDC instance:

1. Fields must appear in the order specified by the schema
2. This order is preserved during SAID computation
3. Verifiers can reconstruct the canonical serialization by following the schema's field order
4. This deterministic ordering prevents malleability attacks where field reordering could bypass signature verification

Operations

Schema Creation and SAIDification

Creating a new ACDC schema involves several steps:

1. Schema Design:

• Define credential purpose and use case
• Identify required attributes and their types
• Determine edge relationships to other credentials
• Specify rules and governance clauses
• Design for graduated disclosure requirements

2. JSON Schema Authoring:

• Write JSON Schema document following ACDC conventions
• Include all required top-level fields
• Define nested sections (attributes, edges, rules)
• Use composition operators for variant support
• Set additionalProperties: false to prevent schema extensions

3. SAIDification Execution:

• Use SAIDification tools (e.g., Python scripts in vLEI training materials)
• Process schema recursively from innermost to outermost blocks
• Compute Blake3-256 digests for each block
• Encode digests in CESR format
• Embed SAIDs into $id fields

4. Validation and Testing:

• Verify schema is valid JSON Schema 2020-12
• Test with sample ACDC instances
• Confirm SAID computation is reproducible
• Validate composition operators work correctly

Schema Resolution and Verification

When processing an ACDC, verifiers must resolve and verify the schema:

Schema Resolution:

1. Extract schema SAID from ACDC's s field
2. Resolve schema document via OOBI (Out-Of-Band Introduction)
3. Fetch schema from schema server or registry
4. Cache schema locally for performance

Schema Verification:

1. Compute SAID of fetched schema document
2. Compare computed SAID with ACDC's s field value
3. If SAIDs match, schema is authentic and unmodified
4. If SAIDs don't match, schema has been tampered with - reject credential

Instance Validation:

1. Parse ACDC instance according to schema structure
2. Validate all required fields are present
3. Check field types match schema definitions
4. Verify constraints and value ranges
5. Validate nested structures recursively

Schema Versioning and Evolution

ACDC schemas follow Semantic Versioning 2.0.0 principles:

Version Numbering:

• MAJOR: Incremented for backward-incompatible changes
• MINOR: Incremented for backward-compatible additions
• PATCH: Incremented for backward-compatible fixes

Backward Compatibility:

• A schema version is backward incompatible when credentials validating against the previous version cannot guarantee validation against the new version
• JSON Schema composition operators enable extensibility such that newer schema versions may be backward compatible with older versions
• Each schema version has its own unique SAID

Schema Evolution Strategy:

1. New schema versions are created as separate documents
2. Each version has a distinct SAID
3. Credentials reference specific schema versions via SAID
4. Multiple schema versions can coexist in the ecosystem
5. Verifiers must support schema versions they accept

Schema Registry Management

Schemas are managed through registries that provide:

Schema Publication:

• Schemas hosted on accessible servers (e.g., GitHub, vLEI-server)
• OOBI URLs enable schema discovery
• Schema SAIDs serve as content-addressable identifiers

Schema Lookup:

• Verifiers resolve schema SAIDs to schema documents
• Caching improves performance
• Multiple resolution mechanisms (HTTP, IPFS, etc.)

Schema Governance:

• Official schemas maintained by governance authorities (e.g., GLEIF for vLEI)
• Schema updates follow governance processes
• Schema deprecation policies

Usage Context

ACDC Credential Issuance

Schemas are central to the ACDC issuance workflow:

Issuer Perspective:

1. Select appropriate schema for credential type
2. Populate ACDC fields according to schema structure
3. Include schema SAID in ACDC's s field
4. Ensure field ordering matches schema definition
5. Compute ACDC SAID with schema reference included
6. Sign and anchor ACDC to issuer's KEL

Holder Perspective:

1. Receive ACDC with schema SAID reference
2. Resolve schema to understand credential structure
3. Validate ACDC conforms to schema
4. Store ACDC with schema reference for future presentations

Verifier Perspective:

1. Receive ACDC presentation
2. Extract schema SAID from ACDC
3. Resolve and verify schema
4. Validate ACDC instance against schema
5. Check schema is from trusted governance authority

vLEI Ecosystem Implementation

The vLEI ecosystem demonstrates production schema usage:

Official vLEI Schemas (all version 1.0.0):

1. QVI Credential (EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao)
2. Legal Entity Credential (ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY)
3. OOR Authorization Credential (EKA57bKBKxr_kN7iN5i7lMUxpMG-s19dRcmov1iDxz-E)
4. OOR Credential (EBNaNu-M9P5cgrnfl2Fvymy4E_jvxxyjb70PRtiANlJy)
5. ECR Authorization Credential (EH6ekLjSr8V32WyFbGe1zXjTzFs9PkTYmupJ9H65O14g)
6. ECR Credential (EEy9PkikFcANV1l7EHukCeXqrzT1hNZjGlUk7wuMO5jw)

Schema Hosting:

• All official schemas hosted on GitHub: GLEIF-IT/vLEI-schema repository
• Schemas served via vLEI-server for OOBI resolution
• Schema SAIDs preconfigured in vLEI workflows

Schema Governance:

• GLEIF maintains official schema registry
• Schema updates follow vLEI Ecosystem Governance Framework
• Schema versions tracked in governance documentation

IPEX Protocol Integration

Schemas play a crucial role in IPEX (Issuance and Presentation Exchange) protocol:

Schema-Based Negotiation:

• Verifiers specify required schema SAIDs in presentation requests
• Holders filter credentials by schema to match requests
• Schema compatibility checked before presentation

Graduated Disclosure:

• Schema defines which sections support compact disclosure
• Verifiers can request specific disclosure levels
• Schema structure enables progressive revelation

Contractually Protected Disclosure:

• Schema disclosure precedes data disclosure
• Parties agree on schema before exchanging sensitive data
• Schema serves as contract for data structure

Schema in Credential Chaining

ACDC schemas support credential chaining through edge definitions:

Edge Schema Requirements:

• Edge sections specify required schema SAIDs for linked credentials
• Schema validation ensures proper credential chains
• Edge operators (I2I, NI2I, DI2I) defined in schema

Chain Validation:

1. Verify each credential in chain against its schema
2. Check edge references point to credentials with correct schemas
3. Validate edge operators match schema definitions
4. Ensure chain integrity through schema conformance

Schema Security Properties

Immutability:

• Schema SAID cryptographically binds to content
• Any modification produces new SAID
• Tamper-evident schema references

Verifiability:

• Schema authenticity verified through SAID computation
• No trusted third party needed for schema validation
• End-to-end verifiable schema integrity

Interoperability:

• Standard JSON Schema format
• Composition operators enable extensibility
• Multiple implementations can validate consistently

Privacy:

• Schema structure supports selective disclosure
• Compact variants hide attribute details
• Schema reveals structure without revealing data

Implementation Considerations

Schema Design Best Practices

Minimize Breaking Changes:

• Use composition operators for extensibility
• Design schemas with future evolution in mind
• Consider backward compatibility in initial design

Clear Field Semantics:

• Use descriptive field names
• Include comprehensive descriptions
• Document field purposes and constraints

Graduated Disclosure Support:

• Design attribute sections for selective disclosure
• Use nested structures for privacy control
• Enable compact and expanded variants

Edge Relationship Clarity:

• Clearly specify required linked credential schemas
• Document edge operators and their semantics
• Define chain validation requirements

Schema Tooling Requirements

SAIDification Tools:

• Recursive SAID computation
• CESR encoding support
• Canonical serialization

Validation Tools:

• JSON Schema 2020-12 validators
• ACDC-specific validation rules
• Field ordering verification

Schema Servers:

• OOBI-compatible schema hosting
• Schema caching mechanisms
• Version management support

Performance Optimization

Schema Caching:

• Cache resolved schemas locally
• Implement cache invalidation strategies
• Balance freshness with performance

Lazy Schema Resolution:

• Resolve schemas only when needed
• Batch schema resolutions
• Prefetch commonly used schemas

Validation Optimization:

• Compile schemas for faster validation
• Cache validation results
• Use efficient JSON Schema validators

Lazy Validation: For large ACDC graphs, consider lazy validation strategies where schemas are validated only when needed rather than eagerly validating entire graphs.

Security Considerations

SAID Verification: ALWAYS verify schema SAID before using a schema. Accepting schemas without SAID verification opens attack vectors where malicious schemas could be substituted.

Schema Source Trust: Only accept schemas from trusted sources. In vLEI ecosystem, official schemas come from GLEIF-controlled repositories. Implement schema source validation.

Version Pinning: When building applications, pin to specific schema versions (SAIDs) rather than accepting any version. This prevents unexpected behavior from schema updates.

Interoperability

JSON Schema 2020-12: Ensure validators support JSON Schema 2020-12 specification. Older validators may not support composition operators correctly.

CESR Encoding: Schema SAIDs use CESR encoding with specific prefixes (e.g., 'E' for Blake3-256). Implementations must correctly encode/decode CESR primitives.

Cross-Language Consistency: When implementing in multiple languages, ensure SAID computation produces identical results. Test cross-language compatibility with reference test vectors.