A zero-indent literal or folded block scalar sits at column 0, where the directive scan runs, so a content line beginning with `%` (`%!PS-Adobe-2.0`) was misread as a directive and rejected as unsupported. The directive scan now runs only outside a block scalar, so a leading `%` in block scalar content is literal text. A real `%YAML` or `%TAG` directive still parses, and a stray `%` in other content is still rejected rather than silently accepted, so the should-error behaviour is unchanged. This is groundwork for yaml-test-suite W4TN, which additionally needs a block scalar to be terminated by `...` and per-document directives across a multi- document stream, so conformance counts are unchanged this step.
54 KiB
Changelog
All notable changes to PureYAML are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
Added
- The tagged validator now enforces mapping-key uniqueness, the invariant the coverage manifest
already claimed for
Tagged.MappingandTagged.Nodebut no check enforced.Tagged.Mappingkeeps every parsed pair, so a duplicate key survives into the tree;Tagged.BuiltinCheck.mappingKeysAreUnique(aCheck<Mapping, Node>on the one framework) reports each duplicate at its key path, exactly as the plain model does. It ships failing, near-miss, and nested fixtures, and the tagged validator's two built-in checks are pinned by description. TheModel.Valuecoverage reason is corrected to note that merges and aliases are resolved at parse time, so they are not a validation-phase invariant: everyvalidatedmanifest entry now names an invariant a check actually enforces. - A finding-coverage meta-test makes validation coverage a tested law, now across both validating layers: every default check, in the model validator and in the tagged validator, must ship a failing fixture and a near-miss (just-valid) fixture. The meta-test asserts the fixture set covers exactly each layer's default checks, naming any default check without fixtures or any fixture for a check that no longer ships. Each check is exercised in isolation, in a validator holding only it, so a fixture cannot lean on a sibling check to fail and the law stays precise as a layer grows past one check. A planted orphan fixture was confirmed to fail both the set-equality and the isolation tests.
- Type-directed validation, the core of the validation-rules idiom: a
Check<Subject, Document>carries a positive description, awhenpredicate, and a Bool or multi-error check, and fires only on values of itsSubjecttype wherever they occur in the tree.AnyCheckerases the subject type and dispatches by runtime type, guarding against an optional or a wrong type matching. The validator gains acheckslist and avalidating(_:)overload for checks, and the traversal offers each node the values it may specialise on (the value, and for a mapping the mapping and its keys).BuiltinCheck.mappingKeysAreUniqueis the type-directed counterpart of the legacy rule, firing onModel.Mappingdirectly. The machinery has its own negative tests (wrong type, optional, and false predicate yield nothing; the same type twice yields two errors) and the builtin ships a failing and a near-miss test. - The validator is now configurable by rule identity, per the validation-rules idiom:
withoutValidating(_ description:)removes a rule by its description (the removal identity, so descriptions must be unique and stable), andvalidationDescriptionslists the active rules in application order. A configuration-pin test asserts the exact descriptions of the blank and default validators, so adding, removing, or rewording a rule is a deliberate change. - A validation-coverage gate (
scripts/check-validation-coverage.sh, wired intoscripts/check-all.shand CI) enforcing the validation-rules discipline that every public type is either validated or excluded. It enumerates the public surface from the compiler symbol graph (the authoritative source, not a grep heuristic) and fails the build, by name, if any public type is missing fromscripts/validation-coverage.tsvor any manifest entry is no longer public. All 58 public types are classified: the value models carrying a runtime invariant (mapping-key uniqueness) arevalidated, and the caseless namespaces, closed sum types, data-transfer values, error types, and engine/machinery areexcludedwith a one-line reason each. This is the first phase of adopting the OpenAPIKit-style validation idiom; the type-directedValidation<Subject>framework that backs thevalidatedentries follows. - An opt-in conformance harness against the official YAML test-suite, the canonical
YAML 1.2 corpus (
Tests/YAMLTestSuiteConformanceTests.swift,scripts/fetch-yaml-test-suite.sh). Gated behindPUREYAML_RUN_YAML_TEST_SUITE=1and a separate fetch, so the data is never vendored. It reports two levels: parse-level (a should-parse case must parse; a should-error case must be rejected; failures histogrammed by cause) and the stricter, honest value-level, comparing the parsed tree to each case'sin.json. Value-level baseline: 130/170 (76.5%) of comparable single-document cases, exposing 40 documents that parse without error but to the wrong tree (e.g. double-quoted line folding, scalar resolution, block-scalar indentation) which parse-level cannot see. This turns "best YAML library" from an assertion into a tracked number.
Changed
- The validation framework is now a single value type across the whole package. The legacy
Ruleand itsContextare removed: a rule was exactly aCheck<Model.Value, Model.Value>(it fired on every node, switched on the value itself, and carried the root), so it was a second copy of the one check machinery (validation-rules.md, principle 10). The model validator now holds onlychecks, its default is the type-directedBuiltinCheck.mappingKeysAreUnique, andvalidating(_:)takes aCheck. Custom whole-tree rules are written asCheck<Model.Value, Model.Value>with the formercontext.rootnowcontext.document; behaviour is byte-identical (same issues, paths, and order), so the publicvalidate/collect/blanksurface is unchanged. - The tagged-node validator no longer carries its own copy of the validation machinery. The
type-directed
Check, its erasureAnyCheck, and itsSubjectContextare now generic over both the subject and the document (the validated tree's root type), so one framework serves both layers: the model tree validates with aModel.Valuedocument, the tagged tree with aTagged.Nodedocument.Tagged.Ruleand the tagged validationContextare removed; the tagged validator keeps only its own document type, its built-in check (Tagged.BuiltinCheck), and its traversal. This is the one-framework, no-per-layer-duplication discipline of the validation-rules idiom (principle 10); the tagged validator's public surface (validate,collect,blank,validating) is unchanged except thatvalidatingnow takes aCheck<Tagged.Node, Tagged.Node>instead of aTagged.Rule.
Fixed
-
A line beginning with
%inside a block scalar is now kept as literal content rather than being misread as a directive. A zero-indent literal or folded scalar sits at column 0, where the directive scan runs, so a content line such as%!PS-Adobe-2.0was rejected as an unsupported directive. The directive scan now runs only outside a block scalar; a real%YAML/%TAGdirective and the rejection of a stray%in other content are unchanged. This is groundwork for yaml-test-suite W4TN, which additionally needs block-scalar termination by...and per-document directives, so conformance counts are unchanged. -
A block sequence value carrying an inline property (
sequence: !!seqthen- entryat the key's column) is now correctly terminated by a sibling mapping key. Such a zero-indent sequence has its entries at the mapping key's own indentation, so a following key ends it. The untagged form already stopped at the sibling key, but the property-bearing form was routed through the generic node path, which read the sibling key as a mixed sequence-and-mapping entry and rejected the document. The zero-indent sequence is now handled before that path, with or without a property. Fixes yaml-test-suite 57H4; raises parse-level conformance to 313/333 (94.0%) and value-level to 206/206 (100.0%), with the should-error rate unchanged. -
Node properties that span their own indented lines above a further-indented node now attach to that node (
key: &anchorthen!!mapthena: b). An inline anchor with a tag on the next indented line, above a mapping indented deeper still, left the node introduced by another indent token, which the parser could not read and rejected as a missing node. The indented mapping value now descends through that deeper indent, carrying the accumulated properties to the node. Fixes yaml-test-suite BU8L; raises parse-level conformance to 312/333 (93.7%) and value-level to 205/205 (100.0%), with the should-error rate unchanged. -
A node property written on its own indented line above a zero-indent block sequence (
seq:then&anchorthen- aback at the key's column) now binds to that sequence. The grammar lets a block-in-block sequence sit at its parent's indentation while its property sits one level deeper, so the indent's matching dedent falls between the property and the entries. The parser had read the property as an empty anchored value and then rejected the entries as unexpected; it now consumes that dedent and attaches the property to the sequence. Fixes yaml-test-suite SKE5; raises parse-level conformance to 311/333 (93.4%) and value-level to 204/204 (100.0%), with the should-error rate unchanged. -
An alias node may now serve as an implicit mapping key (
*a : value). The scanner emits the implicit-key indicator before a scalar key followed by a:but did not for an alias, so the parser, which already accepts an alias node in key position, never entered the pair and rejected the alias as an unexpected token. The scanner now emits the same indicator before an alias that a:(after optional spaces) follows, in block context. A:written directly against the alias stays part of its name, since:is a valid anchor-name character. Fixes yaml-test-suite E76Z and 26DV; raises parse-level conformance to 310/333 (93.1%) and value-level to 203/203 (100.0%), with the should-error rate unchanged. -
A property written inline before a block mapping's first key (
&a key: value) now binds to that key rather than to the whole mapping. The YAML grammar requires a block collection's own properties to be followed by a line break, so a property on the first key's line belongs to the key, not the collection. The parser had attached it to the mapping, where an anchor registered only at the mapping's end, too late for an alias inside one of the mapping's values to resolve. A property on its own line above the key still binds to the mapping. Fixes yaml-test-suite 2SXE (anchor names include a trailing:, so&a:and&aare distinct anchors, already handled by the scanner) and HMQ5 (a key carrying both a tag and an anchor); raises parse-level conformance to 308/333 (92.5%) and value-level to 201/201 (100.0%), with the should-error rate unchanged. -
An anchor on an empty mapping value (
a: &anchor) now registers that value's implicit null node, so a later alias resolves to null instead of failing as an undefined alias. Two bugs compounded: the parser dispatched the anchor-only value position to a nested block mapping, absorbing the sibling key (b:) as the anchored node's child instead of emitting the empty anchored node; and the stream composer registered an anchor by its raw scalar text rather than the resolved node, so even a registered anchor on an empty scalar came back as""and a typed scalar (&a 42) came back as text. The value position now emits an empty anchored node when only a sibling mapping key follows, and an anchor registers the composed value. Fixes yaml-test-suite 6KGN and a latent typed-scalar anchor bug; raises parse-level conformance to 306/333 (91.9%) and value-level to 199/199 (100.0%), with the should-error rate unchanged. -
A
%YAMLdirective with a higher minor version than 1.2 is now accepted rather than rejected. The spec calls for processing a document with a higher minor version, with a warning, so%YAML 1.3is read as a YAML 1.x document instead of erroring. The version check now accepts any well-formed1.minorversion and rejects only a different major version (2.0) or a malformed one. Three tests that asserted%YAML 1.3was an error were corrected to use2.0. Raises yaml-test-suite parse-level conformance to 305/333 (91.6%), with the should-error rate unchanged. -
A plain scalar that is an inline block sequence item value (
: - b) now stops folding at a later block entry that returns to the sequence's own indent, so the dashes form the rest of the sequence rather than folding into the first item. A block entry only recorded its inline node's indent as a valid implicit level, not the dash's own indent, so a continuation could not tell a sibling entry from content, and? a/: - b/- - c/- dfolded into one scalar. The entry's indent is now recorded as a sibling level too (except under an explicit key, whose sequence key drives implicit indentation itself), while a block entry more indented than its container stays plain content. Brings yaml-test-suite value-level conformance to 197/197 (100.0%), with the parse and should-error rates unchanged. -
A leading blank line of a block scalar now keeps any whitespace past the content indentation as content, as a blank line within the scalar already did. The leading blank lines (those before the first content line) were only counted, so an otherwise-blank
␣\tline under a one-space content indent lost its tab, and a folded scalar that began with such a line dropped the leading tab. The leading blanks now record their whitespace and emit the surplus once the content indentation is known, so the tab survives. Raises yaml-test-suite value-level conformance to 196/197 (99.5%), with the parse and should-error rates unchanged. -
A flow mapping entry may now omit its
:value indicator, mapping its key to null:{ a }and{ a, b }are flow sets. The parser required a:after every flow mapping key and rejected these, and a multi-line key with no value ({ multi/line, a: b}) with it. A value now parses only when a:follows the key; otherwise the key maps to null. A test that asserted{ a, }was an error was corrected, since it is a valid set. Raises yaml-test-suite parse-level conformance to 304/333 (91.3%) and value-level to 195/197, with the should-error rate unchanged. -
A plain scalar key in a flow collection may now span lines. A flow key, unlike a block implicit key, is allowed to be multi-line, so
{ multi/line: v }is the keymulti line. The scalar continuation stopped at the:value indicator in every non-explicit case, dropping the second line, so the parser mis-split the entry. Folding across the:now also applies in flow, while a block implicit key still stops before such a:. Raises yaml-test-suite parse-level conformance to 301/333 (90.4%) and value-level to 193/195, with the should-error rate unchanged. -
An explicit key (
?) inside a flow collection is now parsed correctly. The flow?did not mark an explicit key, so the following scalar synthesized its own implicit key:{? foo : bar}came out as{{foo: bar}: null}rather than{foo: bar}, and[? foo : bar]likewise. The explicit-key state is now tracked per flow level on the flow context, so the key scalar is not turned into an implicit key, a:at that level is the pair's value indicator, a,ends the key, and a nested collection's:does not affect an outer key ({? {a: b} : c}). The key may also span lines, folding to one key, which restores the multi-line flow case[? foo\n bar : baz]. Raises yaml-test-suite value-level conformance to 192/194 (99.0%), with the parse and should-error rates unchanged. -
An explicit key (
? foo) whose plain scalar spans lines now folds a continuation line that ends at the value:.? foothenbar : bazis the keyfoo bar, not an error: the:is the key's value indicator, so the line stays key content and folds in, where before the scalar dropped it and the parser stalled. An implicit key is unchanged, since there a continuation line ending at:is a new mapping key and the scalar still stops before it. The block test-suite rates are unchanged (no comparable case isolates this), and the flow form needs separate explicit-key work, but the parser now folds block explicit keys correctly. -
An explicit block scalar indentation indicator (
|2,>1) on an inline mapping value now measures from the mapping's indentation. A value like- aaa: |2has the inline mapping as its parent, but that mapping sits at an implicit indentation off the main stack, so the indicator was added to the stack's level (0) instead of the mapping's (2), making the content indentation too small and pulling the next key into the scalar. The deepest applicable implicit indentation is now folded in for an inline mapping value, while a direct sequence item (- |1) keeps the sequence's own level. Raises yaml-test-suite value-level conformance to 191/194 (98.5%), with the parse and should-error rates unchanged. -
Compact nested block sequences (
- - x) now separate their outer items correctly. Such a sequence carries no indent/dedent tokens, only block entries at their columns, but the sibling-entry loop collected every following block entry regardless of column, so- - xthen- - ybecame one outer item holding both rather than two. A sequence now collects siblings only at its own column, so an entry at a smaller column ends it and belongs to the enclosing sequence. Raises yaml-test-suite value-level conformance to 190/194 (97.9%), with the parse and should-error rates unchanged. -
A block scalar whose only lines are blank now carries those blank lines through chomping at stream end. Such a scalar never establishes a content indentation, so its blank lines stayed buffered and were dropped, making
keep: |+over a blank line resolve to the empty string instead of a line break. The buffered blanks are now flushed as content at stream end, so keep (|+/>+) preserves them while clip and strip trim them:keep: |+over one blank line is"\n". Raises yaml-test-suite value-level conformance to 189/194 (97.4%), with the parse and should-error rates unchanged. -
A scalar carrying an explicit non-core tag now stays a string instead of being implicitly resolved. A node with a tag is not subject to plain-scalar resolution, so a local tag (
!foo), the non-specific!, or an unknown verbatim URI fixes the node as the string of its content:! 12is the string12, not the integer, and!Thing falseis the stringfalse, not a boolean. Recognized core tags (!!int,!!bool, ...) and untagged scalars still resolve. Two compatibility tests that asserted the previous behavior were corrected. Raises yaml-test-suite value-level conformance to 188/194 (96.9%), with the parse and should-error rates unchanged. -
A tab before a
#now ends a plain scalar and begins a trailing comment, as a space already did, since a comment opens after any white space.c: d\t#Xis the valuedwith a comment, not the literald\t#X. A tab inside a plain scalar with no#after it stays part of the value, and a#glued to content with no white space is still content. Raises yaml-test-suite value-level conformance to 187/194 (96.4%), with the parse and should-error rates unchanged. -
A blank line next to a more-indented line in a folded block scalar (
>) now keeps both line breaks. Between two non-more-indented lines a blank run of N folds to N breaks (the fold is absorbed into the first), but next to a more-indented line nothing folds, so the absorbed break survives and the run yields N+1 breaks. The folder counted N breaks in every case, collapsing the paragraph spacing around indented blocks. Raises yaml-test-suite value-level conformance to 186/194 (95.9%), with the parse and should-error rates unchanged. -
Plain scalar line folding now strips tabs, not only spaces, around continuation lines. A tab is not indentation, so a continuation line's leading tab (
\t3rd) is folding white space and folds away rather than entering the value, and a line of only white space that holds a tab (␣␣\t) is an empty line that folds to a line break, not an extra space. Raises yaml-test-suite value-level conformance to 183/194 (94.3%), with the parse and should-error rates unchanged. -
A tab in block scalar content past the block's indentation is now kept verbatim instead of being re-expanded to spaces. A block scalar is indented with spaces only, so a line like
␣\ttextunder a one-space indent strips the space and keeps the tab, yielding\ttext; the scanner measured the leading whitespace as a tab-expanded width and rebuilt the surplus as spaces, turning the tab into three spaces. The surplus is now reconstructed from the actual leading characters, so a tab stays a tab while surplus spaces stay spaces. Raises yaml-test-suite value-level conformance to 180/194 (92.8%), with the parse and should-error rates unchanged. -
Mid-line separation white space between tokens now includes tabs, not only spaces, completing the tab-as-separation handling. An indicator followed by a tab no longer leaks the tab into the next node:
?\tkeyis the keykey, not\tkey, and a run of tabs between a:and its value (a:\t\tb) is separation. This closes the post-indicator tab leak noted when the indicator boundary itself was fixed. Tabs as indentation are still handled separately by the line-start scan, and the yaml-test-suite rates are unchanged (no comparable case isolates this), but the parser now matches the spec on tab separation. -
A tab now follows the
:mapping-value indicator the way a space does, in both block and flow context, since a tab is separation white space in YAML.foo:\tbaris the mapping{foo: bar}rather than the plain scalarfoo:\tbar. A:with no following white space at all (foo:bar) stays plain scalar content. Raises yaml-test-suite parse-level conformance to 300/333 (90.1%), with the should-error rejection rate unchanged. -
A tab now ends a leading indicator the way a space does, since a tab is separation white space in YAML (only indentation forbids a tab). A document marker, block entry, or explicit key followed by a tab (
---\tscalar,-\titem,?\tkey) is recognized as the indicator rather than folded into a plain scalar. Raises yaml-test-suite value-level conformance to 175/192 (91.1%), with the parse and should-error rates unchanged. -
A flow sequence element that begins with
:is now parsed as a single-pair mapping with an empty (null) key, e.g.[ : value ]is[{null: value}]. The parser raised "expected a YAML node" for the leading:; it now emits the empty-key mapping, mirroring the way[ a: b ](a scalar key followed by:) already becomes a mapping element. Plain elements and scalar-key mapping elements are unchanged. Raises yaml-test-suite parse-level conformance to 298/333 (89.5%), with the should-error rejection rate unchanged. -
A flow mapping entry may now begin with its
:indicator, giving an empty (null) key, e.g.{ : value }or{ a: b, : c }, or carry only properties before the:, e.g.{ !!str : value }. The parser required a node before every flow mapping:and raised "expected a YAML node"; it now emits a null key in that position, the same way an empty value after the:is already handled. The allowance is local to flow mapping key position, so an entry with no:at all ({ a, }) stays an error. Raises yaml-test-suite parse-level conformance to 297/333 (89.2%) and value-level to 174/192, with the should-error rejection rate unchanged. -
A flow collection followed by a
:indicator on the same line is now parsed as an implicit block mapping key, e.g.[a, b]: valueor{a: 1}: value. The scanner looks ahead from the flow opener to its matching close (skipping quoted scalars so their brackets and colons do not miscount) and, when a same-line:follows, emits the implicit-key marker a scalar key would get, so the flow node is parsed as the key through the ordinary mapping path. A block implicit key must lie on one line, so a flow collection spanning a line break before its:([23 / ]: 42) stays an error, and a flow node that no:follows, or that is a mapping value, is unaffected. Raises yaml-test-suite parse-level conformance to 294/333 (88.3%) with no change to the should-error rejection rate. -
A block scalar that is the document's own root node now folds or keeps content that begins at column 0, e.g.
>or--- |followed by unindented lines. The document node's indentation is -1, so its content at column 0 is still more indented than its parent, but the scanner read the base level as 0 and required content to be strictly deeper, leaving the lines to be mis-scanned as a stray scalar after the document. The scanner now recognizes a root block scalar (one with no enclosing mapping value, explicit key, block-entry indent, or flow context on its header line) and establishes its content indentation at column 0. A non-root block scalar keeps its parent's indent as the floor, so an under-indented sequence item or mapping value is still rejected. Raises yaml-test-suite parse-level conformance to 291/333 (87.4%) and value-level to 173/191 (90.6%). -
Content after a document-end marker (
...) now begins a new bare document. A stream such as--- scalar / ... / key: valueora / ... / bis two documents, but the scanner rejected the content and the parser expected the document to end at the marker. The scanner now reopens the stream after..., and the document loop returns at a...so the outer loop parses the next document. A trailing...with nothing after it still leaves a single document. Lifts official test-suite parse-level conformance from 288/333 (86.5%) to 289/333 (86.8%), with no regression. -
An anchor or tag with no node after it now denotes an empty node. A property always attaches to a node and an empty node is allowed, so
&anchoralone,key: &a, or a!!strwith nothing after it (x: !!stris the empty string,x: !!nullis null) is the property applied to a null node rather than a missing-node error. A real tagged or anchored value is unaffected. Lifts official test-suite parse-level conformance from 287/333 (86.2%) to 288/333 (86.5%) and value-level by one. -
An implicit null mapping key is now parsed. A
:that opens a line with no key before it (: value, a bare:, or a null key among other entries) is an entry with a null key, which the parser previously rejected as a missing node. The scanner synthesizes the empty key, tracking a pending explicit?key so that an explicit key's value indicator on the next line, including after a flow complex key (? {a: b}then: c), is not mistaken for a null key. Lifts official test-suite parse-level conformance from 283/333 (85.0%) to 287/333 (86.2%), with no regression. -
A directive after a document-end marker (
...) now begins the next document instead of being rejected. A multi-document stream where each document carries its own directives (%TAG .../--- doc/.../%TAG .../--- doc) is now accepted, since a directive following...opens the next document's directive section. A directive after document content within the same document is still rejected, and a directive after...still requires its own---. Lifts official test-suite parse-level conformance from 278/333 (83.5%) to 283/333 (85.0%), with no regression. -
A block sequence entry can no longer follow a flow collection that closed earlier on the same line (
- { y: z }- invalid,- [a] - b); the entry would begin a sequence inline after a complete node. The scanner now tracks a top-level flow close on the current line and rejects a block entry after it, while a nested block entry (- -, which has no preceding flow close), a flow collection on its own line, and nested flow collections are unaffected. Lifts official test-suite parse-level conformance from 276/333 (82.9%) to 277/333 (83.2%), with no regression. -
A mapping value's anchor or tag on the line below the key must now be indented past the key. A property at the key's own indentation is ambiguous with a sibling and is rejected, whether it is the only property (
seq:then&anchorin column 1) or a later one after an inline first (key: &xthen a!!tagin column 1). An inline property, a property indented under the key, and a block sequence at the key's indent (which carries no property) stay valid. Lifts official test-suite parse-level conformance from 275/333 (82.6%) to 278/333 (83.5%), with no regression. -
A
-immediately before a flow indicator is no longer treated as a scalar. In a flow collection a-that begins a plain scalar must be followed by a non-indicator character, so[-],[-, -], and{a: -}are now rejected. A dash followed by ordinary content is unaffected: negative numbers ([-1, -2]), a dash inside a scalar (a-b), a dash starting a word (-x), and a quoted dash all stay valid. Lifts official test-suite parse-level conformance from 273/333 (82.0%) to 275/333 (82.6%), with no regression. -
A block scalar leading blank line that is more indented than the content is now rejected. The spec forbids a leading empty line from containing more spaces than the first non-empty line, so a block scalar whose blank lines are wider than its content (
|then a 5-space blank then 2-space content) no longer parses. Indentation is counted in spaces, not tab-expanded width, so a tab on a blank line (␣\t) is not treated as a deeper indent. Leading blanks within the content indent are unaffected. Lifts official test-suite parse-level conformance from 270/333 (81.1%) to 273/333 (82.0%), with no regression. -
A document marker line (
---or...) inside a multi-line quoted scalar is now rejected. Such a line is ambiguous with a document boundary, so the spec forbids it within a scalar; the scanner previously folded it into the value. The marker must begin a line and be followed by a boundary to be rejected, so inline dashes ("a --- b"), a---with no following boundary (---b), and an indented---remain ordinary content. Lifts official test-suite parse-level conformance from 268/333 (80.5%) to 270/333 (81.1%), with no regression. -
A block sequence can no longer start on the same line as its anchor or tag (
&a - x). A block collection must begin on the line after its node properties, so an anchor or tag immediately before the first block entry is now rejected. An anchor or tag on its own line above the sequence, inside a sequence item (- &a x), before a flow sequence (&a [x]), or on a scalar is unaffected. Lifts official test-suite parse-level conformance from 267/333 (80.2%) to 268/333 (80.5%), with no regression. -
An alias node can no longer carry an anchor or tag. An alias is a bare reference, so
&b *a(an anchor on an alias) and a tag on an alias are now rejected; the parser previously dropped the property and accepted the document. A bare alias and an anchor or tag on a real node are unaffected. Lifts official test-suite parse-level conformance from 266/333 (79.9%) to 267/333 (80.2%), with no regression. -
A comment can no longer interrupt a multi-line plain scalar. A comment terminates a plain scalar, so content that tries to continue it on a following line (
key: word1then a#line thenword2, orathenb # ...thenc) is now rejected instead of being silently merged back into the value. A genuine multi-line plain scalar and a trailing comment after a value are unaffected. The parser path that re-merged the scanner-split scalar is removed, since the scanner only splits a plain scalar this way when a comment broke its folding. Lifts official test-suite parse-level conformance from 264/333 (79.3%) to 266/333 (79.9%), with no regression. -
A quoted scalar that spans a line break can no longer be a block implicit key (
"c⏎ d": 1). An implicit key in block context must lie on a single line, so a quoted scalar whose open and close quotes sit on different lines is now rejected when used as such a key. The rule is block-only: a flow mapping key may span lines ({ "a⏎ b": 1 }), and a multiline quoted value, a single-line quoted key, and an explicit key (? "a⏎ b") are all unaffected. Lifts official test-suite parse-level conformance from 261/333 (78.4%) to 264/333 (79.3%), with no regression. -
A block sequence can no longer be an implicit key's value on the same line as its
:(key: - a); the value must begin on a following line, or use flow style (key: [a]). Like the inline nested mapping rule, this is specific to an implicit key: an explicit- or null-key:opens its line, so a compact sequence after it stays valid, as do a sequence on the next line, a nested sequence (- - a), a flow sequence, and a negative number (key: -1). Lifts official test-suite parse-level conformance from 260/333 (78.1%) to 261/333 (78.4%), with no regression. -
An inline nested block mapping is now rejected. Block style allows only one mapping pair per line, so a scalar followed by
:after a block-level value on the same line (a: b: c,a: 'b': c,x: { y: z }in: valid, or trailing content after a quoted value) no longer parses as a nested mapping. The scanner suppresses the implicit key it would otherwise synthesize once the line already holds a pair. A value indicator that opens its line is an explicit- or null-key indicator, whose value may legitimately be a compact mapping (? kthen: a: 1), so that, flow mappings ({a: b, c: d}), next-line nesting, and colons inside scalars are unaffected. Lifts official test-suite parse-level conformance from 256/333 (76.9%) to 260/333 (78.1%), with no regression. -
A
...document-end marker no longer accepts content on its own line. Only a comment or blank may follow the marker, so... invalidis now rejected; the scanner previously skipped the rest of the line. A bare..., a trailing comment (... # done), and a...not followed by a boundary (...junk, which is an ordinary plain scalar, not a marker) are unaffected. Lifts official test-suite parse-level conformance from 255/333 (76.6%) to 256/333 (76.9%), with no regression. -
A directive must now be followed by an explicit
---document start. A stream that ends, or reaches a...document-end marker, while a directive is still awaiting its document (%YAML 1.2alone, or%YAML 1.2then...) is now rejected, as the YAML grammar requires a directive to head an explicit document. This applies to any directive, including an unrecognized one, which is still otherwise ignored. A directive followed by---(with content, inline, or empty) is unaffected. Lifts official test-suite parse-level conformance from 253/333 (76.0%) to 255/333 (76.6%), with no regression. -
The
%YAMLdirective is now validated. It takes exactly one parameter, the version, optionally followed by a comment, and at most one may appear per document; an extra parameter (%YAML 1.2 foo) or a second%YAMLdirective is now rejected. Previously any tokens after the version were ignored and duplicate directives were accepted. A well-formed directive, with or without a trailing comment, is unaffected. Lifts official test-suite parse-level conformance from 251/333 (75.4%) to 253/333 (76.0%), with no regression. -
A flow collection no longer accepts an empty entry. A comma separates entries, so one must precede it; a leading comma (
[ , a ]), a repeated comma ([ a, , b ]), or the same in a flow mapping is now rejected, while a single trailing comma ([ a, b, ]) and empty collections ([],{}) stay valid. The parser previously skipped a comma without checking that an entry came before it. Lifts official test-suite parse-level conformance from 249/333 (74.8%) to 251/333 (75.4%), with no regression. -
Double-quoted escape sequences now follow the full YAML 1.2 escape table. Previously the decoder recognized only a subset (
\" \\ \/ \b \f \n \r \t \u) and silently passed any other character through, so invalid escapes such as\.and\'were accepted while valid ones such as\x,\v,\e,\0,\N,\_,\L,\P,\U, and backslash-space were mangled (\x0dbecame the textx0d). The decoder now maps every defined escape to its character, handles\x(8-bit) and\U(32-bit) hex escapes alongside\u, treats a backslash before a line break as an escaped line break that joins the lines with no separator, and rejects an unknown or truncated escape. Lifts official test-suite parse-level conformance from 247/333 (74.2%) to 249/333 (74.8%) and value-level from 166 to 170 of comparable cases (90.4%), with no regression. -
A
#glued to earlier content on its line (e.g."value"# c,[ a, b ]#c,>#c) is now rejected: the spec requires a comment to be preceded by whitespace or to open a line, and such input was previously accepted as a comment. A#that opens a line, follows a space, or sits inside a plain scalar (a#b, where it is literal content) is unaffected. The check tracks whether real content has been scanned on the current line, rather than comparing token line numbers, because the streaming tokenizer drains its buffer and a block scalar's blank line emits an empty scalar attributed to the next line. Lifts official test-suite parse-level conformance from 243/333 (73.0%) to 247/333 (74.2%); four wrongly-accepted invalid documents are now correctly rejected with no valid document regressing. -
A block scalar followed by a less-indented comment line no longer fails with a spurious "unexpected indentation". When a comment ends a block scalar, its own column was processed as a dedent and, landing on a width no indentation level held, raised an error; a comment's indentation is now left out of block structure. Relatedly, a whitespace-only line indented past a block scalar's content level now keeps its surplus spaces as content instead of collapsing to empty, so such a line contributes the correct value. Lifts official test-suite parse-level conformance from 240/333 (72.1%) to 243/333 (73.0%) and value-level matches.
-
A quoted mapping key may now have a space before its
:("key" : value). A plain key consumes the space before the colon into the scalar, but a quoted key stops at its closing quote, leaving the space, and the implicit-key check looked only at the immediate next character. It now looks past spaces for the colon, as the spec allows. Quoted keys with no space, quoted values, and plain keys are unaffected. Lifts official test-suite parse-level conformance from 238/333 (71.5%) to 240/333 (72.1%). -
A block mapping pair after the first may now carry an anchor or tag on its key (
k: 1/&b key2: 2). The first pair's key properties were consumed when the mapping was entered, but later pairs were not, so an anchored key past the first failed with "expected mapping key". The pair parser now consumes leading key properties for every pair, and the mapping continues across an anchor or tag that begins a key. Lifts official test-suite parse-level conformance from 235/333 (70.6%) to 238/333 (71.5%). -
An explicit mapping key (
? key) with no following:now maps to null instead of failing to parse, so several? keyentries in a row (a set, for instance) each map to null. The parser required a:after every explicit key; it now treats a missing one as an implicit null value. Explicit keys with values, and complex keys generally, are unaffected. Lifts official test-suite parse-level conformance from 229/333 (68.8%) to 235/333 (70.6%). -
An unrecognized directive (e.g.
%FOO) before a document is now ignored, as the YAML spec requires (a warning, otherwise no effect), instead of being rejected with an error.%YAMLand%TAGare unchanged, and a directive after content (where one cannot appear) is still rejected. Lifts official test-suite parse-level conformance from 227/333 (68.2%) to 229/333 (68.8%). -
A plain scalar at the document root now folds across lines that sit at column 1, so a bare multi-line value such as
a/b/cbecomes"a b c"instead of failing to parse. The continuation check required a continuation to be more indented than the scalar, but a root scalar has nothing enclosing it, so its enclosing-block indent is -1 and a continuation may start at column 1. The continuation now stops at a document marker (---/...), so a scalar never folds across a document boundary. Lifts official test-suite parse-level conformance from 221/333 (66.4%) to 227/333 (68.2%). (A stream test that asserted two bare plain lines were rejected as extra content was corrected: that input is a valid multi-line scalar; genuine extra content, like a flow node followed by a scalar, is still rejected.) -
A multi-line single-quoted scalar now folds its line breaks, like the double-quoted fix below; both share the same flow line folding, so the fold logic is now one helper. Lifts official test-suite value-level conformance from 143/169 (84.6%) to 147/169 (87.0%), with no regression.
-
A multi-line double-quoted scalar now folds its line breaks instead of keeping them raw. The decoder appended real line breaks and continuation-line indentation verbatim, so
"a\n b"came back as"a\n b"rather than"a b". It now applies flow folding: a single break folds to a space, a blank line to one newline, and whitespace adjacent to a break (a line's trailing, the next line's leading) is stripped, while first-line leading and last-line trailing whitespace and\nescapes are preserved. Lifts official test-suite value-level conformance from 135/169 (79.9%) to 143/169 (84.6%), with no regression; parse-level is unchanged because these documents already parsed, just to the wrong tree. -
A root node that begins on the document-marker line (
--- >,--- |,--- foo,--- {a: 1}) is no longer discarded. The marker scanner skipped the rest of the---line unconditionally, so a block-scalar header was dropped and its body was mis-read as a plain scalar (folded to spaces, no trailing newline) and a same-line plain or flow node was lost entirely. The document start now keeps any real same-line content for the parser, skipping only trailing spaces or a comment. Lifts official test-suite value-level conformance from 130/170 (76.5%) to 135/169 (79.9%), with no regression; parse-level is unchanged because these documents already parsed, just to the wrong tree, which only the value-level metric could see. -
A multi-line plain scalar whose value begins on its own line under a mapping key now folds its continuation lines instead of stopping after the first. The continuation check compared the next line's indent against the value's own pushed indent, so a continuation at the same indent failed the strict
>; it now compares against the parent block's indent, matching the spec (continuation must exceed the mapping's indentation, not the value's). Lifts official test-suite parse-level conformance from 211/333 (63.4%) to 221/333 (66.4%), with no regression across the existing suite.
Changed
- Split multi-type source files so each file declares exactly one top-level type
(
docs/rules/code-style.md): the Tagged node component types, the validation report types,TokenKind, and the event-stream composer helpers each move to their own file. Public type names are unchanged.scripts/check-namespacing.shis now namespace-aware and detects multiple sibling types declared insideextensionblocks, which the previous column-anchored scan missed. - Merge-key (
<<) override resolution now lives in a single internal helper,Parsing.MergeResolution, shared by the buffered and streaming event composers. Both paths previously carried an identical copy of the inherited-versus-local pair merge, so the subtle precedence rules (local keys win, earlier sources win, inherited-then-local ordering) now have one source of truth. No behavior change.
Removed
- Remove three
Parsing.ParseErrorcases that were never thrown:emptyDocument(empty and comment-only documents parse tonull),expectedMappingKey(superseded byunexpectedTokencarrying an "expected mapping key" message), andtabIndentation(tabs in indentation are reported by the validation layer'sPreflightScanner, not the parser). No reachable behavior changes.
Fixed
- Preserve blank lines in block scalars. The scanner dropped every blank line
within and after a block scalar, so a literal
|lost its internal blank lines, a folded>turned a blank line into a space instead of a newline, and the|+/>+keep indicator could not preserve trailing blank lines. Blank lines are now captured as empty content in both the batch and streaming scan paths (which had duplicated the loop), andblockScalarValueapplies literal versus folded line semantics and clip/strip/keep chomping correctly. A block scalar without blank lines is unchanged. - Keep a more-indented line inside a folded
>block literal, with its line breaks preserved, rather than folding it into the surrounding text. - Preserve leading blank lines between a block scalar header and its first content line. They precede the indent token, so they are buffered and emitted as empty content once the content indentation is established.
Documentation
- Correct
SECURITY.md: fix the reporting contact address and replace the scope section, which described an unrelated static-site generator, with the YAML parsing, validation, and emitting surface that is actually in scope.
[0.1.5] - 2026-06-23
Documentation
- Document why
maxNestingDepthis the necessary and sufficient safety bound for deeply nested input: aModel.Valueis a recursive tree whose every operation (compose, emit, compare, hash, and especially deallocate) recurses with nesting, and Swift cannot deallocate a recursive value type iteratively, so bounding the tree's depth at parse time is the only complete protection. Records the measured headroom, why the bound cannot be raised without an iterative parser (and would be pointless past the ~5,000deinitlimit), and the caveat that trees built by encoding a deepCodablevalue bypass it.
[0.1.4] - 2026-06-23
Fixed
- Reject documents nested beyond a fixed depth (
maxNestingDepth) with anestingTooDeepparse error instead of overflowing the recursive-descent parser's stack. A pathologically nested input (for example hundreds of nested[[[...]]]or deeply indented mappings) previously crashed the process; it now fails cleanly. The limit is well above the nesting of real-world specs, which are unaffected.
[0.1.3] - 2026-06-23
Fixed
- Parse a leading
#in block scalar content (>,>-,|,|-) as literal text instead of a comment. A block scalar whose first content line began with#, such as an OpenAPI$ref: >-folded onto#/components/..., was previously dropped to an empty string.
[0.1.2] - 2026-06-06
Added
- Document the real-world YAML corpus, fuzz/property gate, and CI artifact contract for production hardening.
- Add machine-readable parser diagnostic codes to validation report payloads and cover malformed production-shaped YAML with 10+ structured diagnostics.
- Vendor a 114-file real-world YAML corpus with a machine-readable manifest, default metadata checks, and an opt-in full parse/validate/round-trip gate.
- Add large public APIs.guru Stripe and Zoom OpenAPI YAML specs to the opt-in corpus gate.
- Add a reduced synthetic ACME Zephyr fixture set for Stitcher-style multi-file OpenAPI inputs and bundled output.
- Add a full renamed Birch-style ACME fixture catalog with 594 YAML files, preserving module/file structure while replacing private organization names, domains, and documentation URLs.
- Add YAML 1.2 JSON-subset compatibility for compact flow mappings such as
{"openapi":"3.0.0"}, including regression coverage for colons inside flow mapping values. - Add JSON compatibility tests and artifacts that compare PureYAML against Swift's JSON decoder across JSON roots, escapes, Unicode surrogate pairs, exponent numbers, nested values, and whitespace.
- Preserve round-trip fidelity for mapping keys that require quotes, including trailing-space keys found in the large Zoom OpenAPI corpus seed.
- Add an opt-in Yams differential script that compares parse behavior for the checked-in real corpus without adding Yams to the PureYAML package manifest.
- Add an opt-in Yams diagnostic comparison script that records PureYAML structured malformed-input diagnostics alongside Yams parser errors.
- Add an opt-in Yams validation comparison script proving structured duplicate key validation on YAML that both parsers can load.
- Add an opt-in Yams throughput script and scheduled/manual CI artifact for release-mode parser performance comparison on representative corpus seeds.
- Add an opt-in PureYAML phase profiler that times scanner, event parser, composer, lazy parse, validation, and dumping phases on slow corpus seeds.
- Compose normal parser output from events as they are emitted, avoiding a full
intermediate event array while keeping
parseEventsavailable for explicit event materialization. - Lazily scan tokens for normal
parseandparseStreamcalls, avoiding a retained full token array on the main parser path. - Track reader positions with a UTF-8 cursor so ASCII-heavy scanner advancement avoids per-character string allocation while preserving byte-accurate marks.
- Add deterministic generated corpus properties for valid YAML round trips and malformed real-seed mutations with structured diagnostics.
- Write corpus run artifacts under
.build/pureyaml-artifacts/, including real seed summaries, generated mutation summaries, seed metadata, and environment details. - Add a scheduled/manual CI corpus job that runs the corpus and Yams differential gates and uploads the generated artifact bundle.
[0.1.1] - 2026-06-06
Added
- Add platform CI badges and an active production-hardening roadmap to the README.
Changed
- Add release-mode build and test gates to the macOS, Linux, Windows, and WASM verification scripts.
- Update GitHub Actions checkout steps to
actions/checkout@v6so CI uses the current Node 24 action runtime.
Fixed
- Treat more-indented plain scalar continuation lines that start with
-as text unless they appear at a known sequence-entry indentation. This fixes OpenAPI-styleallOfdescriptions while preserving nested block sequences such as- - 123. - Parse explicit scalar keys whose
:value starts a same-line mapping and continues with indented mapping siblings, matching large OpenAPI schema keys.
[0.1.0] - 2026-06-05
Added
- Bootstrap PureYAML as a root Swift package with one
PureYAMLlibrary product, no external SwiftPM dependencies, no C sources, no generated parser targets, and no Foundation requirement in the library target. - Add the core pure-Swift YAML model with ordered mappings, sequences, scalars,
duplicate-key preservation, and first-class complex mapping keys through
Model.Pair.keyNode. - Add parser support for block mappings, block sequences, comments, flow collections, quoted strings, literal and folded block scalars, anchors, aliases, YAML directives, document markers, merge keys, complex mapping keys, multi-document streams, and selected explicit built-in scalar tags.
- Add deterministic YAML dumping with block output by default, optional flow collections, conservative plain scalars, conservative literal block scalars, complex mapping key dumping, and multi-document stream dumping.
- Add tag-preserving parsing with
PureYAML.parseTagged(_:)andPureYAML.parseTaggedStream(_:), plus tagged validation rules for unsupported built-in tags and tags applied to the wrong node kind. - Add
PureYAML.Tagged.Constructorfor caller-owned tagged construction with exact missing-handler and kind-mismatch errors, recursive path context, and a model-value fallback that preserves mapping order and duplicate keys. - Add path-aware validation with duplicate-key checks, custom rules, rule predicates, strict and non-strict behavior, warning collection, stream document indexes, deterministic validation paths, and direct value-tree validation for states ordinary loaders may collapse.
- Add diagnostic-first validation reports, raw-source preflight scanning,
Validation.ReportError, and Markdown, YAML, and JSON report rendering for application-owned files or error bodies. - Add scalar, keyed, unkeyed, nested, dynamic-key, dictionary-like, and
super-coder
Codableconversion APIs with exact path-aware errors. - Add fixture-backed compatibility coverage for scalar spellings, explicit tags, collections, anchors, unsupported YAML gaps, literal block emission, downstream documents, and deliberately failing validation fixtures.
- Add a real-world YAML fixture corpus with representative short, medium, large, and very large documents, including OpenAPI, Kubernetes, GitHub Actions, Docker Compose, Prometheus, and cert-manager YAML.
- Add macOS, Linux, Windows, and WASM verification gates, hosted CI, a full local verification script, a pre-push hook, usage documentation, migration boundaries, attribution, and release notes.
Changed
- Lower the package tools version to Swift 6.1 for hosted macOS CI compatibility.
- Harden duplicate-key validation to use set membership while preserving exact diagnostics.
- Make validation rules immutable after construction.
- Preserve keyed super-encoder field order even when delayed child encoders are written in a different order than they were requested.
- Make keyed default
superEncoder()andsuperDecoder()use the standardsupermapping key instead of the current mapping. - Resolve Yams-compatible plain scalar spellings for
yesandnobooleans, radix-prefixed integers, numeric separators, and.infand.nanfloats. - Broaden opt-in literal block emission while preserving exact parser round-trips for every emitted block scalar.
- Harden block mapping, multiline plain-scalar parsing, merge expansion, tagged parsing, lower-column mapping siblings, indented root fragments, JSON-style flow mapping pairs, tab-indented corpus files, and empty collection emission.