Hyperbee.Json 1.0.0

JSONPath

A C# implementation of JSONPath for .NET System.Text.Json with a plugable expression selector.

Why

.NET System.Text.Json lacks support for JSONPath. The primary goal of this project is to create a JSONPath library for .NET that will

• Directly leverage System.Text.Json
• Align with the draft JSONPath Specification
  • Working Draft.
  • Editor Copy
• Function 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
• Provide a plugable model for expression script handling.

JSONPath Expressions

JSONPath expressions always refers to a JSON structure in the same way as XPath expression are used in combination with an XML document. Since a JSON structure is usually anonymous and doesn't necessarily have a root member object JSONPath assumes the abstract name $ assigned to the outer level object.

JSONPath expressions can use the dot-notation:

$.store.book[0].title

or the bracket-notation:

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

for input paths. Internal or output paths will always be converted to the more general bracket-notation.

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 of the underlying scripting language (<expr>) 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
    }
    }
}

Script Evaluators

Hyperbee.Json provides out-of-the-box expression evaluators for handling JsonPath filter selectors.

You can create your own evaluator by deriving from IJsonPathScriptEvaluator.

public class JsonPathFuncEvaluator : IJsonPathScriptEvaluator
{
    private readonly JsonPathEvaluator _evaluator;

    public JsonPathFuncEvaluator( JsonPathEvaluator evaluator )
    {
        _evaluator = evaluator;
    }

    public object Evaluator( string script, JsonElement current, string context )
    {
        return _evaluator?.Invoke( script, current, context );
    }
}

You can set a global default for the evaluator.

JsonPath.DefaultEvaluator = new JsonPathCSharpEvaluator();

Or you can wire it up through dependency injection.

public static IServiceCollection AddJsonPath( this IServiceCollection services, IConfiguration config )
{
    services.AddTransient<IJsonPathScriptEvaluator,JsonPathCSharpEvaluator>();
    services.AddTransient<JsonPath>();

    return services;
}

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.SelectPath( "$[-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 Roslyn jsonpath script 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.SelectPath( "$[?(@.key<42)]", JsonPathCSharpEvaluator.Evaluator );

// outputs 0 -1 41 41.9999

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

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.

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