Hyperbee.Json 1.1.0

JSONPath

JSON Path is a query language for JSON documents inspired by XPath. JSONPath defines a string syntax for selecting and extracting JSON values from within a given JSON document.

This library is a C# implementation of JSONPath for .NET System.Text.Json and System.Text.Json.Nodes.

The implementation

• Works natively with both JsonDocument (JsonElement) and JsonNode
• Can be extended to support other JSON models
• Aligns with the draft JSONPath Specification RFC 9535
  • Working Draft.
  • Editor Copy
• Functions according to the emerging consensus of use based on the majority of existing implementations; except through concious exception or deference to the RFC.
  • Parser Comparison Results
  • Parser Comparison GitHub

JSONPath Syntax

JSONPath expressions refer to a JSON structure in the same way as XPath expressions are used in combination with an XML document. JSONPath assumes the name $ is assigned to the root level object.

JSONPath expressions can use dot-notation:

$.store.book[0].title

or bracket-notation:

$['store']['book'][0]['title']

JSONPath allows the wildcard symbol * for member names and array indices. It borrows the descendant operator .. from [E4X][e4x], and the array slice syntax proposal [start:end:step] from ECMASCRIPT 4.

Expressions can be used as an alternative to explicit names or indices, as in:

$.store.book[(@.length-1)].title

using the symbol @ for the current object. Filter expressions are supported via the syntax ?(<boolean expr>), as in:

$.store.book[?(@.price < 10)].title

Below is a complete overview and a side-by-side comparison of the JSONPath syntax elements with its XPath counterparts:

Examples

Given a simple JSON structure that represents a bookstore:

{ "store": {
    "book": [
        { "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
        },
        { "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
        },
        { "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
        },
        { "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
        }
    ],
    "bicycle": {
        "color": "red",
        "price": 19.95
    }
    }
}

Code examples

A couple of trivial code examples. Review the tests for detailed examples.

Example 1 Select the last element of an array.

const string json = @"
[
  ""first"",
  ""second"",
  ""third""
]";

var document = JsonDocument.Parse( json );
var match = document.Select( "$[-1:]" ).Single();

Assert.IsTrue( match.Value.GetString() == "third" );

Example 2 Select all elemets that have a key property with a value less than 42. This example leverages bracket expressions using the default Expression jsonpath filter evaluator.

const string json = @"
[
  { ""key"": 0}, 
  { ""key"": 42}, 
  { ""key"": -1}, 
  { ""key"": 41}, 
  { ""key"": 43}, 
  { ""key"": 42.0001}, 
  { ""key"": 41.9999}, 
  { ""key"": 100}, 
  { ""some"": ""value""}
]";

var document = JsonDocument.Parse( json );
var matches = document.Select( "$[?(@.key<42)]" );

// outputs 0 -1 41 41.9999

foreach( var element in matches )
{
    Console.WriteLine( document.RootElement.GetDouble() );
};

Helper Classes

In addition to JSONPath processing, a few additional helper classes are provided to support dynamic property access, property diving, and element comparisons.

Dynamic Object Serialization

Basic support is provided for serializing to and from dynamic objects through the use of a custom JsonConverter. The DynamicJsonConverter converter class is useful for simple scenareos. It is intended as a simple helper for basic use cases only.

DynamicJsonConverter

var serializerOptions = new JsonSerializerOptions
{
    Converters = {new DynamicJsonConverter()}
};

// jsonInput is a string containing the bookstore json from the previous examples
var jobject = JsonSerializer.Deserialize<dynamic>( jsonInput, serializerOptions);

Assert.IsTrue( jobject.store.bicycle.color == "red" );

var jsonOutput = JsonSerializer.Serialize<dynamic>( jobject, serializerOptions ) as string;

Assert.IsTrue( jsonInput == jsonOutput );

Enum handling

When deserializing, the converter will treat enumerations as strings. You can override this behavior by setting the TryReadValueHandler on the converter. This handler will allow you to intercept and convert string and numeric values during the deserialization process.

Equality Helpers

Property Diving

JsonElement Helpers

Acknowlegements

This project builds on the work of:

• Stefan Gössner - Original JSONPath specification dated 2007-02-21
• Atif Aziz - .NET JSONPath
• Christoph Burgmer - Parser Consensus tests