jmespath.rs

jmespath is the official Rust crate implementing JMESPath, a widely adopted query language for JSON. It lets you compile expressions like foo.bar | baz once and reuse them to search, filter, and reshape structured data without hand-writing traversal code.

Built on serde, it accepts anything implementing ToJmespath (including serde_json::Value and your own Serialize types) as input and returns reference-counted Variable results. A pluggable Runtime ships every builtin JMESPath function and lets you register custom functions, while feature flags let you share compiled expressions across threads or opt into specialization for faster code.

What You Get

• A compile() entry point that turns a JMESPath string into a reusable, cloneable Expression
• serde integration so serde_json::Value and any Serialize type can be searched without manual conversion
• A pluggable Runtime with all builtin JMESPath functions plus registration of custom functions
• Reference-counted Variable results with ergonomic accessors (as_string, as_boolean, and more)
• Feature flags for thread-safe (sync) expression sharing and specialized performance tuning

Common Use Cases

• Extracting specific fields from large or deeply nested JSON API responses
• Filtering and projecting arrays of records with a single declarative expression
• Letting users supply their own query strings to slice application data at runtime
• Reshaping JSON payloads in data pipelines and CLI tools without bespoke parsing code

Under The Hood

Architecture — The crate follows a classic query-engine pipeline: lexer.rs tokenizes an expression string, parser.rs builds an abstract syntax tree defined in ast.rs, and interpreter.rs walks that AST against an input Variable (variable.rs) to produce a search result. Function dispatch is handled by a Runtime (runtime.rs) that owns a registry of builtin and custom functions from functions.rs, and compile() bundles the parsed AST with a shared runtime into a reusable Expression. Errors flow through a unified JmespathError type in errors.rs.

Tech Stack — Written in Rust on the 2024 edition and organized as a Cargo workspace containing the jmespath library and a jmespath-cli binary. Its only runtime dependencies are serde and serde_json, keeping the dependency surface minimal; a build.rs script generates benchmark and compliance test harnesses at build time.

Code Quality — The library is well tested, combining inline unit tests across the lexer, parser, variable, and error modules with a compliance suite under jmespath/tests/ that runs the shared JMESPath specification test cases. Errors are modeled explicitly with Result and a structured JmespathError/ErrorReason hierarchy rather than panics, and documentation examples double as doctests.

API Design — The public surface is small and ergonomic: jmespath::compile(expr).search(data) covers the common path, while advanced users drop down to a custom Runtime to register functions. serde integration removes most explicit coercion, and cargo feature flags (sync, specialized) expose thread-safety and performance trade-offs without complicating the default experience.