Surfaces and projections

Lossless canonical (cx fmt)

Lossless canonical (cx fmt) preserves every node: comments, anchors, aliases, merges, CX directives, BlockContent, RawText, processing instructions. It normalizes only presentation: whitespace, indent, quoting, number formatting.

• Idempotent: fmt(fmt(x)) == fmt(x) for any valid x.
• Use cases: opinionated source-file formatter; diff stability across edits that don't change data; code review where reviewers see only meaningful changes.

          # a note about the user
[user id=1 name="Alice"]
        

          $ cx --from=cx --to=cx input.cx
# a note about the user
[user id=1 name=Alice]
        

Strict canonical (cx canonical / cx hash)

Strict canonical (cx canonical) reduces input to data-equivalence form. Strips comments and directives, expands anchors and aliases, resolves merges, normalizes datetime offsets to UTC, renames declared ids to a deterministic document-order scheme. Two CX documents have identical strict canonical bytes if and only if they encode the same data. Attribute order is data — it is preserved, never sorted.

• Use cases: cx hash (content-addressable hashing — SHA-256 of strict canonical bytes); signed configuration (sign the strict canonical bytes; verify after canonicalizing); deduplication keyed on data, not file bytes.
• Strict canonical is what the identity story rests on. Two documents that "encode the same data" but differ on comments, whitespace, quoting, or anchor names still hash to the same bytes.

          [$cx:canonical [$cx:parse "[user
  [; regrettably noisy comment ]
  email='ada@example.com'
  id=42
  active=true]"]]
        

          $ cx prog.cx
'[user email=ada@example.com id=42 active=true]\n'
        

The strict-canonical bytes are what the SHA-256 hash is taken over (see hash) and what the round-trip guarantee is checked against (see roundtrip).

Mixed content and the lossless $tag envelope

Mixed content — text interleaved with inline elements — has no native JSON form. The default projection is lossy: the text runs collect into an array under a reserved "_" key and the inline elements become sibling keys, so run order is not recoverable. Under --lossless, an element instead emits as the reserved $tag envelope (spec/03-approved/core/conversions.md §2.2.1): $children is an ordered array of runs, so mixed content survives exactly.

          [$cx:to-format [para 'The function ' [code 'parse'] ' returns a value.'] "json"]
        

          $ cx prog.cx
'{\n  "para": {\n    "_": [\n      "The function ",\n      " returns a value."\n    ],\n    "code": "parse"\n  }\n}'
        

JSON → CX reverses this unconditionally: a $tag envelope reconstructs the element with its body in order. The round-trip is byte-identical against cx canonical output (cx eq accepts the recovered document); the envelope also carries attributes ($attrs + $attr-types), element metadata ($anchor / $merge / $id / $type), and [table] payloads ($cols / $rows).

Namespace handling

CX namespace declarations (xmlns:dc=URI) project as JSON object keys with the xmlns: prefix preserved. Qualified names like dc:title project as JSON keys with the colon preserved (JSON keys are arbitrary strings, so this is legal). Round-trip is lossless when consumers preserve the xmlns: attributes.

Number precision and BigInt

JSON numbers are IEEE-754 doubles per RFC 8259, with ambiguous integer support beyond 2^53-1. CX exports int64 integers as JSON numbers; bigint scalars export as JSON strings, with the type recovered in lossless mode via the cx:type sidecar (map positions) or the per-item {"cx:bigint": "…"} carrier (array positions) — see spec/03-approved/core/conversions.md §0.2. Sized variants (::i32, ::u64) keep their native number image; the width name rides the envelope's $type / $attr-types in lossless mode.

Floats with nan / inf / -inf are not reachable from pure CX arithmetic (CX floats are finite-only); at the FFI boundary the JSON module's nan-handling option controls null / string / error behavior.

null vs missing

JSON has no way to distinguish "key absent" from "key present with value null." CX preserves the distinction where JSON can express it: [user email=null] projects to {"user": {"email": null}}, while an empty element [user] projects to {"user": null} (an element with no attributes and no body has nothing to become an object of). JSON → CX reads absent keys as absent attributes (NOT as null).

YAML tags (!!binary and the !!cx: family)

Two tag families are honored on YAML → CX parse: !!binary (base64 payload → CX :bytes — a: !!binary aGVsbG8= parses to [a 0x68656c6c6f]) and the CX-specific !!cx:T type carriers. Any other tag — including the standard !!str / !!int — is not interpreted: the whole scalar text, tag included, is kept as one string (!!custom foo parses to the string '!!custom foo'). On emit, ambiguity is prevented by quoting, not tagging: a numeric-looking string emits as '42'; bytes emit with !!binary.

Multiline scalars (| and >)

On input, YAML's literal (|) and folded (>) block styles parse per YAML 1.2 — newlines preserved or folded respectively. On emit there is no block-scalar form: the canonical YAML emitter is block-style for structure but writes multi-line string values as ordinary quoted scalars with escaped newlines (body: "line one\\nline two"), which round-trip exactly.

Anchors and aliases

YAML-native anchors (&name) and aliases (*name) are resolved (expanded) on YAML → CX parse — the data content is preserved, the anchor/alias structure is not (spec/03-approved/core/conversions.md §5.1). In the other direction the default YAML emit is symmetric: CX anchors and merges are resolved — aliases expand to their referent, merge hosts inherit — so the YAML carries the semantic document (the Resolved AST, ast.md). The lossless envelope instead carries the authored structure via $anchor / $merge keys, which the importer reconstructs — so a --lossless round-trip preserves them.

Section headers, not inline tables

TOML allows three spellings for nested scalars: inline tables (server = { host = "x" }), dotted keys (server.host = "x"), and section headers. All three parse; the emitter's choice is structural, not size-based — there is no entry-count threshold. Every nested element emits as a section with a quoted dotted-path header (["config.server"]), scalars as key = value lines beneath it.

Array of tables

[[users]] repeated on the TOML side produces an array of maps on import (TOML → CX yields map / array values, not elements). CX → TOML emits [["path.to.name"]] — the quoted-dotted-path array-of-tables header — for any sibling group of identically-named child elements, preserving order; a one-of-a-kind child emits a plain quoted section header, never a dotted key.

Processing instructions and comments

XML processing instructions (<?xml-stylesheet …?>) project to CX directive elements ([?xml-stylesheet …]). XML comments (<!-- … -->) project to CX comments ([; … ]). Both round-trip losslessly in the lossless canonical form; the strict canonicalizer strips comments per canonical-strict.

xml:space round-trip

xml:space=preserve survives XML round-trip identically — as an inert pass-through attribute. CX gives it no engine semantics: quoted body text is verbatim anyway (see xml-space), so there is nothing for the attribute to switch. It rides along for XML consumers that honor it.

DOCTYPE and DTD

CX does not have a DTD layer. XML input with a DOCTYPE declaration is accepted; the declaration is captured as a DoctypeDecl prolog node on the document (<!DOCTYPE html> imports as [!DOCTYPE html] ahead of the root element). DTD internal-subset content (<!ELEMENT>, <!ATTLIST>, <!ENTITY>) is carried verbatim inside that node and is not used for validation — schemas are first-class CX (.cxs files, see schema).

GFM tables

A GFM pipe table in Markdown input is not decomposed into [tr] / [th] / [td] structure — the table's source lines are carried as raw text inside a [table] element, and re-emit reproduces them byte-for-byte.

In the other direction, a CX [table[…]] block (see tables) emits as a real GFM pipe table — header row from the declared column names, then one row per data row — per spec/03-approved/core/conversions.md §7:

          [$cx:to-format [$cx:parse "[doc [p 'Two people:'] [table [table[name age::int]]
  Ada 35
  Grace 36
]]"] "md"]
        

          $ cx prog.cx
'Two people:\n\n| name | age |\n| --- | --- |\n| Ada | 35 |\n| Grace | 36 |'
        

Fenced code with language

Fenced code blocks ( lang ... ) project to a [code] element with a bare lang attribute and the code carried verbatim as raw text — [code lang=v [#println(1)#]]. There is no [pre] wrapper. The language identifier round-trips.

Frontmatter

YAML frontmatter (between --- markers at top of file) projects to attributes on the [doc] root element. Values stay strings — a frontmatter date: is not auto-typed into a CX date.

          [$cx:from-format "---\ntitle: My Post\ndate: 2026-05-22\n---\n\nHello, world." "md"]
        

          $ cx prog.cx
[doc title='My Post' date='2026-05-22' [p 'Hello, world.']]
        

Footnotes

GFM footnote syntax (text[^1] … [^1]: ref) is not implemented — there are no [fn-ref] / [fn-def] elements. Footnote markers are treated as ordinary inline text by the prose parser and do not round-trip as footnotes. Keep footnotes out of Markdown that must survive a CX round-trip.

Math blocks

Math syntax ($inline$, $$display$$) is not implemented — there is no [math] element. Dollar-sign math is treated as ordinary inline text and is not protected from the prose parser's emphasis and pairing rules. Keep LaTeX math out of Markdown that must survive a CX round-trip.

Header row

The first row is always the header — its cells become the column names of the imported [table[…]] block. There is no header-detection heuristic and no flag to declare the header absent; headerless data needs a header row added before import.

Type inference

Per-column type inference scans the whole column: all values match int → ::int; all match int or float → ::float; all bool → ::bool; all date or datetime → ::date / ::datetime; otherwise the column stays string (the untyped default). One odd value anywhere in the column is enough to keep it string — inference never truncates its scan.

Quoting and escaping

RFC 4180 rules: fields containing the delimiter, double quote, or newline are wrapped in double quotes; internal double quotes are escaped as "". Output canonicalizes to RFC 4180 regardless of input quoting style. Lone CR / LF outside quotes are treated as row terminators; embedded CRLF inside a quoted field is preserved verbatim.

CSV → CX → CSV is byte-identical for RFC-4180-conformant input (quoted fields and escaped quotes included). The emit direction is defined only for table-shaped documents: a CX document that is not a single flattenable table refuses with a named emit_delimited error rather than guessing a tabular shape.

          [$cx:to-format [$cx:parse "[table [table[id::int name email active::bool]]
  1 Ada ada@example.com true
  2 Grace grace@example.com false
]"] "csv"]
        

          $ cx prog.cx
'id,name,email,active\r\n1,Ada,ada@example.com,true\r\n2,Grace,grace@example.com,false\r\n'