Canonical JSON Model

Source: Dev.to | Dec 16, 2025 (UTC)

Purpose

The Canonical JSON Model defines the stable, deterministic representation of AI execution state produced by a FACET-compliant system.

Its goal is to ensure that:

• identical inputs produce byte-for-byte identical JSON
• outputs are comparable, cacheable, diffable, and replayable
• provider-specific formats do not leak nondeterminism into downstream systems

Canonical JSON is the boundary artifact between deterministic compilation and probabilistic model execution.

Why Canonical JSON Is Necessary

Modern LLM stacks suffer from hidden nondeterminism:

• field reordering in JSON objects
• optional fields appearing/disappearing
• provider-specific message layouts
• streaming vs non-streaming structural drift
• implicit defaults applied at runtime

These effects make:

• caching unreliable
• replay impossible
• regression testing meaningless
• auditing and compliance fragile

Canonical JSON eliminates these failure modes by enforcing a single normalized shape.

Definition

A Canonical JSON Document is a JSON object that satisfies all of the following:

1. Deterministic field ordering
2. Explicit presence or absence of all optional fields
3. Stable numeric and string encoding
4. Provider-agnostic structure
5. Fully derived from a typed execution state

FACET treats Canonical JSON as a compiled artifact, not a serialization convenience.

Canonical Ordering Rules

FACET enforces a strict top-level ordering:

1. meta
2. system
3. tools
4. examples
5. history
6. user
7. assistant
8. output

This ordering is normative and MUST be preserved by all compliant implementations.

Nested objects follow:

• lexical key ordering (UTF-8, codepoint order)
• stable list ordering derived from execution order or explicit keys

Explicitness Rules

Canonical JSON forbids implicit defaults and structural ambiguity.

Rules:

• Optional Fields: Fields defined in the schema but missing from the runtime value MUST be explicitly rendered as null. Omission of known fields is PROHIBITED.
• Empty Lists: MUST be rendered as [].
• Empty Objects: MUST be rendered as {}.
• Booleans: MUST always be explicit (true / false).

Rationale: Explicit null guarantees that the JSON structure (keyset) remains constant regardless of data content, enabling O(1) shape verification and stable hashing across languages with different default serialization behaviors (e.g., JavaScript vs. Rust).

Numeric and String Normalization

To avoid cross-platform drift:

• Integers are rendered without leading zeros
• Floats use normalized decimal form (no exponent unless required)
• Strings are UTF-8, NFC-normalized
• Escaping follows JSON standard, no alternative encodings

Implementations MUST NOT emit:

• NaN
• Infinity
• locale-dependent number formats

Relationship to FACET Execution Phases

Canonical JSON is produced at the end of Phase 5 (Render).

Inputs:

• Typed AST
• Computed variable map
• Finalized Token Box layout
• Interface schemas

Outputs:

• One canonical JSON document
• Zero ambiguity about structure or meaning

Any violation at this stage MUST abort execution rather than emit a non-canonical result.

Canonical JSON vs Provider Payloads

Input: [.facet] -> [AST] -> [R-DAG] -> [Token Box] │ Core: [[ CANONICAL JSON IR ]] ─┤ │ Views: ┌──────────────┼───────────────┐ ▼ ▼ ▼ [OpenAI] [Anthropic] [Gemini] │ │ │ Output: └──────────────┼───────────────┘ ▼ [ API Call ]

Enter fullscreen mode

Exit fullscreen mode