yaml-domain-reference

name	yaml-domain-reference
description	YAML 1.2.2 spec knowledge as noyalib implements it — scalar resolution (resolve_plain_ext table), documents/streams/directives (§6.8, §9.1.2), block vs flow, block-scalar chomping (|/>/-/+), line breaks (§5.4 LF/CR/CRLF), anchors/aliases/merge keys with DoS budgets (max_alias_expansions, alias_anchor_ratio, max_merge_keys), tags (!!str/!!int/!!bool/!!null/!!binary → RFC 4648), YAML 1.1 vs 1.2 flags (legacy_booleans/octal/sexagesimal), the Norway problem, MergeKeyPolicy Auto/AsOrdinary/Error, and official-suite conformance arithmetic. Load when reasoning about YAML semantics, plain-scalar coercion, or spec-conformance work. Use for "explain merge keys / anchors / chomping / tags", "how do I resolve a plain scalar", "why does `no` parse as false", "does noyalib accept `nan` / `.inf` / octal `0o7`", "how many cases does the official YAML suite cover".
date	"2026-07-08T00:00:00.000Z"

YAML domain reference

Reference material (full resolve_plain_ext table, directive regression case list, block-scalar chomping worked-example matrix, official-suite integration walkthrough, YAML 1.1 vs 1.2 long-form flag matrix): see reference.md in this directory. Load when the terse summaries below are insufficient — spec-conformance work, tracing a case ID back to its rule, or verifying chomping edge cases.

Purpose. Domain-theory pack — the YAML 1.2.2 subset noyalib implements, plus the gotchas that hit real code.

When NOT to use. Parser/CST internals → noyalib-architecture-contract. Config flags in depth → noyalib-config-and-flags. Historical incidents → noyalib-failure-archaeology.

Ground truth files (re-read if you doubt any claim): GLOSSARY.md; doc/adr/0002-yaml-1.2-default.md; crates/noyalib/src/streaming.rs (resolve_plain_ext at L1620 is the scalar table); crates/noyalib/src/parser/scanner.rs (§5.4, §6.8, §9.1.2 rules cited inline); crates/noyalib/src/de/config.rs (every flag + default); crates/noyalib/tests/official_suite.rs + crates/noyalib/tests/yaml_compliance_report.rs (conformance arithmetic).

Provenance re-verify (one-liners):

grep -n '"\.nan"\|"\.inf"' crates/noyalib/src/streaming.rs
grep -n 'yaml_version: YamlVersion::V1_2' crates/noyalib/src/de/config.rs
grep -n 'max_alias_expansions:\|alias_anchor_ratio:\|max_merge_keys:' crates/noyalib/src/de/config.rs
grep -n '§5\.4\|§6\.8\|§9\.1\.2' crates/noyalib/src/parser/scanner.rs
grep -n 'SKIP_LIST' crates/noyalib/tests/official_suite.rs

---

1. Documents and streams

A YAML stream is zero or more documents, bounded by optional --- (start) and ... (end) markers. The first --- is optional; markers become mandatory between documents once directives, !!binary-tag context, or a preceding ... appear.

Directives are %-prefixed head lines: %YAML 1.2 sets version, %TAG !x! tag:example.com,2026: binds a tag-shorthand prefix. Only one %YAML per document (§6.8.1).

noyalib's strict rules (scanner.rs, § cited inline):

• §6.8: directive must be followed by explicit ---. Pending directive at stream end → error.
• §6.8 / §9.1.2: directive must not appear after content without intervening ....
• ADR-0002: %YAML 1.1 is recorded but not honoured — no auto-flip of legacy_* flags. Silently honouring it would reintroduce the Norway problem, which 1.2 was created to fix.

Regression case IDs (9MMA, B63P, RHX7, EB22, 9HCY, MUS6:1, ZYU8): see reference.md §R2.

---

2. Block vs flow, indentation, column tracking

Block style is the indentation-driven form:

db:
  host: localhost
  port: 5432

Flow style is the JSON-shaped inline form: db: {host: localhost, port: 5432}. YAML mixes freely — flow can nest inside block and vice versa.

Indentation is structure, not decoration: a mapping value at column N+2 is a child of a key at column N. This is why column tracking is load-bearing — every byte offset must map to the correct visual column, or nesting silently mis-parses.

Two column-desync incidents shaped this code (see noyalib-failure-archaeology for the full stories):

• BOM incident — UTF-8 BOM is three bytes, zero visual columns. Fix: advance_by(3) over the BOM without touching col (scanner.rs L1150–L1181).
• Lone-CR incident — classic-Mac \r-only breaks left column state stale. Fix (v0.0.14): recognise LF, CR, CRLF per §5.4 (see §5 below).

---

3. Scalars and block-scalar chomping

Five scalar styles:

