Compatibility

This is the exhaustive compatibility and divergence reference. For everyday use you don’t need it — see Schema modes, Untrusted input, and Migrating from serde_yaml.

What this crate targets

• Primary API: serde_yaml read-side ergonomics for config-shaped YAML — from_str / from_slice / from_reader, plus Value and structural writes.
• Parser reference: YAML 1.2 tree/event acceptance comparable to yaml-rust2 and saphyr for supported syntax.
• Documented divergence: libyaml / YAML 1.1-era behavior is version-pinned against a Ruby Psych 3.1.0 / libyaml 0.2.1 probe. Default loading is YAML 1.2-oriented; YAML 1.1 typing is opt-in.

Every divergence record under tests/fixtures/divergences/records/ carries a migration_impact field, and tests/divergence_manifest.rs fails any record that omits caller-facing impact. That registry is the source of truth for intentional behavior splits.

serde_yaml 0.9 rename support matrix

“Supported” means the name resolves under both serde_yaml = { package = "saneyaml", ... } and use saneyaml as serde_yaml;. “Intentionally divergent” means it resolves but behaves differently by policy. “Not preservable” means it isn’t a stable surface this crate emulates.

Reproducible loader matrix

Generated from tests/fixtures/compatibility-matrix/manifest.toml and checked by tests/compatibility_matrix.rs. Cross-ecosystem entries are pinned offline vectors; the Rust test validates their metadata and does not execute Go, Python, or C++ runtimes.

Behavior by area

Scalar Resolution Modes

Schema::Yaml12 is the retained spelling for Schema::Core (the default); Schema::Yaml11 is the retained spelling for Schema::LegacySerdeYaml. Schema::Json resolves only JSON lowercase booleans/null and JSON numbers, then keeps other scalar text as strings. Schema::Failsafe keeps every scalar a string. Missing mapping values and empty documents are null in every mode.

Tree-shape divergences

A few YAML 1.2 inputs parse fine as events but yield tree-shape divergences in the loaded tree, where reference loaders disagree. saneyaml keeps these in event parity and shared-reference acceptance, excludes them from loaded-tree value-shape parity, and pins a divergence record for each:

• PW8X and 6KGN — anchors on empty scalar nodes.
• S4JQ — an explicit non-specific tag shape on an empty node.
• C4HZ — a custom tag plus a schema scalar divergence.
• FH7J — tags on empty scalar nodes.

tests/parity_manifest.rs gates these terms and the event/tree/shared-reference ledgers; cargo test --test conformance_dashboard -- --nocapture prints the full 402-case selected-suite dashboard with divergence overlays.

Event and streaming contracts

• EventStream is the stable pull-based parser-event surface; parse_events is the all-or-error collector over the same events. Events carry scalar style, block/flow collection style, tags, anchors, alias events, and DocumentStart directives. Aliases are not expanded here.
• DocumentStream is the semantic pull stream — one merge-expanded Node per document, same schema/limits/spans as parse_documents.
• Reader constructors fully buffer bounded input before yielding, so streaming bounds the retained parsed representation, not the source bytes.

Raw scalar spelling and graph identity are not exposed by events; recover them with LosslessStream::source_fragment(span) and the lossless graph.

Threat Model and Resource Guarantees

The defended input is untrusted YAML at every load entrypoint. With default LoadOptions, the crate rejects:

• input above 64 MiB before parsing,
• alias-expansion bombs (input-derived budget) and recursive aliases,
• nesting beyond 128, scalars above 1 MiB, and collections above 16,384 entries,

with span-bearing diagnostics. Raw event and lossless streams validate alias references but don’t expand them. Callers can tighten or relax each limit through LoadOptions; a without_*_limit() opt-out transfers that bound to the caller.

These are structural construction limits, not wall-clock or resident-memory guarantees: reader entrypoints fully buffer bounded input, and your own Deserialize impls can allocate after the YAML layer hands them bounded values. saneyaml validates YAML structure, not application schemas. See Untrusted input for the how-to and SECURITY.md for reporting.

Public API stability

The crate is pre-1.0 (MSRV Rust 1.88), but the preview surface is SemVer-visible: public exports, enum variants, struct fields, constants, and the package-vs-library name split are commitments. docs/PUBLIC_API.txt is the committed snapshot checked for drift; intentional changes must update it along with this file and MIGRATION.md.

saneyaml::Error keeps a flat Display compatible with the preview contract and exposes additive category(), path(), document_index(), and render_source(...) diagnostics. saneyaml::Index and saneyaml::mapping::Index are sealed.