Most modern programming languages support ordered dictionaries or hash tables that preserve insertion order, enabling this reproducibility without reordering.

Block-Delimited Serializations

In block-delimited serializations like JSON, each field-map is represented by an object block with delimiters such as {}. These blocks create clear structural boundaries within the serialization. The block-delimited nature is significant because:

• Each block represents a self-contained unit that can be independently verified
• Blocks can be replaced with their SAIDs for compact disclosure
• The hierarchical block structure enables selective disclosure mechanisms
• Block boundaries align with cryptographic commitment boundaries

The ACDC specification explicitly references these "block-delimited" serializations when discussing how field-maps are represented in JSON, CBOR, and MGPK formats.

Self-Describing and Self-Framing Properties

Field-maps in KERI/ACDC support self-describing properties, meaning the data structure includes metadata about its own contents. When combined with CESR encoding, field-maps participate in self-framing, where textual or binary encodings include type, size, and value information that allows parsers to extract elements from streams without additional delimiters.

The self-framing property is essential for:

• Stream processing - Parsers can extract field-maps from continuous streams
• Cold start parsing - Systems can begin parsing without prior context
• Composability - Field-maps can be converted between text and binary domains

Hierarchical Composition and Nesting

Nested Field Maps

Field-maps can be nested, where a field value itself references another field-map, creating hierarchical data structures. This nesting enables:

• Self-contained data units - Each nested field-map is independently verifiable
• Hierarchical composition - Complex data structures built from simpler components
• Selective disclosure - Revealing or hiding entire nested blocks
• Compact representation - Replacing nested field-maps with their SAIDs

For example, in an ACDC credential structure:

{
  "v": "ACDC10JSON000197_",
  "d": "EBdXt3gIXOf2BBWNHdSXCJnFJL5OuQPyM5K0neuniccM",
  "i": "did:keri:EmkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM",
  "s": "E46jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A",
  "a": {
    "d": "EgveY4-9XgOcLxUderzwLIr9Bf7V_NHwY1lkFrn9y2PY",
    "i": "did:keri:EpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPmkPreYpZ",
    "dt": "2021-06-27T21:26:21.233257+00:00",
    "LEI": "254900OPPU84GM83MG36"
  }
}

Here, the top-level field-map contains a nested field-map at the "a" (attributes) field, which itself contains multiple field-maps representing individual attributes.

Top-Level ACDC Structure

ACDCs define strict ordering for top-level field-maps: [v, d, u, i, rd, s, a, A, e, r], where each letter represents a specific field label:

• v: Version string - The first field in any top-level KERI field-map, enabling self-framing for JSON, CBOR, and MGPK serializations
• d: SAID of the ACDC - Self-addressing identifier providing content-addressable verification
• u: UUID - One-time use nonce for replay attack protection
• i: Issuer AID - Autonomic identifier of the credential issuer
• rd: Registry SAID - Reference to credential status registry for revocation checking
• s: Schema SAID - Identifier for the credential schema
• a: Attributes - Field-map or SAID containing credential claims
• A: Attribute aggregates - Additional attribute structures
• e: Edges - Field-map or SAID defining connections to other ACDCs
• r: Rules - Field-map or SAID containing Ricardian contract terms

Each of these top-level fields may contain nested field-maps, creating the hierarchical structure that enables graduated disclosure and cryptographic verification.

SAID Computation and Cryptographic Properties

Self-Addressing Identifiers

Field-maps are fundamental to SAID (Self-Addressing Identifier) computation. A SAID is a cryptographic digest that is embedded within the content it identifies, creating a self-referential but content-addressable identifier. The SAID computation process for field-maps works as follows:

1. Replace SAID placeholder: In the serialized field-map, the SAID field (typically labeled "d") is replaced with a dummy value of appropriate length
2. Compute digest: A cryptographic hash function (such as Blake3-256) is applied to the serialization
3. Embed SAID: The computed digest replaces the dummy value, creating the final self-addressed field-map
4. Verification: Any recipient can repeat the process to verify the SAID matches the content

This mechanism provides several critical properties:

• Content integrity - Any modification to field-map contents produces a different SAID
• Tamper evidence - Recipients can detect unauthorized changes
• Cryptographic binding - The identifier is cryptographically bound to the content
• Self-referential verification - No external references required for validation

24-Bit Alignment in CESR Context

When field-maps are encoded using CESR (Composable Event Streaming Representation), 24-bit alignment becomes critical. CESR achieves text-binary composability through careful management of bit boundaries:

• Base64 encoding uses 6 bits per character
• Binary bytes are 8 bits each
• Least common multiple of 6 and 8 is 24

