TLio.JsonPath 1.2.0

TLio.JsonPath

Moving from Newtonsoft.Json to System.Text.Json and still need SelectToken / SelectTokens? This is a drop-in: the same JSONPath strings select the same nodes, in the same order, failing in the same places, on System.Text.Json.Nodes.JsonNode. That is not a claim, it is a test: every query in the suite is run through Newtonsoft.Json 13.0.4 and through this engine and the results must agree (≈1.8 million comparisons in the long soak).

Want the standard instead? The same engine reads RFC 9535 in full — function extensions, I-Regexp, normalized paths — and passes the official compliance suite (706 / 706). A third dialect, Extended, accepts both. No dependencies: not Newtonsoft.Json, not JsonCons, not TLio. It is the JSONPath engine behind TLio.Json.SystemText, but it is a package in its own right:

dotnet add package TLio.JsonPath

Coming from Newtonsoft — the default dialect is yours, nothing to configure:

using System.Text.Json.Nodes;
using TLio.JsonPath;

JsonNode doc = JsonNode.Parse(json)!;
var engine = JsonPathEngine.Default;                        // Newtonsoft's dialect

IReadOnlyList<JsonPathMatch> all = engine.Select("$.store.book[?(@.price < 10)].title", doc);   // ≈ SelectTokens
JsonPathMatch?               one = engine.SelectSingle("$.store.book[0].title", doc);            // ≈ SelectToken (>1 match throws)

Wanting RFC 9535:

using System.Text.Json.Nodes;
using TLio.JsonPath;

var doc = JsonNode.Parse("""
    { "store": { "book": [ { "title": "Sayings", "price": 8.95 },
                           { "title": "Sword",   "price": 12.99 } ] } }
    """);

var engine = new JsonPathEngine(new JsonPathOptions { Dialect = JsonPathDialect.Rfc9535 });

foreach (var match in engine.Select("$.store.book[?@.price < 10].title", doc))
    Console.WriteLine($"{match.NormalizedPath} = {match.Node}");
// $['store']['book'][0]['title'] = "Sayings"

Selected nodes are the live nodes of your document — nothing is copied or serialized — so you can read, replace or remove them through their Parent.

Why there are dialects

The two JSONPaths in the wild disagree. Newtonsoft.Json's SelectToken/SelectTokens predates the standard and is defined by its implementation; RFC 9535 is the standard. They differ in syntax ($.a-b, [?(…)] vs [?…]), in results ($..*, filters over objects, != on a missing member) and in errors. One rule set cannot be both, so the dialect says which applies:

The dialect is part of the engine's options. It is never a per-call switch and never global state.

API

var engine = new JsonPathEngine(options);              // thread-safe; keep one — it caches parsed queries

IReadOnlyList<JsonPathMatch> all = engine.Select(path, doc);   // every node, in order; empty is a valid result
JsonPathMatch?               one = engine.SelectFirst(path, doc);   // first match or null
JsonPathMatch?               only = engine.SelectSingle(path, doc); // Newtonsoft's SelectToken: >1 match throws
bool                          any = engine.Exists(path, doc);

JsonPathQuery q = engine.Parse(path);   // immutable, thread-safe; throws JsonPathException(Syntax) with a position
q.Select(doc);

A JsonPathMatch carries Node, Parent, Name (object member) or Index (array element), IsRoot, and NormalizedPath (RFC 9535 §2.7, e.g. $['store']['book'][0]).

JSON null is a match, not an absence. System.Text.Json stores JSON null as a C# null, so match.Node == null means the query selected a null value, and Parent + Name/Index is the slot it sits in. A query that finds nothing returns an empty list. That is how {"a": null} / $.a and {} / $.a are told apart.

NormalizedPath is computed on first use, by one walk of the document shared by all matches of the same selection; selecting itself records only each match's last step and allocates no paths.

Options

Errors

