XavierJefferson.JsonPathParser 1.0.1.101

JsonPathParser

A .NET domain specific language for reading JSON documents.

This library is a .NET port of Jayway JsonPath, which is a Java port of Stefan Goessner JsonPath implementation.

Getting Started

This library is available at the Central Maven Repository. Maven users add this to your POM.

If you need help ask questions at Stack Overflow. Tag the question 'jsonpath' and 'C#'.

JsonPath expressions always refer to a JSON structure in the same way as XPath expression are used in combination with an XML document. The "root member object" in JsonPath is always referred to as $ regardless if it is an object or array.

JsonPath expressions can use the dot-notation

$.store.book[0].title

or the bracket-notation

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

Operators

Functions

Functions can be invoked at the tail end of a path - the input to a function is the output of the path expression. The function output is dictated by the function itself.

Filter Operators

Filters are logical expressions used to filter arrays. A typical filter would be [?(@.age > 18)] where @ represents the current item being processed. More complex filters can be created with logical operators && and ||. string literals must be enclosed by single or double quotes ([?(@.color == 'blue')] or [?(@.color == "blue")]).

Path Examples

Given the JSON

{
    "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
        }
    },
    "expensive": 10
}

Reading a Document

The simplest most straight forward way to use JsonPath is via the static read API, using the Read method with generic arguments:

string json = "...";

var authors = JsonPath.Read<List<string>>(json, "$.store.book[*].author");

If you only want to read once this is OK. In case you need to read an other path as well this is not the way to go since the document will be parsed every time you call JsonPath.Read<T>(...). To avoid the problem you can parse the JSON first.

string json = "...";
var document = Configuration.DefaultConfiguration.JsonProvider.Parse(json);

var author0 = JsonPath.Read<string>(document, "$.store.book[0].author");
var author1 = JsonPath.Read<string>(document, "$.store.book[1].author");

JsonPath also provides a fluent API. This is also the most flexible one.

string json = "...";

ReadContext ctx = JsonPath.Parse(json);

List<string> authorsOfBooksWithISBN = ctx.Read<List<string>>("$.store.book[?(@.isbn)].author");


List<Dictionary<string, object??>> expensiveBooks = JsonPath
                            .Using(configuration)
                            .Parse(json)
                            .Read<List<Dictionary<string, object??>>("$.store.book[?(@.price > 10)]");

What is Returned When?

When using JsonPath in .NET, it's important to know what type you expect in your result. JsonPath will automatically try to cast the result to the type expected by the invoker.

//Will throw an InvalidCastException    
var list = JsonPath.Parse(json).Read<List<string>>("$.store.book[0].author");

//Works fine
var author = JsonPath.Parse(json).Read<string>("$.store.book[0].author");

When evaluating a path you need to understand the concept of when a path is definite. A path is indefinite if it contains:

• .. - a deep scan operator
• ?(<expression>) - an expression
• [<number>, <number> (, <number>)] - multiple array indexes

Indefinite paths always returns a list (as represented by current JsonProvider).

You can map your JsonPath output directly into POCO's.

Book book = JsonPath.Parse(json).Read<Book>("$.store.book[0]");

List<string> titles = JsonPath.Parse(JSON_DOCUMENT).Read<List<string>>("$.store.book[*].title");

Predicates

There are three different ways to create filter predicates in JsonPath.

Inline Predicates

Inline predicates are the ones defined in the path.

var books =  JsonPath.Parse(json).Read<List<Dictionary<string, object?>>>("$.store.book[?(@.price < 10)]");

You can use && and || to combine multiple predicates [?(@.price < 10 && @.category == 'fiction')] , [?(@.category == 'reference' || @.price > 10)].

You can use ! to negate a predicate [?(!(@.price < 10 && @.category == 'fiction'))].

Filter Predicates

Predicates can be built using the Filter API as shown below:

IJsonProvider jsonProvider = ...;
var cheapFictionFilter = Filter.Create(
   Criteria.Where(jsonProvider, "category").Is("fiction").And("price").Lte(10d)
);

List<Dictionary<string, object?>> books =  
   JsonPath.Parse(json).Read<List<Dictionary<string, object?>>>("$.store.book[?]", cheapFictionFilter);

Notice the placeholder ? for the filter in the path. When multiple filters are provided they are applied in order where the number of placeholders must match the number of provided filters. You can specify multiple predicate placeholders in one filter operation [?, ?], both predicates must match.

Filters can also be combined with 'OR' and 'AND'

IJsonProvider jsonProvider = ...;
var fooOrBar = Filter.Create(
   Criteria.Where(jsonProvider, "foo").Exists(true)).Or(Criteria.Where(jsonProvider, "bar").Exists(true)
);
   
var fooAndBar = Filter.Create(
   Criteria.Where(jsonProvider, "foo").Exists(true)).And(Criteria.Where(jsonProvider, "bar").Exists(true)
);

Roll Your Own

Third option is to implement your own predicates. You can either use the IPredicate interface directory, or use the SimplePredicate class.

