JsonPathPlus 1.1.0

JsonPathPlus

Lightweight JSONPath-like Stream extensions for System.Text.Json.

Extracts JSON subtrees from a Stream by path expression without loading the full document into memory. Internally uses JsonNode.ParseAsync for evaluation; a true token-streaming mode (no full parse) is on the roadmap.

Installation

dotnet add package JsonPathPlus

Quick start

using JsonPathPlus;

// First match
JsonNode? node = await stream.ExtractFirstJsonMatchAsync("$.document_data.items[0].seal");

// All matches
await foreach (var item in stream.ExtractAllJsonMatchesAsync("$.items[*].id"))
{
    Console.WriteLine(item);
}

NuGet publishing (GitHub only)

NuGet publishing is automated in GitHub Actions and does not require local package push commands.

Workflows

• Build validation: .github/workflows/build.yml
• NuGet publish: .github/workflows/publish-nuget.yml

Required GitHub secret

Add this repository secret before publishing:

• NUGET_API_KEY: API key from nuget.org with push permission for JsonPathPlus

Release branch format

Publishing is triggered when you push a branch with this exact pattern:

• release_1.0.0
• release_1.0.1

The version is taken from the branch name after release_. Only semantic versions in major.minor.patch format are accepted.

Publish flow

When a release branch is pushed, .github/workflows/publish-nuget.yml performs:

1. Restore
2. Build (Release) with /p:Version from branch name
3. Test
4. Pack with /p:PackageVersion from branch name
5. Push package to nuget.org with --skip-duplicate

Typical commands

git checkout -b release_1.0.0
git push -u origin release_1.0.0

Notes

• Local nupkg/snupkg outputs are ignored by git.
• If a branch name is invalid (for example release_1.0), the publish workflow fails fast with a validation error.
• If the same package version already exists on nuget.org, publish step is non-failing because --skip-duplicate is enabled.

Supported path syntax

API reference

// Stream input
Task<JsonNode?> ExtractFirstJsonMatchAsync(this Stream stream, string? selectToken)
IAsyncEnumerable<JsonNode?> ExtractAllJsonMatchesAsync(this Stream stream, string? selectToken)

// JsonNode input
Task<JsonNode?> ExtractFirstJsonMatchAsync(this JsonNode? node, string? selectToken)
IAsyncEnumerable<JsonNode?> ExtractAllJsonMatchesAsync(this JsonNode? node, string? selectToken)

// Raw JSON string input
Task<JsonNode?> ExtractFirstJsonMatchAsync(this string json, string? selectToken)
IAsyncEnumerable<JsonNode?> ExtractAllJsonMatchesAsync(this string json, string? selectToken)

Passing null or "$" as selectToken returns the entire document.

Path validation

Use JsonPathValidator to check a path expression before executing it:

// Quick boolean check
bool ok = JsonPathValidator.IsValid("$.items[?(@.price < 10)]");

// Full result with error message
JsonPathValidationResult result = JsonPathValidator.Validate("$.items[?()]");
if (!result.IsValid)
    Console.WriteLine(result.Error);
// → "Empty filter expression at position 7."

Validate detects the following structural errors:

null and empty strings are considered valid (they select the root document). Bracket characters inside quoted string literals in filter expressions are handled correctly and do not produce false positives.

Malformed path behavior

The parser is lenient and never throws on invalid or incomplete path expressions. The table below documents the defined behavior for common malformed inputs.

Guarantee: no malformed path will cause an infinite loop or an unhandled exception. At worst, the path is parsed partially and matched against whatever valid segments were extracted before the error.

Implementation roadmap

The section below details the remaining planned work. All earlier phases (negative/union indexing, filter expressions, computed index expressions) are implemented.

Phase 0.5 - API parity for input types (implemented)

Goal: Provide the same extraction ergonomics for JsonNode and raw JSON string inputs as existing Stream extensions.

Design notes:

1. Keep matcher behavior identical across Stream, JsonNode, and string overloads.
2. Centralize parsed-segment and match execution to avoid duplicated extraction logic.
3. Add API-level tests that assert parity of outputs across all three input types.

Phase 1 — Streaming strategy (partially implemented)

Goal: Traverse large streams with a streaming strategy where possible.

Implementation sketch:

1. Add a dedicated streaming matcher (for example JsonPathStreamingMatcher) that evaluates parsed JsonPathSegment lists against Utf8JsonReader.
2. Keep JsonPathMatcher as the in-memory strategy and select between strategies in StreamJsonExtractionExtensions.
3. Add compatibility tests to ensure streaming and in-memory strategies return the same results for identical paths.
4. Add benchmark comparing streaming vs full-parse for various document sizes.

JSONPath ↔ XPath quick reference

The table below maps common XPath expressions to their JSONPath equivalents as a reference. Entries marked "not present in the original spec" are extensions defined by the JSONPath-Plus JavaScript library and are not guaranteed to be implemented in this library.

License

MIT