Field-maps must align on 24-bit boundaries (3 bytes, 4 Base64 characters) to enable lossless conversion between text and binary domains. This alignment ensures:

• Composability - Concatenated field-maps can be converted en masse
• No pad characters - CESR never uses the = pad character
• Stream processing - Parsers can extract field-maps without delimiter confusion
• Pipelining efficiency - Groups of field-maps can be processed in parallel

The CESR specification uses pre-padding and lead bytes rather than post-padding to maintain this alignment while preserving the self-framing property.

Cross-Variant Verifiability

A powerful property of field-map SAIDs in ACDCs is cross-variant Issuer commitment verifiability. When an issuer signs an ACDC, they commit to the top-level field-map structure. This commitment remains valid across different variants:

• Full variant - All nested field-maps expanded
• Compact variant - Nested field-maps replaced with SAIDs
• Partially disclosed variant - Some field-maps expanded, others compact
• Selectively disclosed variant - Specific attributes revealed

The issuer's signature verifies against any variant because all variants share the same top-level field-map SAIDs, even when nested content is represented differently.

Serialization Format Support

Multiple Format Compatibility

Field-maps in KERI/ACDC support multiple serialization formats, each optimized for different use cases:

JSON (JavaScript Object Notation):

• Human-readable text format
• Field-maps represented as objects with {} delimiters
• Supports debugging and development workflows
• Self-describing through field labels
• Version string enables self-framing

CBOR (Concise Binary Object Representation):

• Compact binary format (RFC 8949)
• Efficient for network transmission
• Maintains field-map structure in binary encoding
• Supports same nested structures as JSON

MGPK (MessagePack):

• Binary serialization format
• Similar compactness to CBOR
• Cross-platform compatibility
• Preserves field-map relationships

CESR (Composable Event Streaming Representation):

• Dual text-binary format
• Unique composability properties
• Self-framing primitives
• Stream processing optimization

All serialization formats must preserve the canonical insertion-order of field-maps to maintain cryptographic integrity. The order in which fields were originally created must be maintained across all format transformations.

Interleaved Serialization

CESR supports interleaved serialization, where field-maps from different formats can be mixed within a single stream. Special count codes enable CESR streams to incorporate:

• JSON field-maps for human-readable sections
• CBOR field-maps for compact binary sections
• MGPK field-maps for cross-platform compatibility
• Native CESR primitives for cryptographic material

This interleaving capability is particularly important for:

• Flexible data structures - Field-maps, dictionaries, hash tables
• Self-describing data - Format metadata embedded in stream
• Efficient processing - Each section uses optimal encoding

Sniffable Streams

A CESR stream containing field-maps is sniffable when it begins with recognizable markers:

• Group codes - Indicating grouped primitives
• Field-map markers - Indicating structured data objects
• Unique bit patterns - Three-bit combinations distinguishing formats

The Parside parser leverages sniffability to detect field-map types:

• CESR binary field-maps
• CESR text field-maps
• JSON field-maps
• CBOR field-maps
• MGPK field-maps

This cold start problem solution enables parsers to begin processing field-maps from any point in a stream without prior context or framing information.

Privacy and Disclosure Mechanisms

Graduated Disclosure Framework

Field-maps are central to ACDC's graduated disclosure mechanisms, which enable progressive revelation of credential information. The framework operates through strategic manipulation of field-map representations:

Compact Disclosure:

• Replace full field-maps with their SAIDs
• Provides cryptographic commitment without revealing content
• Enables verification that content matches commitment
• Reduces data transmission size

Partial Disclosure:

• Some field-maps disclosed in full, others as SAIDs
• Progressively reveals information as requirements are met
• Partially disclosed fields become correlatable after full disclosure
• Enables negotiated revelation based on verifier needs

Selective Disclosure:

• Uses cryptographic aggregator (not accumulator)
• Each selectively disclosable attribute has dedicated blinded block
• All field-maps must be addressed (blinded or published)
• Unlike partial disclosure, selectively disclosed fields remain non-correlatable

Full Disclosure:

• Context-dependent meaning:
  • In selective disclosure: detailed disclosure of selected attributes only
  • In partial disclosure: detailed disclosure of previously compact field-map
• Represents final revelation step in disclosure progression

Contractually Protected Disclosure

Field-maps enable contractually protected disclosure through the rules section (r field). This top-level field-map can embed:

• Ricardian contracts - Legal language in machine-readable format
• Usage terms - Conditions on data utilization
• Chain-link confidentiality - Downstream recipient obligations
• Cryptographic references - SAID-based contract commitments

The rules field-map is both human-readable and machine-processable, enabling automated enforcement of disclosure terms while maintaining legal validity.