• Plain — no quotes, resolved by the plain-scalar table (§4): port: 8080.
• Single-quoted — 'literal ''with'' apostrophes'. Only '' escape.
• Double-quoted — full backslash-escape alphabet plus \uXXXX (paired for surrogates).
• Literal block (|) — every newline byte preserved.
• Folded block (>) — non-empty lines joined with a space; blank lines preserved as paragraph breaks.

Chomping on block scalars (stacked as |-, >+, etc.): - = strip all trailing newlines; (none) = clip to one; + = keep every trailing newline / blank line.

noyalib gotcha (v0.0.14 fix). For keep-chomped (|+ / >+) block scalars, Document::span_at now includes the kept trailing blank lines in the returned span. Earlier releases truncated at the last non-blank byte — byte-faithful for the value but not for the span, breaking editor diagnostics.

Worked-example matrix (six header combinations with literal byte-level output including folding rules): see reference.md §R3.

---

4. The plain-scalar resolution table (as implemented)

Every plain scalar walks resolve_plain_ext (streaming.rs:1620). ~17 rows covering five null forms, canonical + non-strict + legacy booleans, 12 inf/nan forms, integer variants (decimal, 0x, 0o, bare-0 octal, u64 under lossless_u64), sexagesimal, f64 fallback, then string.

Precedence: null → bool → hard-coded inf/nan → legacy booleans → integer parse → sexagesimal → f64 fallback → string.

Full row-by-row table (verbatim source order): see reference.md §R1.