Everything throws JsonPathException with a Kind (Syntax, Evaluation, Conversion, Limit, MultipleResults, NoMatch) and, for syntax errors, the zero-based Position of the offending character. An invalid query fails when it is parsed, not when it is run. An empty result is never an error (RFC 9535 §2.1) unless you ask for it with ErrorWhenNoMatch.

Supported syntax

Extended, exactly. The query text is first read as Newtonsoft; if that succeeds, Newtonsoft semantics apply. If Newtonsoft rejects the text it is read as RFC 9535 and RFC semantics apply. One refinement: Newtonsoft's negative array index ([-1]) never worked — it escapes as an ArgumentOutOfRangeException — so there is no Newtonsoft answer to preserve, and Extended counts from the end as RFC 9535 does. A query neither dialect accepts reports both reasons.

Where the dialects differ

Each row is an executable test (DivergenceTableTests); the Newtonsoft column is additionally checked against Newtonsoft.Json 13.0.4 itself.

Slices [start:end:step] are the same in both dialects for every start, end and step in [−4, 4] ∪ {omitted} on arrays of length 0–5 (DivergenceTableTests compares all of them), except step == 0.

Function extensions

length(), count(), match(), search() and value() are built in. Static typing (RFC §2.4.3) is enforced when a query is parsed: $[?length(@.*) > 1] is rejected up front because @.* is a node list where length() takes a value.

Register your own with declared parameter and result types:

var registry = new JsonPathFunctionRegistry().Register(new JsonPathFunction(
    "ends_with",
    [JsonPathFunctionType.Value, JsonPathFunctionType.Value],
    JsonPathFunctionType.Logical,
    args => JsonPathFunctionResult.FromLogical(
        args.Value(0).Node is JsonValue s && args.Value(1).Node is JsonValue suffix
        && s.GetValue<string>().EndsWith(suffix.GetValue<string>(), StringComparison.Ordinal))));

var engine = new JsonPathEngine(new JsonPathOptions { Dialect = JsonPathDialect.Rfc9535, Functions = registry });
engine.Select("$[?ends_with(@.name, '.pdf')]", doc);

Built-in names cannot be replaced. Registrations are snapshotted when the engine is created.

I-Regexp, and the two places it is not the letter of the RFC

match() and search() accept I-Regexp (RFC 9485) only. A pattern is validated against the I-Regexp grammar and then translated to an equivalent .NET Regex; one that is not I-Regexp (\d, lazy quantifiers, back-references, …) never matches rather than quietly working. Matching is by Unicode scalar value: . and negated classes consume a surrogate pair as one character.

• ^ and $. RFC 9485's grammar makes them ordinary characters, yet the JSONPath Compliance Test Suite expects match(@, '^ab.*') to anchor — as it does in every engine that hands the pattern to a regex library. By default a ^ that opens a branch and a $ that closes one are anchors; elsewhere they are literal. StrictIRegexp = true gives the literal reading.
• \p{…} and supplementary-plane characters. .NET does not classify a character outside the BMP through \p{L} and friends, so a category escape never matches one.

Dates

Newtonsoft.Json parses a string like "2020-06-15T12:30:45+02:00" into a date value the moment it reads the document, and from then on it compares as a date. A System.Text.Json document still holds a string, so with EmulateNewtonsoftDates (default true) the Newtonsoft dialect applies the same recognition at comparison time, with Newtonsoft's own parser transcribed. What that means in practice:

The time-zone dependence is Newtonsoft's own — the same query on the same document gives the same answer in Newtonsoft.Json on the same machine — and the tests hold the engine to it. But it does mean the same query can answer differently on a laptop and in a container (containers usually run in UTC). If your documents hold dates and you did not rely on Newtonsoft's behaviour, set EmulateNewtonsoftDates = false: date-looking strings are then plain strings everywhere, and every comparison is machine-independent. (Do the same if you parsed the Newtonsoft document with DateParseHandling.None.) The default stays true because the Newtonsoft dialect exists to give Newtonsoft's answers. The RFC 9535 dialect never treats strings as dates.

Limits and safety

