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, attribute ordering within their declared category.

• **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.

              [# Source — author-friendly form (loose layout, mixed quoting) #]
           [user
             email="ada@example.com"
             id=42
             active=true]

           [# cx fmt output — presentation normalized, comments preserved #]
           [user email='ada@example.com' id=42 active=true]
            

Strict canonical (cx canonical / cx hash)

Strict canonical (`cx canonical`) reduces input to **data-equivalence form**. Strips comments, expands anchors and aliases, resolves merges, removes presentation-only directives, normalizes date offsets to UTC. Two CX documents have identical strict canonical bytes if and only if they encode the same data.

• **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, attribute order, or anchor names still hash to the same bytes.

              [# Source #]
           [user
             [# regrettably noisy comment #]
             email='ada@example.com'
             id=42
             active=true]

           [# cx canonical output — comments stripped, attributes sorted #]
           [user active=true email='ada@example.com' id=42]
            

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 concatenate 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/conversions.md §2.2.1`](../../spec/conversions.md)): `$children` is an ordered array of runs, so mixed content survives exactly.

              [para 'The function ' [code 'parse'] ' returns a value.']
            

              { "$tag": "para", "$children": ["The function ", {"$tag": "code", "$children": ["parse"]}, " returns a value."] }
            

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/conversions.md §0.2`](../../spec/conversions.md). 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: `[user]` (no email attribute) projects to `{"user": {}}`; `[user email=null]` projects to `{"user": {"email": null}}`. JSON → CX reads absent keys as absent attributes (NOT as null).

YAML tags (!!str, !!int, !!binary)

YAML tags survive round-trip: `!!str 42` parses to CX `:string "42"`; `!!int "42"` parses to CX `:int 42`; `!!binary base64bytes` parses to CX `:bytes`. The CX emitter writes tags only when type inference would be ambiguous (e.g. emitting a numeric-looking string requires `!!str` to avoid being read back as a number).

Multiline scalars (| and >)

Literal block style (`|`) preserves newlines verbatim; folded block style (`>`) collapses single newlines to spaces but preserves blank lines. CX triple-quoted strings round-trip through `|` by default (preserves the as-authored shape). The `>` form is used on emit when the string content has no internal blank lines and the line length would exceed 80 columns.

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/conversions.md §5.1`](../../spec/conversions.md)). In the other direction, CX anchors and merges are dropped by the default YAML emit and carried by the lossless envelope's `$anchor` / `$merge` keys, which the importer reconstructs — so a `--lossless` round-trip preserves them.

Inline tables vs dotted keys

TOML allows two shapes for nested scalars: inline tables (`server = { host = "x", tls = true }`) and dotted keys (`server.host = "x"`, `server.tls = true`). Both project to the same CX nested-element shape. Canonical CX → TOML output uses the inline form for tables with ≤ 4 entries and the section-header form otherwise.

Array of tables

`[[users]]` repeated produces an array. CX preserves order and emits as repeated child elements with the same name. CX → TOML emits `[[name]]` for any sibling group of N≥2 identically-named child elements; one-of-a-kind children use the dotted-key form.

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. Same for `cx:lang` (round-trips as `xml:lang` if the input used that alias; preserves the chosen form). See xml-space and locale.

DOCTYPE and DTD

CX does not have a DTD layer. XML input with a DOCTYPE declaration is accepted; the DOCTYPE name is captured as a `[?cx doctype=…]` directive (see doctype). DTD content (`<!ELEMENT>`, `<!ATTLIST>`, `<!ENTITY>`) is parsed but not used for validation — schemas are first-class CX (`.cxs` files, see schema). External entity references are gated per include-capabilities.

GFM tables

GitHub-Flavored Markdown tables project to CX `[table]` elements with `[tr]` / `[th]` / `[td]` children. Column alignment markers (`:---`, `:---:`, `---:`) project to `align=left`/`center`/`right` attributes on the `[th]` cells.

              | Name | Age |
           |:-----|----:|
           | Ada  |  35 |
           | Linus | 24 |
            

              [table
           [tr [th align=left 'Name'] [th align=right 'Age']]
           [tr [td 'Ada']   [td 35]]
           [tr [td 'Linus'] [td 24]]]
            

Fenced code with language

Fenced code blocks (` ```lang ... ``` `) project to `[pre [code lang=lang ...]]`. The language identifier is preserved; canonical emit uses single-quoted attribute form for the language tag.

Frontmatter

YAML frontmatter (between `---` markers at top of file) projects to a `[frontmatter]` element with attributes from the YAML mapping. Round-trip preserves the frontmatter shape verbatim.

              ---
           title: My Post
           date: 2026-05-22
           ---

           # Body
            

              [frontmatter title='My Post' date=2026-05-22]
           [h1 'Body']
            

Footnotes

GFM footnotes (`text[^1]` … `[^1]: ref`) project to inline `[fn-ref id=1]` elements with corresponding `[fn-def id=1 ...]` at the document end. Round-trip preserves the labels.

Math blocks (KaTeX/MathJax)

`$inline$` and `$$display$$` math project to `[math]` elements with `display=true|false`. The body is the LaTeX source preserved verbatim (no LaTeX parsing). Renderers (KaTeX, MathJax, native renderers) consume the `[math]` element directly.

Header detection

The reader inspects the first row: if all values are non-numeric, non-boolean, non-date strings AND the second row contains at least one typeable value, the first row is the header. The default heuristic can be overridden: `cx convert in.csv --header=auto|present|absent --to cx`.

When `header=absent`, columns are named `col1`, `col2`, …; an explicit schema (`--schema cols.cxs`) can name them.

Type inference

Per-column type inference scans the first 1000 rows (or all rows if fewer): all values match `:int` → `:int`; all match `:int` or `:float` → `:float`; all bool → `:bool`; all date or datetime → `:date` / `:datetime`; otherwise `:string`. An explicit schema overrides inference.

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. CSV with non-standard quoting (single quotes, no escape) is accepted on input via `--delimiter-profile=relaxed` and emits as RFC 4180.