JsonSift 1.0.0

JsonSift

A small, safe, bounded expression language over in-memory JSON (System.Text.Json). Point it at a JsonNode and:

• navigate with $-paths — $.user.name, $.items[0], $.items[*].id
• filter arrays with one comparison — $.items[?id == $.current.id].name
• evaluate boolean conditions — $.amount > 1000 && $.country in ['ES','PT']
• interpolate strings — "Hi {name}" with a {hole} → path map

It is a deliberately small subset: no recursive descent (..), no functions, no arithmetic, no code execution. The whole surface is hand-written and auditable — you navigate data, nothing else. That makes it a good fit for user-supplied templates, rules, and config where you must not hand over a general expression engine.

Install

dotnet add package JsonSift

Multi-targets net8.0, net9.0, net10.0. Only dependency: System.Text.Json (in-box).

Quickstart

using JsonSift;                 // SiftContext, JsonExpr, exceptions
using JsonSift.Paths;           // PathExpression, CompiledPath
using JsonSift.Conditions;      // ConditionParser, ConditionEvaluator
using JsonSift.Interpolation;   // StringInterpolator
using System.Text.Json.Nodes;

// 1) Build the root document from heterogeneous inputs (or use any JsonNode you already have)
JsonObject root = new SiftContext()
    .AddNode("payload", payloadJsonElement)   // JsonElement / JsonDocument / JsonNode / any T
    .AddNode("user", new { id = "u2", name = "Bob" })
    .Build();

// 2) Compile once (this validates syntax and throws ExpressionParseException on errors)
CompiledPath path = PathExpression.Parse("$.user.name");
CompiledCondition cond = ConditionParser.Parse("$.payload.amount > 1000");
CompiledTemplateString tpl = StringInterpolator.Compile(
    "Hi {name}", new Dictionary<string, string> { ["name"] = "$.user.name" });

// 3) Evaluate against any JsonNode root
JsonNode? name = PathExpression.ResolveSingle(path, root);   // "Bob"
bool ok        = ConditionEvaluator.Evaluate(cond, root);   // true/false
string text    = StringInterpolator.Interpolate(tpl, root); // "Hi Bob"

// Typed resolution with coercion:
string? n = JsonExpr.ResolveAs<string>(path, root);

Grammar at a glance

A path with [*] or a filter yields a list; otherwise a single value. A missing member/index resolves to null (never throws).

Two things to know

• == coerces numeric strings (SQL-like): "1" == 1 is true. This is not RFC 9535 behaviour — see Documents/07-vs-rfc-9535.md.
• Filters use a bare field name ([?id == ...]), not @.id. One comparison only — no &&/||/nesting inside a filter.

Documentation

Full docs live in Documents/:

1. Overview — concepts, types, API map
2. Grammar — paths, indices, wildcards, filters, cardinality
3. Conditions — booleans, in, matches, truthiness
4. Interpolation — literals, bare paths, {holes}
5. SiftContext — assembling the root from JsonElement/JsonDocument/T
6. Coercion — equality, ordering, dates, truthiness, to-string
7. vs RFC 9535 — how this differs from standard JSONPath

License

MIT — see LICENSE.