• Every regex evaluation has a timeout (RegexTimeout); a pathological pattern fails with Limit.
• A query longer than MaxQueryLength is refused before it is parsed; filter nesting deeper than MaxDepth is refused rather than recursed into.
• Walking a document with .. uses an explicit stack bounded by MaxDepth, not the call stack.
• Parsed queries are immutable and thread-safe; the cache is bounded.
• Numbers: integers are exact (long, and BigInteger in the Newtonsoft dialect); an integer and a double are compared exactly, not through a lossy conversion.

Target frameworks

net8.0, net9.0 and net10.0, built in parallel and each tested on its own runtime. A later runtime (net11.0 and beyond) uses the net10.0 build — NuGet picks the highest compatible one — and that is checked, not assumed: the net10.0 build passes the compliance suite and the Newtonsoft differential corpus unchanged on the .NET 11 release candidate.

Microsoft's own support for .NET 8 and .NET 9 ends on 10 November 2026; they are targeted because migrating teams are still on them, and will be dropped only in a major version after that date. Policy and the runtime differences found on the way (JsonObject.GetAt, JsonNode.DeepEquals) are in docs/target-frameworks.md.

Not targeted: netstandard2.0 / .NET Framework 4.8 — it would need the System.Text.Json package as a dependency, which ends the "no dependencies" property. Say so on the issue tracker if you need it.

How this is verified

The test project depends on Newtonsoft.Json as an oracle only; the package does not.

Performance

Measured with BenchmarkDotNet (TLio.JsonPath.Benchmarks), one run on an Apple M4 Pro / .NET 10. The full tables, method and caveats are in docs/benchmarks/jsonpath-engine.md. They are measurements, not promises, and they include the cases where this engine is not the fastest:

• Against Newtonsoft's SelectTokens: faster on plain lookups (2–3×), a large filter (2×) and a large descendant query (1.3×); slower where a query fans out over many nodes (a 20,000-element wildcard: 2.6× the time) and on a four-element filter (1.4×) — Newtonsoft enumerates lazily and returns no list.
• Against the other RFC 9535 engines: JsonPath.Net is 2–9× slower than this engine in every case measured. Hyperbee.Json is faster on plain lookups (1.4–1.7×), the small descendant query and a 20,000-element wildcard, and slower on filters (1.5–1.9×).
• Against the JsonCons-based strategy this package replaced in TLio.Json.SystemText: faster in every case, from 2× on a small filter to over 100,000× for an indexed lookup in a 20,000-element document (which no longer gets serialized).

Migrating from the JsonCons-based TLio.Json.SystemText

Earlier versions of TLio.Json.SystemText evaluated paths with JsonCons.JsonPath on a serialized copy of the document. If you used it:

• The default dialect is now Newtonsoft, which is what the package always claimed to match. Paths that worked under Newtonsoft work here; paths that relied on RFC/JsonCons syntax — [?@.a], [-1], match(), double-quoted names — need JsonPathDialect.Extended (which accepts all of them and still behaves as Newtonsoft for everything Newtonsoft accepts) or Rfc9535.
• Errors are no longer swallowed. An invalid path used to select nothing silently; it now throws JsonPathException, as Newtonsoft's SelectTokens throws.
• SelectNode on a path with several matches used to return the first; it now throws, as Newtonsoft's SelectToken does. Use SelectNodes(...).First.
• JsonCons-only functions (keys(), tokenize(), sum(), to_number(), …) are gone; register an RFC function extension for anything you relied on.
• Selection is no longer against a snapshot: it sees the document exactly as it is, including mutations made earlier in the same script.

Third-party notices

The Newtonsoft dialect is a transcription of the behaviour of Newtonsoft.Json 13.0.4's Linq/JsonPath (JPath, the path filters, QueryExpression, JValue.Compare) and of the date recognition in JsonTextReader/DateTimeUtils/DateTimeParser. Those files are MIT licensed:

Copyright (c) 2007 James Newton-King

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

License

MIT — see the repository.