NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io
crates.io, #2392 most downloaded on crates.io
YAML (de)serializer for Serde, emphasizing panic-free parsing, fast builds and good error reporting. Supports properties, include, tag and comment capture
Latest stable
2.1.1
Last release 17 days ago
05 Nov 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 32 of 35 stable releases
3 versions withdrawn
withdrawn after publishing
1 years old
40 releases · first in 2025
Drag across the ruler to compare, or tap a release to open it.
Fixed 2.1.0 regression empty documents producing errors ( #265 ). Empty document is a valid YAML document. Fix of this regression is the reason of mak
2.1.1 Optimization and maintenance release Latest
Latest
Compare
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Deprecated SerializerOptions::empty_as_braces . Setting it to false emits YAML null for empty block collections without tags or anchors. These values…
Options::reject_tagged_field_names to catch misplaced tags onError::TaggedStructFieldName diagnostics. Struct field names can!!str is still accepted. As other tags can only be ignored, tag on a structureOptions::leading_zero_numbers_as_strings andOptions::underscored_numbers_as_strings to preserve numeric spellings such as0755 and 1_000 as strings in untyped values, including untagged enums andfalse; direct typed parsing, explicit numeric tags, andError::render_to to append diagnostics to any std::fmt::Write usingRenderOptions, without collecting the complete output in an intermediate stringDuplicateKeyPolicy::PassThrough to delegate repeated explicit mapping entriesserde_yaml's handling for structs, standard maps, and customError; merge expansion retains its precedence rules. See the READMESerializerOptions::empty_as_braces. Setting it to false emits YAML nulltrue and emit [] or {}.std::io::Error from deserialization failures throughstd::error::Error::source(). The outer message is IO error, so error chainsMessageFormatter::format_standalone_message.Error::WithSnippet when followingstd::error::Error::source() by forwarding the wrapped error's source.without_snippet() to inspect the wrapped error. Alias errors retain their!time duration tag is distinct from standard YAML!!timestamp; robotics tags require the feature and angle_conversions: true.~, null, Null, and NULL are handled consistently.[] for an empty sequence or {} for an empty mapping. Option<T> null handlingThis release includes some verified performance improvements, as well CodSpeed suite extensions to justify them
–
PropertySyntax::DockerComposeWithNulls: Compose interpolation where a value that is
solely a reference to an unset property, or whose expansion is null/~, becomes YAML null.
Explicitly empty properties and empty defaults stay empty strings, and DockerCompose itself
is unchanged.Options::reject_tagged_field_names to catch misplaced tags on
struct field names, with Error::TaggedStructFieldName diagnostics. Struct field names can
only be strings, !!str is still accepted. As other tags can only be ignored, tag on a structure
field name is almost for sure placed wrongly. This setting will be default in next major release.Options::leading_zero_numbers_as_strings and
Options::underscored_numbers_as_strings to preserve numeric spellings such as
0755 and 1_000 as strings in untyped values, including untagged enums and
flattened fields (#225).
Both default to false; direct typed parsing, explicit numeric tags, and
mapping-key comparison keep their existing behavior.Error::render_to to append diagnostics to any std::fmt::Write using
RenderOptions, without collecting the complete output in an intermediate string
(#221).DuplicateKeyPolicy::PassThrough to delegate repeated explicit mapping entries
to Serde visitors, matching serde_yaml's handling for structs, standard maps, and custom
multimap visitors (#226).
The default remains Error; merge expansion retains its precedence rules. See the README
migration note for the scope of this option.SerializerOptions::empty_as_braces. Setting it to false emits YAML null
for empty block collections without tags or anchors. These values do not round-trip into
collection types. Omit the setting to keep the default true and emit [] or {}.
Existing serialization behavior remains supported for compatibility.garde and validator integrations. A document such as !Maybe null now reaches
enum dispatch instead of being skipped. This also affects default options: an
Option<String> target receives a None item for !Foo null, while a String target
reports NullIntoString. Untagged null documents and explicit !!null are still skipped.no_schema:
!Number 42 can deserialize into a numeric payload, while a string payload still
requires quoting, as in !Text "42". This applies independently of property interpolation.std::io::Error from deserialization failures through
std::error::Error::source(). The outer message is IO error, so error chains
include the underlying cause only once. Standalone Miette, Figment, and Figment2
diagnostics retain the cause in their messages. Custom Miette formatters retain
control over the complete message through MessageFormatter::format_standalone_message.Error::WithSnippet when following
std::error::Error::source() by forwarding the wrapped error's source.
Use without_snippet() to inspect the wrapped error. Alias errors retain their
complete source chain, including snippet wrappers, for compatibility.!time duration tag is distinct from standard YAML
!!timestamp; robotics tags require the feature and angle_conversions: true.~, null, Null, and NULL are handled consistently.
Write [] for an empty sequence or {} for an empty mapping. Option<T> null handling
and defaults for absent fields are unchanged; see the README migration notes.2.1.0 Minor feature extension, maintenance and performance release
Compare
This feature was the main reason to advance the first version digit, because formally this is a breaking change.
Breaking changes
AliasError. The old field (text representation) is still present, but deprecated. Another formally breaking change, even if unlikely to be a problem.All other changes are backward compatible:
strict_indentation flag in Options.Inf and NaN if so configured. Even if most common serde_json::Value cannot take them (produces null instead), many other abstract value receivers can.huge_documents and serde_derived_types enable deserialize, fixing isolated feature--no-default-features, including autopkgtests of Debian team (as observed).SerializerOptions::no_lang_directive (default false) to suppress the %YAML 1.2 directive independently of yaml_12's quoting (requirement obvious from Nushell code work work arrounds).serde_saphyr::from_str_multiple supports any collection implementing Default + Extend<T>, such as Vec<T>, VecDeque<T>, BTreeSet<T>, or custom storage like SmallVec<T>.Other fixes
~ or null; quoted strings and collections are rejected.path_map::PathKind, PathKey::segments(), and PathMap::locations_for()
for inspecting validation paths and resolving their YAML use/definition locations,
including best-effort spelling matches and recorded ancestor/root fallback.RenderOptions::line_offset and RenderOptions::source_name for displaying
embedded YAML diagnostics at their containing document's line numbers and naming
the root source in snippet headers, including the new
miette::to_miette_report_with_options entry point. Included files retain their own
names and coordinates, and stored error locations and spans are unchanged.PropertySyntax::DockerCompose for Compose-compatible property interpolation.comments feature, forwarding to granit-parser's matching
feature. Builds with default-features = false must enable it to use Commented<T>,
CommentPosition, comment options, or comment budget fields and reports. Without it,
YAML comments are still accepted and validated, but their text is not retained.Options::non_finite_float_policy with NonFiniteFloatPolicy::{PassThrough, Reject, AsString}
to configure non-finite floats delivered through deserialize_any. Explicit policies override
the legacy boolean; leaving the field unconfigured preserves its behavior.borrowed_context example showing recursive Serialize adapters that borrow
an existing value tree and per-call formatting context, composing with Tagged<T> and
style wrappers without building a second container tree or using thread-local state.SerializerOptions::no_lang_directive (default false) to suppress the
%YAML 1.2 directive and its leading --- marker independently of yaml_12's quoting.from_str_multiple, from_bytes_multiple, and their _with_options variants to
deserialize multiple YAML documents into any C: Default + Extend<T>, including vectors,
queues, sets, and custom accumulators. Values can borrow from the input string or UTF-8 byte
slice. Explicit type arguments specify both the document and collection types, for example
from_str_multiple::<String, Vec<_>>(input).error: Box<Error> field to Error::AliasError, which keeps the original error
when an aliased value fails to deserialize. A custom MessageFormatter or Localizer
now applies to that error, and std::error::Error::source returns it
(#199).from_multiple, from_multiple_with_options, from_slice_multiple, and
from_slice_multiple_with_options now accept T: Deserialize<'de> so values can borrow from
the input. They retain their names, single type parameter, and Vec<T> returns and are not
deprecated. Ordinary calls, including from_multiple::<Config>(input) and generic callers
with T: DeserializeOwned, continue to work. Function pointers or callbacks accepting arbitrary
input lifetimes may need forwarding closures, such as |input| from_multiple::<String>(input).comments feature. Serialization-only builds remain independent of
granit-parser, including when comment emission is enabled.deserialize_any, including overflowing
literals such as 1e999. Opt into PassThrough to preserve them in float-capable visitors,
untagged enums, and flattened float fields, or AsString to receive canonical strings.
With PassThrough, serde_json::Value converts them to Null without an error.
Direct f32/f64 deserialization is unchanged.Error::AliasError has a new mandatory error: Box<Error> field.
Manual constructors must supply it, and patterns listing every field must add error or ...
The variant name is unchanged. Rendering and source() use the original error; the
deserializer still populates msg with an error.to_string() snapshot for existing handlers.Options::reject_non_finite_typeless_float in favor of non_finite_float_policy.
When the new field is unconfigured, the boolean retains its original behavior: true
(the default) rejects and false converts to strings. Use Reject or AsString, respectively,
when migrating. Explicit policies override the boolean. Serialized options that omit both
fields retain the 1.3.0 behavior of converting non-finite floats to strings;
Options::default() continues to reject them.msg field of Error::AliasError in favor of its structured error field.
Existing Error::AliasError { msg, .. } patterns still work with a deprecation warning.~, null, Null, and NULL.
Other capitalization such as NulL remains a string instead of being rejected, converted
to an empty value, or skipped as a document (#234).LastWins values and inline merges no longer produce alias errors when no
alias was used. Replay preserves per-node origins, including genuine nested aliases,
ordinary value locations, and merge use-sites for Spanned<T>.strict_booleans: true now recognizes only the six YAML 1.2 Core boolean spellings.
Other capitalization such as tRuE remains a string during inference, is accepted
as unquoted text with no_schema, and is rejected for boolean targets.(used at line X, column Y).
The new Localizer::alias_used_at hook controls this suffix independently of failure and
definition locations. Custom localizers that previously used attach_location to format
or suppress alias-use coordinates should override alias_used_at as well.Localizer implementations migrating from 1.x must also override
anchor_defined_here to translate the alias anchor-definition label.(defined) or
(defined here), including errors in included YAML files.Error::SerdeInvalidLength with separate
len, expected, and location fields, allowing custom formatters to inspect them.
Default diagnostic wording is preserved (#205, item 6).Localizer::root_path_label in plain, snippet, and
miette diagnostics (#205, item 5c).MessageFormatter::format_validation_issue_lines hook; existing custom whole-message
overrides retain their behavior (#205, item 5a).error, source(),
and the legacy msg field (#205, item 1).miette
reports include the distinct failing location; equal locations are not repeated.MessageFormatter, including
formatters that delegate other variants to the built-in formatter. Plain messages report
the alias definition and use locations once through the active Localizer; snippet and
miette diagnostics use location labels without embedding plain-text location suffixes.
Custom location formatting and suppression now apply throughout aliased values
(#199).std::error::Error::source exposes the inner error for both Error::AliasError and
Error::WithSnippet, preserving the source chain through the default snippet wrapper.huge_documents and serde_derived_types enable deserialize, fixing isolated feature
builds with --no-default-features, including autopkgtests of Debian team (as observed).serde_yaml migration caveat for null values in String fields,
including when to use Option<String>, quoted strings, or !!str
(#229).2.0.0 Performance and compliance release
Compare
Integer mapping keys now compare by their parsed numeric value for duplicate detection and merge resolution, including inside composite keys ( 0xB and
0xB and 11 compare equal). Deserializing to stringsFirstWins and LastWins retain the selected key's spelling{{"null": 1}: 2} now round-trips correctly.!!str null, including when deserializing to Option<String>.!!int and !!float) now deserialize correctly through deserialize_any,from_str::<f64>("!!str 1.5") now returns an error.\uFFFE and \uFFFF.LitStr and LitString, by using keep chomping and retaining every empty line.Input for performance improvements. As serde-saphyr re-exports it,1.3.0 Maintenance and performance release
Compare
This release focuses on enhanced tag support.
This release focuses on enhanced tag support.
Tagged<T> wrapper that is similar to Commented<T>.ruamel.yaml that rejects tags for which it has no constructor (serde-saphyr does not construct this way) that caused discussion on prek.Budget; property resource-limit
failures are now reported through Error::Budget and BudgetBreach.Options::reject_unsupported_tags strict mode. It rejects explicitly tagged
scalar, sequence, and mapping nodes when their tag is unknown to serde-saphyr; the default remains
permissive for compatibility with custom tagged enums. YAML 1.1 !!merge and !!value are
accepted in this mode only as the exact scalar mapping keys << and =, respectively, while
robotics-only !degrees and !radians require both the robotics crate feature and
angle_conversions, and !include requires both the include crate feature and a configured
resolver.reject_unsupported_tags is disabled.indent_step is now limited to 1..=64, all
serializer entry points validate it, and indentation arithmetic returns an error instead of
overflowing. We do not consider this breaking because values outside this range does not look sane.#, such as
a#b, while retaining quotes for leading or whitespace-separated hashes. Borrowed from
commit 1119a54
under the terms of the Apache/MIT licenses. When property interpolation is configured,
newly plain values such as ${NAME}#fragment can interpolate; use quote_all to preserve
literal values.!!merge keys, including verbatim tags and %TAG-expanded
handles, everywhere implicit << merge keys are supported.!!value tag while intentionally treating it as a no-op annotation.#-prefixed content lines.typetag trait-object deserialization by consuming the closing mapping
event when a Serde map visitor returns after its final key/value pair, preventing a false
"multiple YAML documents" error.Added granit-parser resource limits to Budget ( #172 ):
Added granit-parser resource limits to Budget (#172):
max_buffered_comment_events (default: 32)simple_key_max_lookahead (default: 1,024 characters)flow_nesting_limit (default: 255)The limits are applied to parsers created for strings, readers, standalone budget checks, and
included YAML sources. When the serde_derived_types feature is enabled, deserializing an older
Budget representation that omits these fields uses the documented defaults.
Fix #170 regression on local type tags
This means that API changes will be clearly reflected in the version number: the major version indicates breaking changes, the minor version indicates…
From this release onward, we are adopting the 1.x.x semantic versioning (SemVer) scheme. This means that API changes will be clearly reflected in the version number: the major version indicates breaking changes, the minor version indicates backward-compatible additions, and the patch version indicates backward-compatible fixes. The current compatibility status is indicated by the accompanying badge.
This release adds some #[track_caller] and #[must_use] annotations where looks reasonable. There are not many other changes that is exactly the point: the crate seems serving community well enough.
Nothing published for this version
This means that API changes will be clearly reflected in the version number: the major version indicates breaking changes, the minor version indicates…
From this release onward, we are adopting the 1.x.x semantic versioning (SemVer) scheme. This means that API changes will be clearly reflected in the version number: the major version indicates breaking changes, the minor version indicates backward-compatible additions, and the patch version indicates backward-compatible fixes. The current compatibility status is indicated by the accompanying badge.
Some breaking changes were made at this point because this is the last good time to streamline the API. Please raise any issues you find with the API changes, or if you would like to propose something. The goal of the release preview is exactly not to go 2.x.x next week after release.
Options, SerializerOptions, Budget, and AliasLimits are now #[non_exhaustive]. Construct them with options!, ser_options!, budget!, and alias_limits!.to_writer and to_writer_with_options APIs. Use to_fmt_writer* for fmt::Write or to_io_writer* for io::Write.Also
!!str 42 is accepted as i32(42), and !!int true is accepted as bool(true). Core tag handling is now hardened, and such constructs no longer pass.1.0.0-rc.1 release preview Pre-release
Pre-release
Compare
Summarizing results of automated fuzzing and static analysis, robustness against malformed (bad intent) YAML input was further hardened.
serde-saphyr emulates, supports property nesting, so implemented nesting support for serde-saphyr as well. In the previous release, "${SET:-${B}}" with SET=value resolves to "value}".inf/Infinity/nan). YAML 1.2 only recognizes the .inf/.nan forms.FoldStr wrapping now cares not to start a continuation line with a tabSignificant extension of property interpolation ( @CommanderStorm )
SingleQuoted<..> and DoubleQuoted<..> wrappers to emit quoted strings. SingleQuoted may provide additional safety, as control characters will be rejected (with error), rather than written as YAML escape sequences. NullableTilde<T> is like Option and emits tilde ( ~ ) rather than null.serde_coreserde-saphyr now avoids compiling serde_derive by default. The crate core uses serde_core instead that allows building serde-saphyr in parallel with serde_derive. However this also means that we needed to drop the previously built-in (de)serialization support for some serde-saphyr own configuration and reporting types like Options. (De)serialization support for these types can be re-enabled with the new feature serde_derived_types:
serde-saphyr = { version = "...", features = ["serde_derived_types"] }This does not affect normal use of serde-saphyr for user data, you can still serialize and deserialize your own structs as before.
0.0.28 Property interpolation extensions and even faster builds
Compare
The major extension of this release is comments support.
The major extension of this release is comments support.
The long existed wrapper Commented<..> was usable for serialization only until now. Since this release, Commented also captures a comment of the wrapped data structure:
struct DeploymentConfig {
name: Commented<String>,
image: Commented<String>,
ports: Commented<Vec<Commented<u16>>>,
labels: Commented<BTreeMap<String, Commented<String>>>,
}would capture all comments for the elements of the structure, like
# deployment manifest
name: checkout
image: registry.example.com/checkout:v1 # container image to deploy
ports: # sequence of exposed ports
- 80 # public HTTP
- 443 # public HTTPS
labels: # mapping of Kubernetes labels
app: checkout # stable app label
tier: frontend # routing tier
"#;while assigning them to the relevant YAML element. This became possible after migrating to granit parser 0.0.3, which now captures comments. Comments can be either on the right or above the item they describe.
This release also adds support for figment2 (figment is supported since v0.0.13).
UTF-16LE, UTF-16BE, UTF-8 with BOM and UTF-8 without BOM are all supported for the Reader - based methods (stabilized)
huge_documents mode, using 48 bits only for offsets. This silences Clippy warnings, due these some teams needed to box serde-saphyr Error. The maximal size of documents in huge_documents mode is now 256 Tb that is unlikely a problem (default limit is 4 Gb).Merge key handling is now configurable via MergeKeyPolicy. There may be communities that
<< as ordinary, and these are even not quoted, maybe in generated YAML. Handling of this case is supported via AsOrdinary variant.Error variant for this case.Merge)Fixed deserialization bug ( #100 ) where mixing tagged and #[serde(untagged)] enum variants caused YAML tags to be ignored, leading to incorrect or fa
100000 is valid and 1000_000 also, but _10, 10_ are no longer. This is consistent with the serializer's auto-quoting policies.We need to migrate to macros because adding any field to the public structure is formally a breaking change unless it is #[non_exhaustive], but then i…
#[non_exhaustive], but then it cannot be instantiated, listing fields at all. Use options! { key: value, key2: value2 } macro. After the 1.0.0 release, we still want to keep adding new options without a "major release".Added first-class feature gating for serialize and deserialize, both of which are now enabled by default. Consumers can now build a lighter dependency
serialize and deserialize, both of which are now enabled by default. Consumers can now build a lighter dependency set by enabling only the side they need. Public re-exports in src/lib.rs are now conditionally exposed based on enabled features:serde-saphyr = { version = "0.0.23", default-features = false, features = ["deserialize"] }
or
serde-saphyr = { version = "0.0.23", default-features = false, features = ["serialize"] }
Enabling neither feature is now rejected at compile time. This may happen for projects that previously used default-features = false, features=[]. Simple integrations that only specify the version remain backward-compatible.
Vec at root structure level (#95)This release introduces support for !include. While not a standard YAML, multiple existing implementations show the need for this capability.
This release introduces support for !include. While not a standard YAML, multiple existing implementations show the need for this capability.
serde-saphyr now can resolve !include tags through a custom resolver configured via Options. The !include functionality is gated behind the include feature and must also be explicitly enabled by providing a resolver. For convenience, a safety-hardened filesystem-based resolver is available as an additional optional feature (include-fs).
This library also now supports properties, implemented in a Docker Compose-like style:
database_password: ${DATABASE_PASSWORD}
Properties are implemented to prevent their values from being checked into the repository or from leaking via error snippets or other messages in logs. Tests were written to ensure that the value is never printed on error (please supply the security report if it is). Property values are provided via a custom-supplied HashMap, so up to the user how to store them safely, or maybe even generate them.
Other improvements
serde-saphyr now correctly decodes valid UTF-16 surrogate pair escapes such as \uD834\uDD1E into a single Unicode scalar, matching the equivalent YAML \U form. We also expanded the JSON compatibility test coverage with dedicated cases for objects, arrays, URLs, Unicode escapes, numbers, booleans, and null, and the full related test suite now passes.serde-saphyr can enforce indentation rules during deserialization via RequireIndent.It is now possible to deserialize tuple enum variants, using tags to choose the variant. This is compatible with serde_yaml and serde_yaml_ng.
It is now possible to deserialize tuple enum variants, using tags to choose the variant. This is compatible with serde_yaml and serde_yaml_ng.
#[derive(Debug, PartialEq, Eq, Deserialize)]
pub enum Value {
Expression(String),
Pair(String, i32),
}
#[derive(Debug, PartialEq, Eq, Deserialize)]
pub struct Context {
value: Value,
}
serde_saphyr::from_str::<Context>(yaml) would take the value: !Expression 1 + 1 or value: !Pair [a, 12]. Nesting using Variant:\n ... already worked, but that syntax is inconvenient for short scalars that would otherwise fit on a single line.
Tuple members can differ in type, so Rust tuple agrees with YAML list here better than Rust list or array.
We now emit list items with a more compact indentation style:
containers:
- env:
- name: METHOD
value: WATCH
Compared to a more expanded indentation style:
containers:
- env:
- name: METHOD
value: WATCH
Round trip tests were added to check we still produce a valid YAML. This more compact format used to be default in serde-yaml. If the previous format is desired (like it there are tests with direct string comparison), it can be returned by setting compact_list_indent to false in SerializerOptions.
In this release, we primarily focused on improving code coverage. While adding more tests, we uncovered a couple of bugs. Although these are edge case
In this release, we primarily focused on improving code coverage. While adding more tests, we uncovered a couple of bugs. Although these are edge cases, we decided to publish a new release.
"garde", "validator", "figment", "miette", "robotics" are removed from default features again and must be explicitly enabled. These features were brie
If you depend on these features, they can be easily enabled by listing them (ideally only the ones you need) in Cargo.toml:
[features]
default = ["garde", "validator", "figment", "miette", "robotics"]
This release introduces a major overhaul of the error reporting system. Default messages remain developer oriented: they do not just report invalid YA
This release introduces a major overhaul of the error reporting system. Default messages remain developer oriented: they do not just report invalid YAML, they assist the developer in adopting and integrating the crate. They may mention recommended API, comment on data structures, parsing settings, something the end user has no clue about. To produce user-facing messages instead, it is now possible to switch into UserMessageFormatter, or produce the custom formatter with full control over the message rendering. See the new pirate_formatter example for control over rendering.
Errors are no longer pre-formatted strings. Instead, they retain structured data and can be rendered lazily using the new MessageFormatter trait.
UserMessageFormatter: A built-in formatter that produces friendly, end-user-facing messages (hiding internal parser details).Localizer: A new trait allowing full customization of error prefixes, labels (e.g., "defined at"), and message text, enabling internationalization (i18n).Other changes
Zero-Copy from Bytes. The from_slice_with_options function has been generalized to support borrowing from the input byte slice. The function signature was updated to fn from_slice_with_options<'de, T>(bytes: &'de [u8], ...). This is generally backward compatible but allows T to borrow from bytes.
miette : - to_miette_report now generates rich diagnostics that respect your custom MessageFormatter.
Error type: The Error enum has changed significantly internally to support the new features. Pattern matching on Error variants usually requires non_exhaustive handling (which was already true), but some variant fields have changed.
smallvec 1.x: The internal dependency on smallvec was moved from 2.0.0-alpha to the long-standing stable 1.x series. While 2.0.0-alpha has worked reliably for us, it has remained in alpha for an extended period, and keeping an alpha crate in the dependency tree is undesirable. Versions in the range >= 1.0.0, < 1.16.0 have been tested and confirmed to work, so the dependency constraint has been widened accordingly. This change does not affect the public API.
We acknowledge that introducing #[non_exhaustive] is itself a formally breaking change; however, since the crate is still in the 0.0.x series, we cons…
serde-saphyr now supports zero-copy deserialization for string fields when using from_str or from_slice. This allows deserializing into &str fields that borrow directly from the input, avoiding allocation overhead.
use serde::Deserialize;
#[derive(Debug, Deserialize)]
struct Data<'a> {
name: &'a str,
value: i32,
}
let yaml = "name: hello\nvalue: 42\n";
let data: Data = serde_saphyr::from_str(yaml).unwrap();
assert_eq!(data.name, "hello");
Borrowing works for any scalar whose parsed value exists verbatim in the input. If this is not the case, use Cow<str> instead of &str. Reader-based entry points (from_reader) require DeserializeOwned and cannot return borrowed values.
For maximum flexibility, use Cow<'a, str> which borrows when possible and owns when transformation is required.
a[b], -one or a,b,c are clear and valid as unquoted scalars.n, no, off, etc.) are quoted by default, but this can be turned off by setting yaml_12 to true in serializer options. We found the quoting of the key 'y ' (as a coordinate - x, y, z) unnecessarily distracting.#[non_exhaustive]. This requires downstream code to include a wildcard (_) arm when matching on these enums, allowing us to add new variants in future releases without breaking user code. We acknowledge that introducing #[non_exhaustive] is itself a formally breaking change; however, since the crate is still in the 0.0.x series, we consider this the right time to make this adjustment.Options, SerializerOptions, and Budget structures should also now be created by macros:let options = serde_saphyr::options! {
budget: serde_saphyr::budget! {
max_documents: 2,
},
duplicate_keys: DuplicateKeyPolicy::LastWins,
};
Otherwise, we would need to incremente major version number - breaking changes - every time we add a field to these structures, and we do often. Adding #[non_exhaustive] makes them impossible to construct directly anyway, so some other approach must be tried. We decided to use macros. The old usage is still permitted but should be considered deprecated right now. We will add deprecation annotations in the next release, and the macro approach will be the only one in the first 1.x.x release. #[non_exhaustive] will be placed at this point.
This release fixes #56, problems with non-ASCII characters. More tests have been added to support non-ASCII.
deserialize_with (#58).from_reader incorrectly claiming it reads all content into memory that it was last doing many releases behind.Serde-saphyr now supports recursive YAML structures (see example). While such recursion is not common and can only be implemented with references, this is not very obviously against the specs and we have seen people asking to implement this because YAML exist arround that must be parsed.
hello:
world: this is a string
--- still a string
The change is well contained and does not break anything in ours or saphyr-parser test suites.
This release uses slightly modifed saphyr parser saphyr-parser-bw with few tweaks that allow to fix the last corner cases of yaml-test-suite. All test
This release uses slightly modifed saphyr parser saphyr-parser-bw with few tweaks that allow to fix the last corner cases of yaml-test-suite. All test suite cases no exceptions have now been converted into Rust test cases and pass.
Auto-quoting of numerically looking values has been improved, now correctly quoting values representing very large numbers outside the YAML data type representation ranges (attempt just to parse them would result an error, but they are valid numbers).
We also relaxed rules on the indentation of the closing bracket:
a: [1,2,3
4,5,6
] # <-- this closing bracket is not sufficiently indented
is invalid YAML. However, we received multiple bug reports and user complaints about rejecting this input, likely because many other YAML parsers accept it. After careful consideration, the serde-saphyr team decided to support this case for compatibility reasons.
This release also contains the fix of #53 (enum holding struct).
ryu was replaced by zmij that may be up to 3.5x faster. Some YAML documents like scientific measurements or robot calibrations are mostly lots of floa
3.0e+18 and not 3e+18 or 3e18. Some parsers (such as PyYAML, go-yaml, and Psych) do not see 3e18 as a number.This release aims to make serde-saphyr more interoperable with other crates in the Rust ecosystem.
This release aims to make serde-saphyr more interoperable with other crates in the Rust ecosystem.
Next to existing garde integration, it also supports validator, and snippets can optionally be rendered with miette (while retaining native snippet support).
Serializer and Deserializer are now public (due to how it's implemented, Deserializer is available in the closure only).
Main binary executable adapted for validation and should work well in this capacity: it now prints exceprts showing YAML problems, also returns non zero error code for invalid YAML (0 for valid).
This release integrates `garde` to run declarative validation. Indeed, many YAML errors are not kind of "invalid YAML" but rather "valid YAML, still i
This release integrates garde to run declarative validation. Indeed, many YAML errors are not kind of "invalid YAML" but rather "valid YAML, still invalid value". garde is fast evolving framework with rich set of validation tools. If inconsistency would be found, serde-saphyr error will print the snippet right from the YAML document, providing location information. If the invalid value comes from the YAML anchor, serde-saphyr will also tell where this anchor has been defined. Snippets are also now printed for syntax errors.
Common Serde renames made to follow naming conventions (case changes, snake_case, kebab-case, r# stripping) are supported, as long as they do not introduce ambiguity. Arbitrary renames are not. Parsing and validation will still work, but error messages for arbitrarily renamed fields only tell Rust path. The integration of garde is gated by the Cargo feature garde (disabled by default, use serde_saphyr = { version = "0.0.12", features = ["garde"] } in Cargo.toml to enable it).
Also
struct KeyString(String) ).This release includes serialization extensions we need for Verdanta project. If fixes and adjusts possibility to comment on scalars and anchor referen
This release includes serialization extensions we need for Verdanta project. If fixes and adjusts possibility to comment on scalars and anchor references with Commented wrapper.
To improve readability, strings, containing line feed characters, and very long strings (threshold configurable) are now automatically serialized as block scalars.
To make setting the budget easier, serde-saphyr main is not the exacutable that takes the YAML file path and, upon parsing, prints the consumed budget. Options now has the optional handle for budget reporting.
From this release, tagged enums (shape: !!Shape SQUARE") are also supported, even if, unlike simple enum forms (shape: SQUARE) they cannot map to to nested enums. This is more for supporting legacy configurations. If you need this in the output, set tagged_enums = true in SerializerOptions.
Empty maps are now serialized as {} and empty lists as [] . This remains valid YAML and is often seen as more readable then : hanging to nowhere, also some deserializers deserialize "haning emptiness" as null rather than empty map or array. The concept matches Go's gopkg.in/yaml.v3
Finally, while there have never been a working unsafe keyword in this project, since this version we add #![forbid(unsafe_code)] to the top of lib.rs, also including corresponding badge in README.
This release includes a small fix in the serializer, as well as clarifications and rewrites in the README.md after noticing some common misunderstandi
This release includes a small fix in the serializer, as well as clarifications and rewrites in the README.md after noticing some common misunderstandings in recent discussions. It also marks the completion of the yaml-test-suite conversion: all tests from the suite have now been translated into Rust test cases and integrated. The vast majority pass, while the few remaining failures are extreme corner cases.
Earlier releases generated multiple bug reports, RFEs (now resolved), and even pull requests. In contrast, things have now settled down, which likely indicates that no major burning issues remain. The library will of course be updated whenever fixes are needed, and also when saphyr-parser receives an update (it is currently at version 0.0.6 and about six months old). However, from this point onward we expect development to stabilize, with longer intervals between releases.
Nothing published for this version
This release incorporates all fixes made in response to feedback on version 0.0.7, including improvements to null-to-string deserialization, indentati
This release incorporates all fixes made in response to feedback on version 0.0.7, including improvements to null-to-string deserialization, indentation of nested structures during serialization, proper quoting of map keys, and corrections to the ? operator in the reader.
It also includes a rewrite of the stream reader, introducing the methods serde_saphyr::read and serde_saphyr::read_with_options, which parse streams directly into an iterator. This iterator can yield documents (and enforce the budget) before the entire stream has been loaded into memory, protecting against memory-exhaustion attacks caused by extremely large or trivial inputs (for example, an all-zero stream). The release further includes performance enhancements and extensive new tests.
Nothing published for this version
0.0.7 adds identity-preserving deserialization of anchors, if YAML anchors match RcAnchor or ArcAnchor wrappers on the structure. Values resolved with
0.0.7 adds identity-preserving deserialization of anchors, if YAML anchors match RcAnchor or ArcAnchor wrappers on the structure. Values resolved with the same anchor will point with shared references, restoring the original data graph. This is important when the graph is part of the information communicated by YAML. Please take a look at the graph_swiss_trains.rs example.
This release also fixes issues submitted by the community against 0.0.6:
This release adds feature-gated "robotics" capability enables parsing of YAML extensions commonly used in robotics (ROS, ROS2, etc.) These extensions
This release adds feature-gated "robotics" capability enables parsing of YAML extensions commonly used in robotics (ROS, ROS2, etc.) These extensions support conversion functions (deg, rad) and simple mathematical expressions such as deg(180), rad(pi), 1 + 2*(3 - 4/5), or rad(pi/2). This capability is gated behind the [robotics] feature and is not enabled by default. But now rs-opw-kinematics can use the library.
While the first versions only had a deserializer in scope, since 0.0.5, a serializer has also been provided. This puts the package on an equal set of
While the first versions only had a deserializer in scope, since 0.0.5, a serializer has also been provided. This puts the package on an equal set of basic features as most of the other "serde-yaml kind" libraries.
Serializer supports emitting anchors** (Rc, Arc, Weak) if they are appropriately wrapped (see below).
This is the initial release, marking the point at which we also implemented merge keys and parsing into an abstract JSON value, in case someone needs
This is the initial release, marking the point at which we also implemented merge keys and parsing into an abstract JSON value, in case someone needs abstract structures. Since this point, the deserializer appears to be more or less feature-complete, retaining the speed advantage that comes from direct parser-to-Serde deserialization without intermediate values.
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per month.