serde-saphyr

Core Capabilities

• Type-driven parsing: YAML is rejected early if it doesn't match expected Rust types.
• Resource Management: Use Budget to enforce input limits (e.g., nesting depth or array size).
• Tag Support: Use the Tagged<T> wrapper to capture and emit resolved YAML tags.
• Comment Support: Use the Commented<T> wrapper to capture and emit comments.
• Include Support: Optional !include support via custom or default resolvers.
• Validation: Supports declarative validation via validator or garde crates, and advanced error reporting via miette.
• Large Documents: The huge_documents feature allows handling YAML inputs far beyond 4 GiB by using a packed 48-bit internal representation for spans.

By default, if the target field is a boolean, serde-saphyr interprets standard YAML 1.1 boolean values (e.g., true, false, yes, no).

To prevent incorrect inference (for example, when parsing into a JSON Value where you want literal strings), you can:

1. Enclose the value in quotes in the YAML source.
2. Set strict_booleans to true in your Options.

You can control how the parser handles duplicate keys in a mapping via Options. By default, duplicate keys result in an error.

Available strategies:

• First wins: Retains the first occurrence.
• Last wins: Retains the last occurrence (requires buffering).

Key behaviors for integer keys:

• YAML integer keys (e.g., 0xB and 11) are compared by their numeric meaning (within i128/u128 range) regardless of the target Rust type.
• If deserializing into a String, the original spelling is preserved (e.g., 0xB becomes "0xB").
• Quoted keys or keys tagged !!str are treated as distinct from numeric keys.
• Last wins buffering: When using LastWins with integer keys, the parser buffers the mapping to select the correct entry before passing it to Serde. Note that trailing comments and comments nested inside buffered values are not preserved in this mode.

Fuzzing targets in this repository use different input strategies:

• serialize: Uses the entire input as an untrimmed UTF-8-lossy string and attempts bounded recursive value generation. The corpus can contain readable strings, including whitespace and Unicode.
• duplicate_keys and aliases_merges: Use leading control bytes to select a scenario; the remaining bytes are used to generate values.
• document_streams: Uses five control bytes to define line endings, block style/chomping/indentation, content, blank lines, and separators, followed by up to 16 scalar selectors. Missing bytes default to zero.

Note: For structured targets like document_streams, seed files are generator inputs rather than literal YAML fixtures.

To prevent semantic errors caused by incorrect spacing, you can enforce indentation rules during deserialization using the RequireIndent enum within your Options.

Supported policies:

• Require a consistent number of indentation columns throughout the document.
• Ensure indentation is even.
• Enforce that indentation is divisible by a specific number (e.g., 4 or 6).

You can use YAML 1.1 merge keys (<<: *anchor) to reuse shared key-value pairs across multiple mappings. serde-saphyr supports this by default using MergeKeyPolicy::Merge, which expands both implicit << entries and explicit !!merge << entries.

To control this behavior, use the merge_keys option in Options:

• MergeKeyPolicy::Merge (default): Expands merge keys.
• MergeKeyPolicy::AsOrdinary: Treats merge keys as regular mapping keys.
• MergeKeyPolicy::Error: Rejects merge keys.

// Example of using merge keys to inherit properties
let yaml_input = r#"
defaults: &defaults
  adapter: postgres
  host: localhost

development:
  <<: *defaults
  database: dev_db

production:
  <<: *defaults
  database: prod_db
"#;

let parsed: Config = serde_saphyr::from_str(yaml_input).expect("Failed to deserialize");

To support recursive YAML structures (where a structure contains a reference to itself), you must use explicit wrappers to satisfy Rust's memory safety requirements:

• Wrap the recursive data in RcRecursive<T> (or ArcRecursive<T>).
• Use RcRecursion<T> (or ArcRecursion<T>) for any reference pointing to that data.

To use serde-saphyr, define a Rust struct that implements serde::Deserialize and use the serde_saphyr::from_str function to parse a YAML string directly into your type. This approach is resource-efficient as it avoids constructing an intermediate abstract value tree.

use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Config {
  name: String,
  enabled: bool,
  retries: i32,
}

fn main() {
    let yaml_input = r#"
      name: "My Application"
      enabled: true
      retries: 5
    ..."
    #;

    let config: Result<Config, _> = serde_saphyr::from_str(yaml_input);

    match config {
        Ok(parsed_config) => {
            println!("Parsed successfully: {:?}", parsed_config);
        }
        Err(e) => {
            eprintln!("Failed to parse YAML: {}", e);
        }
    }
}