babbel_json 0.3.0

Fast, modular JSON toolkit with streaming parsers, JSON Pointer (RFC 6901), and Merge Patch
Documentation

babbel_json

Version 0.3.0 — A lightweight, modular JSON toolkit for Rust with pluggable I/O sources/destinations, a simple in-memory Node tree, multiple serializers (JSON, YAML, XML, Bencode, TOML), and no_std support. Designed for small binaries, predictable behavior, and easy embedding.

  • Core Node type representing JSON structures
  • Parser to build Node trees from streams, strings, or byte slices
  • Full JSON5 and JSONC parser (parse_json5, Json5Engine) with comments, trailing commas, single-quoted strings, unquoted keys, hex numbers
  • Zero-allocation JSON validation
  • Stringifiers to JSON, YAML, XML, Bencode, and TOML
  • Performance-optimized serialization with lazy escaping and arena allocation
  • File and in-memory buffer I/O abstractions
  • Pretty-printing utilities
  • Line-delimited JSON (JSON Lines / NDJSON / .jsonl) streaming reader and writer
  • JSON Pointer (RFC 6901), JSON Patch (RFC 6902), and JSON Merge Patch (RFC 7386)
  • JSON Schema validation (Draft 7 subset)
  • json! macro for ergonomic Node construction
  • Unicode-aware file helpers (BOM detection/handling)
  • no_std compatible with the alloc feature

Minimum supported Rust version: 1.88.0

Features at a glance

  • Node and Numeric types for representing all JSON values
  • Parse with parse, from_str, from_bytes, or parse_with_config
  • lines::JsonLinesReader — stream record-by-record without buffering entire files
  • validate_json — check syntax without building a Node tree
  • Streaming-friendly ISource/IDestination traits
  • FileSource/FileDestination and BufferSource/BufferDestination
  • Pretty printer (print) and optimized serializer (stringify_optimized)
  • Convert a Node to alternate formats (YAML, XML, Bencode, TOML)
  • JSON Pointer navigation and mutation (pointer_get, pointer_set, pointer_remove)
  • JSON Patch operations (patch::apply_operation, patch::apply_patch)
  • JSON Merge Patch (merge_patch::merge_patch)
  • JSON Schema validation (schema::SchemaValidator)
  • JSON5 comment stripping (parser::json5::strip_comments)
  • json! macro for inline Node construction
  • ParserConfig for resource limits; ParseStats for profiling
  • Unicode file format detection and read/write helpers

Cargo features

Feature Default Description
std yes Enables standard library support (includes alloc)
alloc yes (via std) Enables heap allocation without full std
file-io yes FileSource, FileDestination, and Unicode file helpers
format-yaml no to_yaml encoder
format-xml no to_xml encoder
format-bencode no to_bencode encoder
format-toml no to_toml encoder
json-pointer no JSON Pointer, JSON Patch support

no_std usage

Disable default features and enable alloc for embedded / bare-metal targets:

[dependencies]

babbel_json = { version = "0.2.0", default-features = false, features = ["alloc"] }

# Or within the workspace:

# babbel_json = { path = "crates/json", default-features = false, features = ["alloc"] }

Installation

Add to your Cargo.toml:

[dependencies]

babbel_json = "0.2.0"

Or as a workspace path dependency:

[dependencies]

babbel_json = { path = "crates/json" }

All streaming I/O in babbel_json (FileSource, FileDestination, BufferSource, Buffer) is unified with and powered by babbel_core::io.

Embedding Guide

To embed this library in another Rust project:

  1. Add the path or version dependency as shown above.
  2. Import the required items in your code:
    use babbel_json::{Node, parse, stringify};
    
  3. For comprehensive architecture and conversion pipelines across the Babbel ecosystem, refer to the Babbel Architecture Guide.

Quick start

Parse from a string or bytes

use babbel_json::{from_str, from_bytes};