IPredicate booksWithISBN = new SimplePredicate(ctx=> ctx.GetItem<IDictionary<string, object?>>().ContainsKey("isbn"));

var books = 
   reader.Read<List<Dictionary<string, object?>>>("$.store.book[?].isbn", booksWithISBN);

Path vs Value

In the Goessner implementation a JsonPath can return either Path or Value. Value is the default and what all the examples above are returning. If you rather have the path of the elements our query is hitting this can be achieved with an option.

Configuration conf = Configuration.CreateBuilder()
   .WithOptions(ConfigurationOptionEnum.AsPathList).Build();

List<string> pathList = JsonPath.Using(conf).Parse(json).Read<List<string>>("$..author");

Assert.Contains("$['store']['book'][0]['author']", pathList);
Assert.Contains("$['store']['book'][1]['author']", pathList);
Assert.Contains("$['store']['book'][2]['author']", pathList);
Assert.Contains("$['store']['book'][3]['author']", pathList);

Set a value

The library offers the possibility to set a value.

string newJson = JsonPath.Parse(json).Set("$['store']['book'][0]['author']", "Paul").JsonString;

Tweaking Configuration

Options

When creating your Configuration there are a few option flags that can alter the default behavior.

ConfigurationOptionEnum.DefaultPathLeafToNull

This option makes JsonPath return null for missing leafs. Consider the following JSON

[
   {
      "name" : "john",
      "gender" : "male"
   },
   {
      "name" : "ben"
   }
]

Configuration conf = Configuration.DefaultConfiguration;

//Works fine
var gender0 = JsonPath.Using(conf).Parse(json).Read<string>("$[0]['gender']");
//PathNotFoundException thrown
var gender1 = JsonPath.Using(conf).Parse(json).Read<string>("$[1]['gender']");

Configuration conf2 = conf.AddOptions(ConfigurationOptionEnum.DefaultPathLeafToNull);

//Works fine
var gender0 = JsonPath.Using(conf2).Parse(json).Read<string>("$[0]['gender']");
//Works fine (null is returned)
var gender1 = JsonPath.Using(conf2).Parse(json).Read<string>("$[1]['gender']");

ConfigurationOptionEnum.AlwaysReturnList

This option configures JsonPath to return a list even when the path is definite.

Configuration conf = Configuration.DefaultConfiguration;

//Exception thrown
var genders0 = JsonPath.Using(conf).Parse(json).Read<List<string>>("$[0]['gender']");

Configuration conf2 = conf.AddOptions(ConfigurationOptionEnum.AlwaysReturnList);

//Works fine
var genders0 = JsonPath.Using(conf2).Parse(json).Read<List<string>>("$[0]['gender']");

ConfigurationOptionEnum.SuppressExceptions This option makes sure no exceptions are propagated from path evaluation. It follows these simple rules:

• If option ConfigurationOptionEnum.AlwaysReturnList is present an empty list will be returned
• If option ConfigurationOptionEnum.AlwaysReturnList is NOT present null returned

ConfigurationOptionEnum.RequireProperties This option configures JsonPath to require properties defined in path when an indefinite path is evaluated.

Configuration conf = Configuration.DefaultConfiguration;

//Works fine
var genders = JsonPath.Using(conf).Parse(json).Read<List<string>>("$[*]['gender']");

Configuration conf2 = conf.AddOptions(ConfigurationOptionEnum.RequireProperties);

//PathNotFoundException thrown
var genders = JsonPath.Using(conf2).Parse(json).Read<List<string>>("$[*]['gender']");

IJsonProvider interface

JsonPath is shipped to internally use two different JSON serializers, implemented as interface IJsonProvider:

• SystemTextJsonProvider (default)
• NewtonsoftJsonProvider

The behaviors of these two serializers are slightly different. SystemTextJsonProvider is configured with AllowTrailingCommas = true, PropertyNameCaseInsensitive = true, whereas NewtonsoftJsonProvider is configured with the defaults for Newtonsoft.Json.

Changing the configuration defaults as demonstrated should only be done when your application is being initialized. Changes during runtime is strongly discouraged, especially in multi threaded applications.

Configuration.SetDefaults(new DefaultsImpl(new NewtonsoftJsonProvider(), new NewtonsoftJsonMappingProvider(), new HashSet<ConfigurationOptionsEnum>());

ICache interface

The interface ICache allows API consumers to configure path caching in a way that suits their needs. The cache must be configured before it is accesses for the first time or a JsonPathException is thrown. JsonPath ships with a single cache implementation that uses thread-safe System.Runtime.Caching, but you can replace it with your own:

ICache myCacheProvider = new MyCacheImplementation();

CacheProvider.Cache = myCacheProvider;

ILog interface

The interface ILog allows API consumers to configure logging in a way that suits their needs. The default setting returns an instance of a class called EmptyLogger that doesn't do anything, but you can replace it with your own:

LoggerFactory.Logger = (type) => {
    return new MyLogImplementation(type);
};