Crate rsonpath_syntax

Complete, fast, and fully spec-compliant JSONPath query parser.

The crate exposes the JsonPathQuery type and the parse function that converts a query string into the AST representation. The parsing complies with the proposed JSONPath RFC specification.

A JSONPath query is a sequence of segments, each containing one or more selectors. There are two types of segments:

• child (Segment::Child), and
• descendant (Segment::Descendant);

and five different types of selectors:

• name (Selector::Name),
• wildcard (Selector::Wildcard),
• index (Selector::Index),
• slice (Selector::Slice),
• and filter (Selector::Filter).

Descriptions of each segment and selector can be found in the documentation of the relevant type in this crate, while the formal grammar is described in the RFC.

State of the crate

This is an in-development version that does not yet support functions in filter expressions. However, all other constructs are fully supported, tested, and fuzzed. The planned roadmap is:

• support slices
• support filters (without functions)
• support functions (including type check)
• polish the API
• 1.0.0 stable release

Examples

To create a query from a query string:

use rsonpath_syntax::prelude::*;
let query_string = "$..phoneNumbers[*].number";
let query = rsonpath_syntax::parse(query_string)?;

// Query structure is a linear sequence of segments:
// Descendant '..phoneNumbers', child wildcard, child 'number'.
assert_eq!(query.segments().len(), 3);
assert_eq!(
  query.segments()[0],
  Segment::Descendant(
    Selectors::one(
      Selector::Name(
        JsonString::new("phoneNumbers")
))));
assert_eq!(
  query.segments()[1],
  Segment::Child(
    Selectors::one(
      Selector::Wildcard
)));
assert_eq!(
  query.segments()[2],
  Segment::Child(
    Selectors::one(
      Selector::Name(
        JsonString::new("number")
))));

// Queries stringify to a canonical representation.
assert_eq!(query.to_string(), "$..['phoneNumbers'][*]['number']");

Constructing queries programmatically is more ergonomic with the provided builder interface. For example, to construct the same query as above:

use rsonpath_syntax::builder::JsonPathQueryBuilder;

let mut query_builder = JsonPathQueryBuilder::new();
query_builder
  .descendant_name("phoneNumbers")
  .child_wildcard()
  .child_name("number");
let query = query_builder.into_query();

assert_eq!(query.to_string(), "$..['phoneNumbers'][*]['number']");

Crate features

There are two optional features:

• arbitrary, which enables a dependency on the arbitrary crate to provide Arbitrary implementations on query types; this is used e.g. for fuzzing.
• color, which enables a dependency on the owo_colors crate to provide colorful Display representations of ParseError; see ParseError::colored.

Modules

builder

Utility for building a JsonPathQuery programmatically.

error

Error types for the crate.

num

JSON number types expressible in a JSONPath query.

prelude

Public reexports of the JSONPath query object model, parsing and building entrypoints.

str

JSON string types expressible in a JSONPath query.

Structs

ComparisonExpr

Comparison based on two singular values and a comparison operator.

JsonPathQuery

JSONPath query structure represented by a sequence of Segments.

Parser

JSONPath query parser.

ParserBuilder

Configurable builder for a Parser instance.

Selectors

Collection of one or more Selector instances.

SingularJsonPathQuery

Singular JSONPath query.

Slice

Slice selector defining the start and end bounds, as well as the step value and direction.

Enums

Comparable

One of the sides of a ComparisonExpr, either a constant literal or a singular JSONPath query.

ComparisonOp

Comparison operator usable in a ComparisonExpr.

Index

Directional index into a JSON array.

Literal

JSON literal value available in comparison expressions of a filter selector.

LogicalExpr

Logical expression used in a Filter selector.

Segment

JSONPath query segment.

Selector

Each Segment defines one or more selectors. A selector produces one or more children/descendants of the node it is applied to.

SingularSegment

Segment allowed in a SingularJsonPathQuery.

Step

Directional step offset within a JSON array.

TestExpr

Existence test based on a relative or absolute JsonPathQuery.

Functions

parse

Parse a JSONPath query string using default Parser configuration.

Type Aliases

Result

Convenience alias for Result values returned by this crate.