The Norway problem. YAML 1.1 boolean lexicon includes yes/no/on/off; country: NO (Norway's ISO 3166) was silently coerced to false for a decade in Ruby/pyyaml. YAML 1.2 narrowed the lexicon to true/false only. noyalib defaults to 1.2; legacy_booleans opt-in reintroduces the hazard.

The bare-nan gotcha. Nothing in the match table lists bare nan — but the f64 fallback (s.parse::<f64>()) accepts "nan", "inf", "+inf", "-inf" case-insensitively (Rust stdlib). So bare nan resolves to NaN even under strict 1.2. This bit mapping keys: {nan: 1, nan: 2} collided because both stringified to the same NaN bucket. The distinct-typed KeyCollision guard (§8) catches similar collisions but the f64 fallback route was the surprise.

Schema-strict mode. no_schema = true short-circuits the table — every plain scalar surfaces as Scalar::Str(Cow::Borrowed(s)).

---

5. Line breaks (§5.4)

Per §5.4 a line break is LF (\n), CR (\r), or CRLF (\r\n). All three valid; parser normalises on input. CRLF counts as one break (scanner.rs L554). Lone-CR (classic-Mac) was added v0.0.14 (scanner.rs L1769).

Gotcha. Downstream code assuming \n-only (naive split('\n')) mis-counts columns on CR-only input. External consumers of Document::source() should re-normalise if they care.

---

6. Anchors, aliases, merge keys — and DoS budgets

Anchor (&name) labels a node. Alias (*name) references it inside the same document. Per §7.1 each document has its own namespace; noyalib clears the anchor table on DocumentEnd.

Merge key (<<) — when the value is a mapping or a sequence of mappings, merged keys are inherited unless overridden locally.

Billion-laughs DoS. Nested aliases (c: &c [*b, *b, *b, ...] where b references a etc.) multiply expanded size by 9 per level; ten levels ≈ 3.5 billion terminal nodes from ~50 lines. Libyaml has historically crashed on such inputs.

noyalib's budgets (ParserConfig, defaults from de/config.rs):

Knob	Default	Strict	Trip
max_alias_expansions	1 024	100	Error::RepetitionLimitExceeded (not BudgetBreach)
max_document_length	64 MB	1 MB	Error::Parse (also caps alias_bytes post-expansion)
max_total_scalar_bytes	64 MB	1 MB	BudgetBreach::MaxTotalScalarBytes
max_merge_keys	10 000	1 000	BudgetBreach::MaxMergeKeys
alias_anchor_ratio	Some(10.0)	Some(5.0)	BudgetBreach::AliasAnchorRatio (aliases > ratio × anchors)
max_events	1 000 000	100 000	BudgetBreach::MaxEvents
max_nodes	250 000	25 000	BudgetBreach::MaxNodes
max_depth	128	64	Error::RecursionLimitExceeded (not BudgetBreach)

Only six BudgetBreach variants exist in error.rs: MaxEvents, MaxNodes, MaxTotalScalarBytes, MaxDocuments, MaxMergeKeys, AliasAnchorRatio. max_alias_expansions and max_depth surface as top-level Error::Repetition- / Error::RecursionLimitExceeded; max_mapping_keys and max_sequence_length surface as Error::Serialize(...) (wart documented in noyalib-architecture-contract §5.1).

alias_anchor_ratio is the early-warning signal — real files rarely exceed 2–3 aliases per anchor; above 10 (5 in strict) is bomb-shaped. Set to None to disable.

MergeKeyPolicy (de/config.rs:973, note real variants):

• Auto (default) — YAML 1.2 semantics: << triggers automatic merge of the value into the enclosing mapping.
• AsOrdinary — treat << as a plain string key. The mapping keeps a literal << entry. Useful for round-tripping files where << is a data key, not a merge instruction.
• Error — refuse any document containing << with Error::Custom. For schema-strict pipelines.

Note: GLOSSARY.md drift — it lists {Auto, Disabled, Strict}. The source of truth is de/config.rs — {Auto, AsOrdinary, Error}. Trust the code.

---

7. Tags

Explicit type annotations. Three families:

• Core-schema tags — !!str, !!int, !!float, !!bool, !!null, !!seq, !!map, !!binary. noyalib never strips these — they carry semantics (!!str 42 forces string).
• Custom tags — !shopping, !myapp/config. Carried through as Value::Tagged; a TagRegistry can transform them inline on the streaming path.
• Verbatim tags — !<tag:yaml.org,2002:str> (rare).

Shorthand. !!x expands to tag:yaml.org,2002:x (§6.8.2). Custom prefixes come from %TAG !x! tag:example.com,2026:.

!!binary — RFC 4648 base64 (§10.4). Decoded on the streaming path (streaming.rs L1095–L1115); failure → Error::Deserialize("!!binary: {why}"). Deserialising into a String target defaults to tag-mismatch error; set ignore_binary_tag_for_string = true for pyyaml-style advisory behaviour (returns the literal base64 source).

---

8. Keys — and the KeyCollision guard

YAML permits any node type as a mapping key, including complex keys (? key\n: value). noyalib exposes two mapping types:

• Mapping — string-keyed (IndexMap<String, Value>). Default, JSON-compatible.
• MappingAny — Value-keyed. Use when non-string keys matter for fidelity.

When YAML produces a non-string key (1, true, null) and the target is Mapping, the key is stringified on entry. This is where the distinct-typed KeyCollision guard lives (error.rs:509, Error::KeyCollision(String)). Given 1: one and "1": two, both stringify to "1"; silently dropping one is data loss, so noyalib rejects with KeyCollision("1") at parse time.

Streaming path bypass (de.rs:405-421): serde asks the streaming deserializer for String keys, stringifying typed scalars before ValueVisitor::visit_map can distinguish 1 from "1". The Value target therefore routes through the AST loader (which owns the collision check and DoS budgets).

DuplicateKeyPolicy (unrelated axis — same string key twice): First (keep first) / Last (default, YAML 1.2) / Error (reject).

---

9. YAML 1.1 vs 1.2 — the flags that matter

Per ADR-0002, noyalib defaults to YAML 1.2 strict semantics. Three 1.1 legacy behaviours are opt-in on ParserConfig:

• legacy_booleans — off: yes/no/on/off → string; on: → bool (Norway problem).
• legacy_octal_numbers — off: 0644 → int 644; on: → 420.
• legacy_sexagesimal — off: 60:00 → string; on: → int 3600.

ParserConfig::version(YamlVersion::V1_1) flips all three as a bundle; fine-grained flags remain callable individually.

• strict_booleans — narrows 1.2 further: only true/false (lowercase) are boolean; True/TRUE become strings. Off by default.
• no_schema — every plain scalar surfaces as string; table (§4) bypassed entirely.

Long-form matrix with hazard column, precedence ordering, and flag-interaction notes: see reference.md §R5.

---

10. Official YAML Test Suite

The yaml/yaml-test-suite corpus. Each case is a wrapper with yaml:, json:, fail:, tags:. IDs are four-character codes (9MMA, RHX7, ZYU8).

• tests/yaml-test-suite/ — vendored corpus.
• tests/official_suite.rs — regression-net. Scores pass / (total − skip), asserts compliance >= 94.0.
• tests/yaml_compliance_report.rs — the gap report. No assertions; writes target/yaml-compliance-report.md. Hard floor total >= 350 guards against vacuous 0/0.

Ground-truth reminders (assert every time you cite them):

official_suite.rs::SKIP_LIST     = &[]        # zero entries
yaml_compliance_report.rs::SKIP  = &[]        # zero entries
compliance floor                 = 94.0%      # assertion
total-cases floor                = 350        # regression guard

Drift alert. Top-level and crate READMEs claim "100% strict compliance — 387/387 attempted, 0 failures, 19 skipped". Test files carry empty SKIP_LIST and 94% floor. Report what the TEST FILES say (skip = 0 today) — README numbers are aspirational and may lag.

Wrapper-marker table, six report classifications, full walkthrough: see reference.md §R4.

---

Cross-references

• Extended tables (full resolve_plain_ext, directive cases, chomping matrix, official-suite walkthrough, 1.1/1.2 long matrix): reference.md here.
• Flags in depth (ParserConfig, presets): noyalib-config-and-flags.
• Parser/CST internals (green tree, event stream, streaming vs loader): noyalib-architecture-contract.
• Historical fixes (BOM, lone-CR, span_at): noyalib-failure-archaeology.
• Change control (spec-conformance PRs): noyalib-change-control.