let node = from_str(r#"{"name": "Alice", "age": 30}"#).unwrap();
let node = from_bytes(b"[1, 2, 3]").unwrap();

Stream Line-Delimited JSON (JSON Lines / NDJSON)

use babbel_json::lines::{JsonLinesReader, parse_json_lines, to_json_lines};
use babbel_core::io::SliceSource;

// 1. Batch parsing
let data = "{\"id\": 1}\n{\"id\": 2}\n";
let records = parse_json_lines(data).unwrap();
assert_eq!(records.len(), 2);

// 2. Stream-by-record iteration
let source = SliceSource::new(data);
let mut reader = JsonLinesReader::new(source);
while let Some(Ok(record)) = reader.next_node() {
    println!("ID: {:?}", record.get("id"));
}

// 3. Serialization
let jsonl_output = to_json_lines(&records).unwrap();

Build a Node with the json! macro

use babbel_json::{json, Node};

let value = json!({
    "name": "Alice",
    "age": 30,
    "active": true,
    "scores": [85, 92, 78]
});

assert_eq!(value["name"].as_str(), Some("Alice"));
assert_eq!(value["age"].as_i64(), Some(30));

Parse a file, then pretty-print to another file

use babbel_json::{FileSource, FileDestination, parse, print};
use std::path::Path;

fn main() -> Result<(), String> {
    let input = "data.json";
    let mut src = FileSource::new(input).map_err(|e| e.to_string())?;
    let node = parse(&mut src).map_err(|e| e.to_string())?;

    let output = Path::new(input).with_extension("pretty.json");
    let mut dst = FileDestination::new(output.to_string_lossy().as_ref())
        .map_err(|e| e.to_string())?;

    print(&node, &mut dst, 4, 0); // 4-space indentation
    Ok(())
}

Build a Node in memory and stringify to a buffer

use babbel_json::{Node, Numeric, stringify, BufferDestination};

fn main() {
    let node = Node::Object(vec![
        ("name".into(), Node::Str("example".into())),
        ("count".into(), Node::Number(Numeric::Integer(3))),
        ("items".into(), Node::Array(vec![
            Node::Boolean(true),
            Node::None,
            Node::Str("text".into())
        ])),
    ].into_iter().collect());

    let mut buf = BufferDestination::new();
    stringify(&node, &mut buf);
    println!("{}", buf.to_string());
}

Validate JSON without allocating

use babbel_json::{validate_json, BufferSource, ParserConfig};

let mut source = BufferSource::new(br#"{"valid": true}"#);
let config = ParserConfig::new();
assert!(validate_json(&mut source, &config).is_ok());

Parse with resource limits

use babbel_json::{parse_with_config, BufferSource, ParserConfig};

let config = ParserConfig {
    max_depth: Some(16),
    max_string_length: Some(1024),
    max_array_size: Some(256),
    max_object_size: Some(64),
};
let mut src = BufferSource::new(b"{}");
let node = parse_with_config(&mut src, &config).unwrap();

Convert a Node to YAML / XML / Bencode

use babbel_json::{Node, Numeric, to_yaml, to_xml, to_bencode, BufferDestination};

let node = Node::Array(vec![
    Node::Number(Numeric::Integer(1)),
    Node::Number(Numeric::Integer(2)),
    Node::Number(Numeric::Integer(3)),
]);

let mut yaml = BufferDestination::new();
to_yaml(&node, &mut yaml);
println!("YAML:\n{}", yaml.to_string());

let mut xml = BufferDestination::new();
to_xml(&node, &mut xml);
println!("XML:\n{}", xml.to_string());

let mut bencode = BufferDestination::new();
to_bencode(&node, &mut bencode);
println!("Bencode:\n{}", bencode.to_string());

JSON Pointer (RFC 6901)

use babbel_json::{json, pointer_get, pointer_set};

let mut doc = json!({"users": [{"name": "Alice"}, {"name": "Bob"}]});

// Read a value
let name = pointer_get(&doc, "/users/0/name");
assert_eq!(name.and_then(|n| n.as_str()), Some("Alice"));

// Write a value
pointer_set(&mut doc, "/users/1/name", json!("Charlie")).unwrap();

JSON Patch (RFC 6902)

use babbel_json::{json, nodes::patch::{apply_patch, PatchOp}};

let mut doc = json!({"a": 1, "b": 2});
let ops = vec![
    PatchOp::Add { path: "/c".into(), value: json!(3) },
    PatchOp::Remove { path: "/b".into() },
];
apply_patch(&mut doc, &ops).unwrap();
// doc is now {"a": 1, "c": 3}

JSON Merge Patch (RFC 7386)

use babbel_json::{json, nodes::merge_patch::merge_patch};

let mut doc = json!({"a": 1, "b": 2});
let patch = json!({"b": 3, "c": 4});
merge_patch(&mut doc, &patch);
// doc is now {"a": 1, "b": 3, "c": 4}

JSON Schema validation

use babbel_json::{json, nodes::schema::SchemaValidator};

let schema = json!({
    "type": "object",
    "required": ["name"],
    "properties": {
        "name": {"type": "string"},
        "age":  {"type": "number", "minimum": 0}
    }
});
let validator = SchemaValidator::new(schema);

assert!(validator.validate(&json!({"name": "Alice", "age": 30})).is_ok());
assert!(validator.validate(&json!({"age": 30})).is_err()); // missing "name"

JSON5 comment stripping

use babbel_json::parser::json5::strip_comments;

let input = r#"{
    "name": "Alice", // single-line comment
    /* multi-line
       comment */
    "age": 30
}"#;
let clean = strip_comments(input);
let node = babbel_json::from_str(&clean).unwrap();

Read/write text files with Unicode BOM handling

use babbel_json::{Format, detect_format, read_file_to_string, write_file_from_string};

fn main() -> Result<(), String> {
    let fmt = detect_format("input.txt").unwrap_or(Format::UTF8);
    let content = read_file_to_string("input.txt")?;
    write_file_from_string("output.txt", &content, Format::UTF8)
}

API overview

Version

  • version() -> &'static str

I/O

  • FileSource / FileDestination — file-backed I/O (requires file-io feature)
  • BufferSource / BufferDestination — in-memory I/O

Node model

  • Node: Object, Array, Str, Number(Numeric), Boolean, None
  • Numeric: Integer(i64), UInteger(u64), Float(f64), Byte(u8), Int8(i8), Int16(i16), UInt16(u16), Int32(i32), UInt32(u32)

Parsing

  • parse(&mut Source) -> Result<Node, String>
  • parse_with_config(&mut Source, &ParserConfig) -> Result<Node, String>
  • from_str(&str) -> Result<Node, String>
  • from_bytes(&[u8]) -> Result<Node, String>
  • validate_json(&mut Source, &ParserConfig) -> Result<(), String> — zero-allocation syntax check

Stringifying

  • stringify(&Node, &mut Destination)
  • stringify_pretty(...) — alias for print
  • print(&Node, &mut Destination, indent, current_indent) — human-readable output
  • stringify_optimized(&Node, &mut Destination) -> Result<(), String> — lazy escaping, fast paths
  • strip_whitespace(src, dst) — compact whitespace removal

Alternative format encoders (feature-gated)

  • to_yaml(&Node, &mut Destination) — requires format-yaml
  • to_xml(&Node, &mut Destination) — requires format-xml
  • to_bencode(&Node, &mut Destination) — requires format-bencode
  • to_toml(&Node, &mut Destination) — requires format-toml

JSON Pointer (requires json-pointer)

  • pointer_get(&Node, &str) -> Option<&Node>
  • pointer_get_mut(&mut Node, &str) -> Option<&mut Node>
  • pointer_set(&mut Node, &str, Node) -> Result<(), String>
  • pointer_remove(&mut Node, &str) -> Result<Node, String>

JSON Patch (requires json-pointer)

  • nodes::patch::apply_operation(&mut Node, &PatchOp) -> Result<(), PatchError>
  • nodes::patch::apply_patch(&mut Node, &[PatchOp]) -> Result<(), PatchError>
  • PatchOp: Add, Remove, Replace, Move, Copy, Test

JSON Merge Patch

  • nodes::merge_patch::merge_patch(&mut Node, &Node)

JSON Schema validation

  • nodes::schema::SchemaValidator::new(schema: Node) -> SchemaValidator
  • SchemaValidator::validate(&Node) -> Result<(), Vec<ValidationError>>

JSON5

  • parser::json5::strip_comments(&str) -> String

Parser configuration and profiling

  • ParserConfig::new() — conservative limits suitable for embedded systems
  • ParserConfig::unlimited() — no limits
  • ParseStats — peak depth, node count, string bytes, estimated memory, parse time

Unicode-aware file helpers (requires file-io)

  • detect_format(path) -> Result<Format, String>
  • read_file_to_string(path) -> Result<String, String>
  • write_file_from_string(path, &str, Format) -> Result<(), String>

json! macro

  • json!(null), json!(true), json!(42), json!("text"), json!([...]), json!({...})

Performance features

Several alloc-gated modules provide lower-overhead alternatives for hot paths:

  • parser::arena — arena allocator to reduce per-node heap allocations
  • parser::fast — SIMD-friendly fast parsing utilities
  • parser::sso — Small String Optimization for short keys and values
  • stringify::optimized::stringify_optimized — lazy escaping and batch writes

Design goals

  • Small, explicit API focused on Node-based manipulation
  • Works with streams and simple abstractions
  • Deterministic and predictable output
  • no_std compatible for embedded and constrained targets
  • Easy to integrate for CLI tools, small services, and firmware

Roadmap ideas

  • Optional parse/stringify options (e.g., key sorting, non-ASCII escaping)
  • Streaming parser and incremental writer
  • Canonical JSON and stable hashing
  • Optional serde interop and async I/O

If you're interested in any of these, contributions are welcome.

Conformance Test Results

babbel_json is continuously tested against the official JSONTestSuite for RFC 8259 compliance.

Suite Category Focus Area Total Cases Passed Failed Pass Rate Status
Parsing (y_) Mandatory acceptance of valid JSON & surrogate pairs 95 95 0 100.0% PASSED
Parsing (n_) Mandatory rejection of malformed syntax & control chars 188 188 0 100.0% PASSED
Parsing (i_) Implementation-defined edge cases & huge numbers 35 35 0 100.0% PASSED
Transform Key duplicates, escaped nulls, normalization 22 22 0 100.0% PASSED
OVERALL Full Official JSONTestSuite Corpus 340 340 0 100.0% VERIFIED

Running the Conformance Runner

# 1. Fetch test fixtures on demand

powershell -ExecutionPolicy Bypass -File scripts/fetch_json_test_suite.ps1

# On Linux/macOS: ./scripts/fetch_json_test_suite.sh


# 2. Run the 340 test cases

cargo test -p babbel_json --test nst_conformance -- --nocapture

Documentation

See the Documentation Hub for complete guides:

License

This project is licensed under the terms of the LICENSE file included in the repository.

Contributing

  • Open issues for bugs and feature requests
  • PRs with tests are welcome
  • Please format and lint your code before submitting

Support

If you run into issues or have questions, please open an issue in the repository.