JsonSelector 1.3.0

JsonSelector

A lightweight .NET library for querying JSON payloads using JSONPath expressions. Implements a subset of RFC 9535 (JSONPath: Query Expressions for JSON). No external JSONPath dependencies—built on System.Text.Json only.

Table of Contents

• Features
• Quick Start
• Supported JSONPath Features
• Path and Selector Examples
• Installation
• Usage
• Requirements
• License

Features

Quick Start

using JsonSelector;

var selector = new JsonSelectorImpl();  // or inject IJsonSelector via DI

string json = """{ "id": 1001, "name": "alpha", "items": [{ "kind": "x", "code": "10" }] }""";

bool exists = selector.Any(json, "$.items[?(@.kind=='x')]");  // true
string? name = selector.FirstString(json, "$.name");           // "alpha"
int? code = selector.FirstInt(json, "$.items[0].code");        // 10

Supported JSONPath Features

• Root selector — $
• Child selector — .name
• Index selector — [0], [1], [-1] (negative index = from end)
• Bracket notation for filters — [?()]
• Filter expressions — @.field, ==, !=, >=, >, <=, <, &&, ||, single-quoted strings, numeric literals
• isOneOf — isOneOf(@.field, 'a','b','c') for multiple-value matching

Path and Selector Examples

Installation

NuGet (GitHub Packages)

dotnet add package JsonSelector

Add the GitHub Packages source to nuget.config if needed:

<packageSources>
  <add key="github" value="https://nuget.pkg.github.com/YOUR_ORG/index.json" />
</packageSources>

Project Reference

<ProjectReference Include="path\to\src\JsonSelector\JsonSelector.csproj" />

Usage

Dependency Injection

using JsonSelector;

// Register with DI
services.AddJsonSelector();

// Inject and use
var selector = serviceProvider.GetRequiredService<IJsonSelector>();

Example with Sample JSON

string json = """
{
  "id": 1001,
  "name": "alpha",
  "items": [
    { "id": "A1", "kind": "x", "code": "10" },
    { "id": "B2", "kind": "y", "code": "20" },
    { "id": "C3", "kind": "x", "code": "30" }
  ]
}
""";

// Check if path exists
bool exists = selector.Any(json, "$.id");

// Check if path value matches (non-array paths)
bool nameMatches = selector.Any(json, "$.name == 'alpha'");
bool idInRange = selector.Any(json, "$.id >= 1000");

// Extract values
string? name = selector.FirstString(json, "$.name");
int? code = selector.FirstInt(json, "$.items[?(@.kind=='x')].code");

// Multiple-value filter (OR)
bool hasMatch = selector.Any(json, "$.items[?(@.kind=='x' && (@.code=='10' || @.code=='30'))]");

// Multiple-value filter (isOneOf)
string? id = selector.FirstString(json, "$.items[?(@.kind=='x' && isOneOf(@.code, '10','20'))].id");

// Array index (first, last, by position)
string? first = selector.FirstString(json, "$.items[0].id");
string? last = selector.FirstString(json, "$.items[-1].id");

Requirements

• .NET 10.0

License

MIT License — see LICENSE for details.

Repository

Source code: https://github.com/yanis-kr/JsonSelector