Noyalib

noyalib

A YAML 1.2 parser and serialiser for Rust, with full serde integration and zero unsafe code.

---

Contents

Getting started

• [Install](#install) — Cargo, source
• [Quick Start](#quick-start) — parse and serialise in ten lines

The noyalib ecosystem (library + four satellite crates)

• [The noyalib ecosystem](#the-noyalib-ecosystem) — noyalib, noya-cli, noyalib-lsp, noyalib-mcp, noyalib-wasm at a glance

Library reference

• [One-minute migration from serde_yaml (and the wider ecosystem)](#one-minute-migration-from-serde_yaml-and-the-wider-ecosystem) — name-for-name mapping for serde_yaml 0.9, serde_yml, yaml_serde, serde-yaml-ng, serde-norway, serde-yaml-bw, serde-saphyr, yaml-spanned
• [Why this approach?](#why-this-approach) — design rationale
• [Capabilities in 0.0.1](#capabilities-in-001) — release inventory
• [Two APIs, one parser](#two-apis-one-parser) — data binding vs. tooling
• [Ecosystem comparison](#ecosystem-comparison) — short matrix; full table at [doc/COMPARISON.md](doc/COMPARISON.md)
• [Benchmarks](#benchmarks) — headline numbers; full table at [doc/BENCHMARKS.md](doc/BENCHMARKS.md)
• [Features](#features) — module-level capability list
• [Custom tags ("just data")](#custom-tags-just-data) — Value::Tagged, untag, registry
• [Library Usage](#library-usage) — deserialise, serialise, values, spans
• [Configuration](#configuration) — parser and serialiser options
• [Examples](#examples) — runnable example index

Operational

• [When not to use noyalib](#when-not-to-use-noyalib) — limitations
• [Development](#development) — make targets, fuzzing, CI
• [Security](#security) — guarantees and compliance
• [Documentation](#documentation) — all reference docs
• [License](#license)

---

Install

As a Rust library (crates.io)

[dependencies]
noyalib = "0.0.11"

As a CLI tool

The noyafmt and noyavalidate binaries ship from the noya-cli companion crate (the noyalib library crate itself contains no binaries — the split keeps clap + miette + validate-schema out of the library's dependency graph for downstream embedders).

| Channel | Install | |---|---| | Cargo (crates.io) | cargo install noya-cli --locked | | Cargo (from source) | cargo install --locked --path crates/noya-cli | | Homebrew (personal tap) | brew tap sebastienrousseau/tap && brew install noyalib | | Arch Linux (AUR) | yay -S noyalib-bin (binary) or yay -S noyalib (source) | | Scoop (Windows) | scoop bucket add sebastienrousseau https://github.com/sebastienrousseau/scoop-bucket && scoop install noyalib | | Nix / NixOS | nix run github:sebastienrousseau/noyalib | | Container (GHCR) | docker run --rm ghcr.io/sebastienrousseau/noyafmt:latest --version | | npm (WASM) | npm install @sebastienrousseau/noyalib-wasm | | npm (MCP) | npx @sebastienrousseau/noyalib-mcp (no Rust toolchain needed) | | VS Code | search noyalib in the Marketplace | | Open VSX | search noyalib in open-vsx.org |

cargo install noya-cli --locked builds both binaries by default (via the noyavalidate Cargo feature). To install only the formatter and skip the schema-validation toolchain, use cargo install noya-cli --locked --no-default-features --features noyafmt.

GitHub Releases additionally publish pre-built tarballs for Linux (gnu + musl), macOS (Intel + Apple Silicon + universal), and Windows (x86_64, i686, aarch64). Each archive ships with the binaries, man pages, shell completions, license bundle, and a cosign keyless signature + SLSA L3 attestation.

See [pkg/VERIFY.md](pkg/VERIFY.md) for verification commands and [pkg/PUBLISH.md](pkg/PUBLISH.md) for the per-channel maintainer runbook.

no_std support

[dependencies]
noyalib = { version = "0.0.11", default-features = false }

Requires alloc. Core data binding (from_str, to_string, Value, schemas) and the streaming deserializer all compile and run without the standard library. from_reader, to_writer, the Spanned deserialization helper (which uses thread-local storage), and the CST module require the std feature, which is enabled by default.

Build from source

git clone https://github.com/sebastienrousseau/noyalib.git
cd noyalib
make          # check + clippy + test

MSRV by crate. Each workspace crate carries its own rust-version; CI's msrv-per-crate job (Phase 7) gates each crate independently so a satellite never silently breaks downstream users pinned to the core's floor.

| Crate | MSRV | Why | |---|---|---| | noyalib (core lib) | 1.85.0 | The committed floor since v0.0.5 (edition 2024). Enforced by the dedicated MSRV CI job. | | noyalib-mcp | 1.85.0 | Same floor; small dep tree, no transitives requiring a higher edition. | | noya-cli (binaries) | 1.85.0 | clap_builder 4.6 (a transitive of clap = "4.5") ships in edition 2024. | | noyalib-lsp | 1.85.0 | LSP transport-stack transitives (litemap, uuid) require recent stables. |

Optional core-lib features pull in ergonomics deps that have themselves bumped past 1.75 — miette → backtrace 1.82+, garde → 1.84+, validate-schema / figment → ICU chain 1.86+, parallel → rayon-core 1.80+. Use those with a current stable toolchain; the core lib stays buildable on the Ubuntu 24.04 LTS rustc-1.75 floor.

rust-toolchain.toml itself selects stable for local development; the 1.75.0 floor on the core surface is enforced by the dedicated msrv-1-75-core CI job (Ubuntu, no-default-features + default-features build paths).

Cargo features

All optional integrations are off by default. Enable only what the application needs.

| Feature | Pulls in | Adds | Documented in | | :--- | :--- | :--- | :--- | | std (default) | — | from_reader, to_writer, Spanned, CST module | [Install](#install) | | miette | miette 7 | Rich terminal diagnostics with source spans | [Library Usage](#library-usage), examples/diagnostic.rs | | schema | schemars, serde_json | JsonSchema derive + schema_for::(). Downstream callers that derive JsonSchema must add schemars = "1.2" to their own Cargo.toml — the proc-macro emits ::schemars::* paths that need to resolve in the call-site dep graph. | [Capabilities in 0.0.1](#capabilities-in-001) | | validate-schema | schema + jsonschema | validate_against_schema, coerce_to_schema | [Governance: schema-driven autofix](#governance-schema-driven-autofix) | | figment | figment 0.10 | noyalib::figment::Yaml provider | examples/figment.rs | | garde | garde 0.22 | Validated wrapper | examples/validation_garde.rs | | validator | validator 0.19 | ValidatedValidator wrapper | examples/validation_validator.rs | | robotics | — | Degrees, Radians, StrictFloat newtypes | examples/robotics_polymorphism.rs | | parallel | rayon 1.10 | noyalib::parallel::parse for ----separated streams | [Benchmarks](#benchmarks) | | recovery | — | noyalib::recovery::parse_lenient — best-effort tree + error list for LSP / IDE half-typed documents | examples/recovery_lenient.rs, benches/v006_features.rs | | sval | sval 2 | impl sval::Value for Value / Number / Mapping / MappingAny / TaggedValue, noyalib::sval_adapter::to_sval_writer | examples/sval_streaming.rs, benches/v006_features.rs | | tokio | tokio, tokio-util, bytes | noyalib::tokio_async::from_async_reader / from_async_reader_multi and YamlDecoder codec for tokio_util::codec::Framed pipelines | examples/tokio_async_reader.rs, benches/v006_features.rs | | simd | — | noyalib::simd::* primitives + parser hot path | [Benchmarks](#benchmarks) | | nightly-simd | simd (nightly toolchain) | core::simd-backed StructuralIter (32-byte chunks) | [Benchmarks](#benchmarks) | | compat-serde-yaml | — | noyalib::compat::serde_yaml shim for migration | [When not to use noyalib](#when-not-to-use-noyalib) | | lossless-u64 | — | Number::Unsigned(u64) plus opt-in parser/serializer config for scalars in (i64::MAX, u64::MAX] | [doc/adr/0004-lossless-u64-integers.md](doc/adr/0004-lossless-u64-integers.md), examples/lossless_u64.rs, benches/lossless_u64.rs | | compare-saphyr | serde-saphyr (dev only) | Cross-library bench comparison arms | benches/comparison.rs | | noyavalidate | std + miette + validate-schema | The noyavalidate CLI binary | [Tooling](#tooling) |

# Example: rich diagnostics + schema validation
[dependencies]
noyalib = { version = "0.0.11", features = ["miette", "validate-schema"] }

Optional features: lossless-u64 preserves YAML integer scalars above i64::MAX as Number::Unsigned(u64) instead of lossy f64 widening — useful for distributed-system IDs, content hashes, and timestamp fields. Enable the Cargo feature, then opt in at runtime with ParserConfig::lossless_u64_integers(true) and SerializerConfig::lossless_u64_integers(true). See [doc/adr/0004-lossless-u64-integers.md](doc/adr/0004-lossless-u64-integers.md) for rationale and migration notes.

---

Quick Start

use noyalib::{from_str, to_string};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, PartialEq)]
struct Config {
    name: String,
    port: u16,
    features: Vec,
}

fn main() -> Result {
    let yaml = "
name: myapp
port: 8080
features:
  - auth
  - api
";

    let config: Config = from_str(yaml)?;
    let output = to_string(&config)?;
    let roundtrip: Config = from_str(&output)?;
    assert_eq!(config, roundtrip);

    Ok(())
}

---

The noyalib ecosystem

Five crates ship from this workspace. The library is the core; the four satellites wrap it for specific delivery surfaces.

| Crate | What it is | Use case | |---|---|---| | noyalib | Library — YAML 1.2 parser, serializer, lossless CST, JSON Schema validator | Embed YAML support in any Rust binary or library. | | noya-cli (own repo) | Two binaries: noyafmt (formatter), noyavalidate (schema validator + autofixer) | CI gates, pre-commit hooks, ad-hoc command-line use. | | noyalib-lsp (own repo) | Language Server Protocol server | Editor integration — VS Code, Neovim, Helix, Emacs, Zed, Sublime, IntelliJ. | | noyalib-mcp (own repo) | Model Context Protocol server | LLM agent tooling — Claude Desktop, Cursor, Continue.dev, Zed assistant, mcp.run. | | noyalib-wasm (own repo) | wasm-bindgen wrapper around the library | Browser, Node, Cloudflare Workers, Deno, any WASM-capable host. |

Install the binaries

# CLI tools (noyafmt + noyavalidate)
cargo install noya-cli

# LSP server
cargo install noyalib-lsp

# MCP server
cargo install noyalib-mcp

# WASM bundle
npm install @sebastienrousseau/noyalib-wasm

Per-crate READMEs cover the surface specific to each artifact:

• CLI: [crates/noya-cli/README.md](crates/noya-cli/README.md) — flags, exit codes, recipes.
• LSP: [crates/noyalib-lsp/README.md](crates/noyalib-lsp/README.md) — capabilities, editor configs.
• MCP: sebastienrousseau/noyalib-mcp — tools, host configs (split repo since v0.0.13; strict lockstep per [ADR-0005](doc/adr/0005-workspace-split.md)).
• WASM: sebastienrousseau/noyalib-wasm — JS API, bundling (split repo since v0.0.12).

Per-host quick links

| If you use… | Drop-in config | |---|---| | VS Code / JetBrains / Neovim / Helix / Emacs / Zed / Sublime | [editor configs in noyalib-lsp/examples/](crates/noyalib-lsp/examples/) | | Claude Desktop / Cursor / Continue.dev / Zed assistant / hosted MCP | client configs (noyalib-mcp repo) | | GitHub Actions / pre-commit / Helm / Compose / pyproject-adjacent YAML | [validation gates in noya-cli/examples/](crates/noya-cli/examples/) | | Vite / Webpack / Next.js / Cloudflare Workers / Deno / Bun | bundling guide (noyalib-wasm repo) |

The rest of this README covers the library surface (noyalib itself). For the satellite crates, jump straight to their READMEs above.

---

One-minute migration from serde_yaml (and the wider ecosystem)

Most call sites are mechanical to update. The full guide — covering serde_yaml 0.9 plus every actively-published fork and adjacent crate — is [doc/MIGRATION-FROM-SERDE-YAML.md](doc/MIGRATION-FROM-SERDE-YAML.md). The headline mapping for serde_yaml 0.9 is below; the same guide has per-crate sections for serde_yml, yaml_serde, serde-yaml-ng, serde-norway, serde-yaml-bw, serde-saphyr, and yaml-spanned with verified function tables for each.

-[dependencies]
-serde_yaml = "0.9"
+[dependencies]
+noyalib = "0.0.11"

-use serde_yaml::Value;
-let v: Value = serde_yaml::from_str(input)?;
-let s        = serde_yaml::to_string(&v)?;
+use noyalib::Value;
+let v: Value = noyalib::from_str(input)?;
+let s        = noyalib::to_string(&v)?;

| serde_yaml 0.9 | noyalib | |---|---| | serde_yaml::from_str:: | noyalib::from_str:: | | serde_yaml::from_slice:: | noyalib::from_slice:: | | serde_yaml::from_reader:: | noyalib::from_reader:: | | serde_yaml::to_string | noyalib::to_string | | serde_yaml::to_writer | noyalib::to_writer | | serde_yaml::to_value | noyalib::to_value | | serde_yaml::Value | noyalib::Value (adds a 7th Tagged variant) | | serde_yaml::Mapping | noyalib::Mapping | | serde_yaml::Number | noyalib::Number | | serde_yaml::Error | noyalib::Error | | serde_yaml::with::singleton_map* | noyalib::with::singleton_map* | | (n/a) | noyalib::from_str_strict:: — error on unknown keys | | (n/a) | noyalib::Spanned — source-location wrapper | | (n/a) | noyalib::cst::Document — lossless byte-faithful edits |

If your call sites can't change at all, enable features = ["compat-serde-yaml"] and replace use serde_yaml with use noyalib::compat::serde_yaml — every type is noyalib-native, no transitive dep on the archived upstream.

Coming from a different YAML crate?

Each crate has a standalone migration guide with TL;DR diff, function-mapping table, behavioural notes, and a checklist. Crates.io state verified 2026-05-08:

| Crate | Version | Drop-in for serde_yaml? | Migration guide | |---|---|---|---| | serde_yml | 0.0.12 (archived 2025-09) | mostly | [MIGRATION-FROM-SERDE-YML.md](doc/MIGRATION-FROM-SERDE-YML.md) | | yaml_serde | 0.10.4 | yes (Cargo package = rename) | [MIGRATION-FROM-YAML-SERDE.md](doc/MIGRATION-FROM-YAML-SERDE.md) | | serde-yaml-ng | 0.10.0 | yes | [MIGRATION-FROM-SERDE-YAML-NG.md](doc/MIGRATION-FROM-SERDE-YAML-NG.md) | | serde-norway | 0.9.42 | yes | [MIGRATION-FROM-SERDE-NORWAY.md](doc/MIGRATION-FROM-SERDE-NORWAY.md) | | serde-yaml-bw | 2.5.6 | no (breaking 2.x; 8-variant Value with Alias) | [MIGRATION-FROM-SERDE-YAML-BW.md](doc/MIGRATION-FROM-SERDE-YAML-BW.md) | | serde-saphyr | 0.0.26 | no (no Value DOM, streaming-only) | [MIGRATION-FROM-SERDE-SAPHYR.md](doc/MIGRATION-FROM-SERDE-SAPHYR.md) | | yaml-spanned | 0.0.3 | no (parser-only, no to_string) | [MIGRATION-FROM-YAML-SPANNED.md](doc/MIGRATION-FROM-YAML-SPANNED.md) |

Th

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sebastienrousseau
• Source: sebastienrousseau/noyalib
• License: Apache-2.0
• Homepage: https://docs.rs/noyalib

Install and usage instructions live in the source repository linked above.