Graph Structure and Edge Field-Maps

Labeled Property Graphs

The edges top-level field-map (e) transforms ACDCs into nodes within a directed acyclic graph (DAG). Each edge field-map can contain:

• Target identifiers - SAIDs of other ACDCs
• Edge weights - Numerical properties via optional weight field-map
• Edge operators - Logic expressions for graph traversal
• Relationship metadata - Type and context of connections

This creates a labeled property graph (LPG) where:

• Nodes are ACDCs (structured as field-maps)
• Edges are cryptographically verifiable connections
• Properties are embedded in edge field-maps
• Graph topology is verifiable through SAID chains

Edge Operators

The operator field-map within edge sections enables expression of edge logic:

• Unary operators - Logic on individual edges
• M-ary operators - Logic on edge groups
• Subgraph expressions - Complex graph traversal rules

These operators transform static edge field-maps into dynamic graph processing instructions, enabling sophisticated credential chain verification and authorization propagation.

Implementation Considerations

Version String Requirement

The version string field-map (v) serves as a workaround mechanism to enable self-framing in JSON, CBOR, and MGPK serializations. As the first field in any top-level KERI field-map, it:

• Identifies the CESR code table version
• Enables parsers to load correct interpretation rules
• Provides format recognition for stream processing
• Maintains backward compatibility across protocol versions

The version code "tells you which set of tables to load, it tells the table state."

Schema Integration

Field-maps interact with JSON Schema validation through the schema field (s). The schema SAID references a formal specification defining:

• Required and optional field labels
• Data types for field values
• Structural constraints on nested field-maps
• Validation rules for attribute field-maps

This integration provides:

• Interoperability - Common schema understanding between parties
• Type safety - Validation of field-map structure
• Cryptographic verifiability - Schema itself is self-addressed

Attribute Field-Maps

The attributes field-map (a) is specifically designed for credential claims. It can be provided as:

• Full attribute block - Complete nested field-map structure
• Compact SAID reference - Cryptographic commitment only
• Composed JSON Schema - Schema-defined structure
• Non-composed JSON Schema - Simple attribute list

Attribute field-maps support:

• Selective disclosure - Individual attributes as separate blocks
• Partial disclosure - Progressive attribute revelation
• Schema validation - Type checking and constraint enforcement

Advanced Topics

SAD Path Signatures

Field-maps can be signed using SAD (Self-Addressed Data) path notation, enabling:

• Partial signing - Multiple signers for different field-maps
• Embedded credentials - ACDCs within ACDCs
• Granular commitments - Signing specific nested structures

However, the practical use of pathing in credential signing remains limited, with its primary application being message forwarding in KERI protocols.

Registry Integration

The registry field-map (rd) connects to Transaction Event Logs (TELs) for credential status tracking. This field-map:

• References the management TEL controlling the registry
• Enables revocation checking through registry queries
• Supports privacy-preserving status verification
• Integrates with KERI key event infrastructure

Dynamic Table Loading

Advanced parsers (like Parside) support dynamic code table loading based on version strings in field-maps. This enables:

• Runtime adaptation to protocol updates
• Support for multiple CESR versions
• Backward compatibility with legacy field-maps
• Forward compatibility through graceful degradation

Relationship to Other KERI Concepts

Field-maps are deeply integrated with core KERI primitives:

• AIDs (Autonomic Identifiers) - Appear as field values in issuer and issuee fields
• KELs (Key Event Logs) - Structured as ordered field-maps of events
• Witnesses - Field-maps specify witness configurations
• Seals - Anchoring field-maps in establishment events
• OOBIs (Out-Of-Band Introductions) - Discovery of endpoints for field-map resolution

The consistent use of field-map terminology throughout KERI specifications prevents confusion between data structures and cryptographic keys, enabling clearer reasoning about protocol security properties.

Conclusion

Field-maps represent the fundamental data structure abstraction throughout the KERI/ACDC ecosystem. Their carefully designed properties—insertion ordering, self-addressing, format-agnostic serialization, and graduated disclosure support—enable the construction of verifiable, privacy-preserving, and cryptographically secure credential systems. Understanding field-maps is essential for implementing KERI protocols, as they form the foundation upon which all higher-level constructs are built.

The deliberate renaming from "key-value pairs" to "field-maps" exemplifies the KERI design philosophy: precise terminology prevents semantic confusion in security-critical systems where clarity is paramount. By consistently using field-map terminology, developers can reason about data structures without conflating them with the cryptographic keys that provide security properties. This linguistic precision, combined with the robust technical properties of field-maps themselves, creates a solid foundation for building the next generation of decentralized identity and verifiable credential infrastructure.