JsonPtr 1.0.4

JsonPtr

This project provides extension methods for the System.Text.Json.JsonElement type to support JSON Pointer (RFC 6901) resolution.

Features

• JSON Pointer Support: Resolve JSON elements using RFC 6901-compliant JSON Pointer strings.
• Flexible APIs:
  • GetElement: Retrieves a JSON element or throws a JsonPointerException on failure.
  • GetElementOrNull: Retrieves a JSON element or returns null on failure.
  • TryGetElement: Attempts to retrieve a JSON element, returning a success flag and error details if applicable.

Usage

GetElement

Retrieves a JSON element at the specified pointer, throwing an exception if resolution fails.

var json = @"{""person"":{""name"":""John""}}";
var element = JsonDocument.Parse(json).RootElement;

try
{
    var nameElement = element.GetElement("/person/name");
    Console.WriteLine(nameElement.GetString()); // Output: John
    var invalidElement = element.GetElement("/person/age");
}
catch (JsonPointerException ex)
{
    Console.WriteLine(ex.Message); // Handles invalid pointers
}

GetElementOrNull

Retrieves a JSON element or returns null if the pointer cannot be resolved.

using System.Text.Json;

var json = @"{""person"":{""name"":""John""}}";
var element = JsonDocument.Parse(json).RootElement;

var name = element.GetElementOrNull("/person/name");
Console.WriteLine(name.Value.GetString()); // Output: John
var age = element.GetElementOrNull("/person/age");
Console.WriteLine(age.HasValue ? age.Value.GetString() : "Not found"); // Output: Not found

TryGetElement

Attempts to retrieve a JSON element, returning success status and error details.

using System.Text.Json;

var json = @"{""person"":{""name"":""John""}}";
var element = JsonDocument.Parse(json).RootElement;

if (element.TryGetElement("/person/name", out JsonElement? result, out JsonPointerError? error))
{
    Console.WriteLine(result.Value.GetString()); // Output: John
}
else
{
    Console.WriteLine(error.Message); // Handles failure
}

JSON Pointer Syntax

• /property accesses an object property.
• /0 accesses an array element by index.
• Use ~0 for ~ and ~1 for / in escaped keys (e.g., /foo~1bar for key foo/bar).
• Empty pointer ("") refers to the root element.