Limitations
editThe library implements RFC 9535 with opt-in typed function extensions. This page lists what that leaves out, the limits that protect your application from hostile input, and the precision of number comparisons.
Other JSONPath dialects
Before RFC 9535, JSONPath was an informal syntax with many variants. Their extensions are not supported, and Parse rejects most of them:
- No script expressions:
$.book[(@.length-1)]is invalid. Write$.book[-1]. - No
.lengthproperty:$.books.lengthis valid but selects a member namedlength. Count the matches instead, or uselength()in a filter. - No other operators: no
=~,in,nin,containsor regular expression literals (/.../). Usematch()andsearch(). - No parent or property name operators (
^,~), and no filters evaluated as JavaScript or C# code: filters use the standard operators and functions only. - Only five functions by default. Domain-specific functions require an explicit custom function registry.
var document = JsonNode.Parse("""{"books":[{"title":"A"},{"title":"B"}]}""");
// .length selects a member named "length", not the length of the array
Assert.Empty(JsonPath.Parse("$.books.length").Evaluate(document));
// Count the matches instead
Assert.HasCount(2, JsonPath.Parse("$.books[*]").Evaluate(document));Filters written as [?(@.price < 10)], with parentheses, are valid RFC 9535 and work unchanged.
Other features
- Changes through paths need a
JsonNode. Set, Add and Remove change aJsonNode;JsonDocument,JsonElementand custom object models are read-only. See Set, add and remove values by path. - Streaming is lax and returns the document order. The evaluation of a stream or a
Utf8JsonReaderhas no strict mode and no JsonPathEvaluationOptions, and some queries parse more of the document than others. See Read a document without loading it. - Regular expressions are I-Regexp only.
match()andsearch()do not accept .NET-specific syntax, and^and$are not anchors. See Write the patterns.
Limits
For application-selected cancellation, work, final-match and intermediate-result limits, see Cancel or bound evaluation. These limits throw instead of silently truncating results and do not replace the structural limits below.
- Queries: filter expressions, nested filter selectors and function arguments nest up to 64 levels deep. Beyond that, Parse throws a
FormatExceptionand TryParse returnsfalse, so a hostile or generated query cannot exhaust the stack. - Documents: descendant segments (
..) and comparisons of arrays and objects visit at most 256 levels of nesting. Beyond that, evaluation throws a JsonPathEvaluationException, in both evaluation modes. Documents parsed bySystem.Text.Jsonwith its defaultMaxDepthof 64 never reach this limit; it only affects values built in code, parsed with a higherMaxDepth, or exposed by a custom navigator. - Indexes and slices: the numbers of index and slice selectors must be between -(253)+1 and 253-1, the I-JSON range; Parse rejects larger ones.
Number precision
Filters compare numbers, the literals of the query and the values of the document, by their exact value. Integers beyond 2^53, decimals with more digits than a double holds, and numbers beyond the range of a double all compare exactly:
var document = JsonNode.Parse("""{"ids":[9007199254740992,9007199254740993],"amounts":[0.1,0.10000000000000001]}""");
// Numbers that round to the same double still compare by their exact value
Assert.Equal("[9007199254740993]", JsonPath.Parse("$.ids[?@ == 9007199254740993]").Evaluate(document).ToJsonArray().ToJsonString());
Assert.Equal("[0.10000000000000001]", JsonPath.Parse("$.amounts[?@ > 0.1]").Evaluate(document).ToJsonArray().ToJsonString());- Numbers are compared as
doublevalues first. Only the numbers that round to the samedoubleare compared by their text, so the exact comparison costs nothing for most values. JsonNodevalues created from CLR numbers compare by their value: alongor adecimalexactly, afloatas thedoubleit converts to.- The numbers that functions return, such as
length()andcount(), are exact. A custom function returns adouble, which is compared exactly as it is. - A custom navigator gives the exact text of its numbers by overriding TryGetNumberText. Without it, its numbers compare as
doublevalues, and distinct numbers that round to the samedoublecompare as equal. See Custom object models.