Meziantou.Framework

JsonPath Class

Namespace
Meziantou.Framework.Json
Assembly
Meziantou.Framework.JsonPath.dll
Package
Meziantou.Framework.JsonPath 3.0.10
Source
JsonPath.cs
Available in package assets
net10.0net11.0

Represents a parsed JSONPath expression that can be evaluated against JSON values. This class is immutable and thread-safe; a single instance can be reused to evaluate multiple JSON documents.

public sealed class JsonPath : IParsable<JsonPath>, ISpanParsable<JsonPath>

Remarks

Custom function implementations are shared and must also be thread-safe.

Implements

Methods

NameDescription
Evaluate(JsonDocument?)Evaluates this JSONPath expression against a JSON document.
Evaluate(JsonDocument?, JsonPathEvaluationMode)Evaluates this JSONPath expression against a JSON document.
Evaluate(JsonDocument?, JsonPathEvaluationOptions, JsonPathEvaluationMode)Evaluates with cooperative cancellation and resource limits. Exceeding a limit throws; no partial result is returned.
Evaluate(JsonElement)Evaluates this JSONPath expression against a JSON element.
Evaluate(JsonElement, JsonPathEvaluationMode)Evaluates this JSONPath expression against a JSON element.
Evaluate(JsonElement, JsonPathEvaluationOptions, JsonPathEvaluationMode)Evaluates with cooperative cancellation and resource limits. Exceeding a limit throws; no partial result is returned.
Evaluate(JsonNode?)Evaluates this JSONPath expression against a JSON value.
Evaluate(JsonNode?, JsonPathEvaluationMode)Evaluates this JSONPath expression against a JSON value.
Evaluate(JsonNode?, JsonPathEvaluationOptions, JsonPathEvaluationMode)Evaluates with cooperative cancellation and resource limits. Exceeding a limit throws; no partial result is returned.
Evaluate<TValue>(TValue?, JsonPathNavigator<TValue>)Evaluates this JSONPath expression against a custom object model.
Evaluate<TValue>(TValue?, JsonPathNavigator<TValue>, JsonPathEvaluationMode)Evaluates this JSONPath expression against a custom object model.
Evaluate<TValue>(TValue?, JsonPathNavigator<TValue>, JsonPathEvaluationOptions, JsonPathEvaluationMode)Evaluates with cooperative cancellation and resource limits. Exceeding a limit throws; no partial result is returned.
EvaluateValue(JsonDocument?)Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.
EvaluateValue(JsonDocument?, JsonPathEvaluationMode)Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.
EvaluateValue(JsonDocument?, JsonPathEvaluationOptions, JsonPathEvaluationMode)Returns the first value with cooperative cancellation and resource limits. Strict mode validates later branches too.
EvaluateValue(JsonElement)Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.
EvaluateValue(JsonElement, JsonPathEvaluationMode)Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.
EvaluateValue(JsonElement, JsonPathEvaluationOptions, JsonPathEvaluationMode)Returns the first value with cooperative cancellation and resource limits. Strict mode validates later branches too.
EvaluateValue(JsonNode?)Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.
EvaluateValue(JsonNode?, JsonPathEvaluationMode)Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.
EvaluateValue(JsonNode?, JsonPathEvaluationOptions, JsonPathEvaluationMode)Returns the first value with cooperative cancellation and resource limits. Strict mode validates later branches too.
EvaluateValue<TValue>(TValue?, JsonPathNavigator<TValue>)Evaluates this JSONPath expression and returns the first matched custom value, or null when there is no match.
EvaluateValue<TValue>(TValue?, JsonPathNavigator<TValue>, JsonPathEvaluationMode)Evaluates this JSONPath expression and returns the first matched custom value, or null when there is no match.
EvaluateValue<TValue>(TValue?, JsonPathNavigator<TValue>, JsonPathEvaluationOptions, JsonPathEvaluationMode)Returns the first value with cooperative cancellation and resource limits. Strict mode validates later branches too.
Parse(ReadOnlySpan<char>)Parses a JSONPath expression from a character span.
Parse(ReadOnlySpan<char>, JsonPathFunctionRegistry)Parses an expression span using an immutable opt-in custom function registry.
Parse(string)Parses a JSONPath expression.
Parse(string, JsonPathFunctionRegistry)Parses an expression using an immutable opt-in custom function registry.
ToString()Returns the original JSONPath expression string.
TryParse(ReadOnlySpan<char>, JsonPath?)Tries to parse a JSONPath expression from a character span.
TryParse(ReadOnlySpan<char>, JsonPathFunctionRegistry, JsonPath?)Tries to parse an expression span using an immutable opt-in custom function registry.
TryParse(string?, JsonPath?)Tries to parse a JSONPath expression.
TryParse(string?, JsonPathFunctionRegistry, JsonPath?)Tries to parse an expression using an immutable opt-in custom function registry.

Evaluate overloads

Evaluate(JsonDocument?)

JsonPath.cs

Evaluates this JSONPath expression against a JSON document.

public JsonPathResult<JsonElement> Evaluate(JsonDocument? root)
Parameters
root JsonDocument?
The root JSON document to query. May be null.
Returns

JsonPathResult<JsonElement> A JsonPathResult<TValue> containing all matched nodes.

Evaluate(JsonDocument?, JsonPathEvaluationMode)

JsonPath.cs

Evaluates this JSONPath expression against a JSON document.

public JsonPathResult<JsonElement> Evaluate(JsonDocument? root, JsonPathEvaluationMode mode)
Parameters
root JsonDocument?
The root JSON document to query. May be null.
mode JsonPathEvaluationMode
The evaluation mode.
Returns

JsonPathResult<JsonElement> A JsonPathResult<TValue> containing all matched nodes.

Exceptions
JsonPathEvaluationException
The path cannot be evaluated in JsonPathEvaluationMode.Strict mode.

Evaluate(JsonDocument?, JsonPathEvaluationOptions, JsonPathEvaluationMode)

JsonPath.cs

Evaluates with cooperative cancellation and resource limits. Exceeding a limit throws; no partial result is returned.

public JsonPathResult<JsonElement> Evaluate(JsonDocument? root, JsonPathEvaluationOptions options, JsonPathEvaluationMode mode = JsonPathEvaluationMode.Lax)
Parameters
root JsonDocument?
options JsonPathEvaluationOptions
mode JsonPathEvaluationMode
Returns

JsonPathResult<JsonElement>

Evaluate(JsonElement)

JsonPath.cs

Evaluates this JSONPath expression against a JSON element.

public JsonPathResult<JsonElement> Evaluate(JsonElement root)
Parameters
root JsonElement
The root JSON element to query.
Returns

JsonPathResult<JsonElement> A JsonPathResult<TValue> containing all matched nodes.

Evaluate(JsonElement, JsonPathEvaluationMode)

JsonPath.cs

Evaluates this JSONPath expression against a JSON element.

public JsonPathResult<JsonElement> Evaluate(JsonElement root, JsonPathEvaluationMode mode)
Parameters
root JsonElement
The root JSON element to query.
mode JsonPathEvaluationMode
The evaluation mode.
Returns

JsonPathResult<JsonElement> A JsonPathResult<TValue> containing all matched nodes.

Exceptions
JsonPathEvaluationException
The path cannot be evaluated in JsonPathEvaluationMode.Strict mode.

Evaluate(JsonElement, JsonPathEvaluationOptions, JsonPathEvaluationMode)

JsonPath.cs

Evaluates with cooperative cancellation and resource limits. Exceeding a limit throws; no partial result is returned.

public JsonPathResult<JsonElement> Evaluate(JsonElement root, JsonPathEvaluationOptions options, JsonPathEvaluationMode mode = JsonPathEvaluationMode.Lax)
Parameters
root JsonElement
options JsonPathEvaluationOptions
mode JsonPathEvaluationMode
Returns

JsonPathResult<JsonElement>

Evaluate(JsonNode?)

JsonPath.cs

Evaluates this JSONPath expression against a JSON value.

public JsonPathResult Evaluate(JsonNode? root)
Parameters
root JsonNode?
The root JSON value to query. May be null.
Returns

JsonPathResult A JsonPathResult containing all matched nodes.

Evaluate(JsonNode?, JsonPathEvaluationMode)

JsonPath.cs

Evaluates this JSONPath expression against a JSON value.

public JsonPathResult Evaluate(JsonNode? root, JsonPathEvaluationMode mode)
Parameters
root JsonNode?
The root JSON value to query. May be null.
mode JsonPathEvaluationMode
The evaluation mode.
Returns

JsonPathResult A JsonPathResult containing all matched nodes.

Exceptions
JsonPathEvaluationException
The path cannot be evaluated in JsonPathEvaluationMode.Strict mode.

Evaluate(JsonNode?, JsonPathEvaluationOptions, JsonPathEvaluationMode)

JsonPath.cs

Evaluates with cooperative cancellation and resource limits. Exceeding a limit throws; no partial result is returned.

public JsonPathResult Evaluate(JsonNode? root, JsonPathEvaluationOptions options, JsonPathEvaluationMode mode = JsonPathEvaluationMode.Lax)
Parameters
root JsonNode?
options JsonPathEvaluationOptions
mode JsonPathEvaluationMode
Returns

JsonPathResult

Evaluate<TValue>(TValue?, JsonPathNavigator<TValue>)

JsonPath.cs

Evaluates this JSONPath expression against a custom object model.

public JsonPathResult<TValue> Evaluate<TValue>(TValue? root, JsonPathNavigator<TValue> navigator)
Type parameters
TValue
The node type used by the JSONPath navigator.
Parameters
root TValue?
The root value to query. May be null when the root value is JSON null.
navigator JsonPathNavigator<TValue>
The navigator used to inspect values.
Returns

JsonPathResult<TValue> A JsonPathResult<TValue> containing all matched nodes.

Exceptions
ArgumentNullException
navigator is null.

Evaluate<TValue>(TValue?, JsonPathNavigator<TValue>, JsonPathEvaluationMode)

JsonPath.cs

Evaluates this JSONPath expression against a custom object model.

public JsonPathResult<TValue> Evaluate<TValue>(TValue? root, JsonPathNavigator<TValue> navigator, JsonPathEvaluationMode mode)
Type parameters
TValue
The node type used by the JSONPath navigator.
Parameters
root TValue?
The root value to query. May be null when the root value is JSON null.
navigator JsonPathNavigator<TValue>
The navigator used to inspect values.
mode JsonPathEvaluationMode
The evaluation mode.
Returns

JsonPathResult<TValue> A JsonPathResult<TValue> containing all matched nodes.

Exceptions
ArgumentNullException
navigator is null.
JsonPathEvaluationException
The path cannot be evaluated in JsonPathEvaluationMode.Strict mode.

Evaluate<TValue>(TValue?, JsonPathNavigator<TValue>, JsonPathEvaluationOptions, JsonPathEvaluationMode)

JsonPath.cs

Evaluates with cooperative cancellation and resource limits. Exceeding a limit throws; no partial result is returned.

public JsonPathResult<TValue> Evaluate<TValue>(TValue? root, JsonPathNavigator<TValue> navigator, JsonPathEvaluationOptions options, JsonPathEvaluationMode mode = JsonPathEvaluationMode.Lax)
Type parameters
TValue
Parameters
root TValue?
navigator JsonPathNavigator<TValue>
options JsonPathEvaluationOptions
mode JsonPathEvaluationMode
Returns

JsonPathResult<TValue>

EvaluateValue overloads

EvaluateValue(JsonDocument?)

JsonPath.cs

Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.

public JsonElement? EvaluateValue(JsonDocument? root)
Parameters
root JsonDocument?
The root JSON document to query. May be null.
Returns

JsonElement? The first matched value, or null when there is no match.

EvaluateValue(JsonDocument?, JsonPathEvaluationMode)

JsonPath.cs

Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.

public JsonElement? EvaluateValue(JsonDocument? root, JsonPathEvaluationMode mode)
Parameters
root JsonDocument?
The root JSON document to query. May be null.
mode JsonPathEvaluationMode
The evaluation mode.
Returns

JsonElement? The first matched value, or null when there is no match.

Exceptions
JsonPathEvaluationException
The path cannot be evaluated in JsonPathEvaluationMode.Strict mode.

EvaluateValue(JsonDocument?, JsonPathEvaluationOptions, JsonPathEvaluationMode)

JsonPath.cs

Returns the first value with cooperative cancellation and resource limits. Strict mode validates later branches too.

public JsonElement? EvaluateValue(JsonDocument? root, JsonPathEvaluationOptions options, JsonPathEvaluationMode mode = JsonPathEvaluationMode.Lax)
Parameters
root JsonDocument?
options JsonPathEvaluationOptions
mode JsonPathEvaluationMode
Returns

JsonElement?

EvaluateValue(JsonElement)

JsonPath.cs

Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.

public JsonElement? EvaluateValue(JsonElement root)
Parameters
root JsonElement
The root JSON element to query.
Returns

JsonElement? The first matched value, or null when there is no match.

EvaluateValue(JsonElement, JsonPathEvaluationMode)

JsonPath.cs

Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.

public JsonElement? EvaluateValue(JsonElement root, JsonPathEvaluationMode mode)
Parameters
root JsonElement
The root JSON element to query.
mode JsonPathEvaluationMode
The evaluation mode.
Returns

JsonElement? The first matched value, or null when there is no match.

Exceptions
JsonPathEvaluationException
The path cannot be evaluated in JsonPathEvaluationMode.Strict mode.

EvaluateValue(JsonElement, JsonPathEvaluationOptions, JsonPathEvaluationMode)

JsonPath.cs

Returns the first value with cooperative cancellation and resource limits. Strict mode validates later branches too.

public JsonElement? EvaluateValue(JsonElement root, JsonPathEvaluationOptions options, JsonPathEvaluationMode mode = JsonPathEvaluationMode.Lax)
Parameters
root JsonElement
options JsonPathEvaluationOptions
mode JsonPathEvaluationMode
Returns

JsonElement?

EvaluateValue(JsonNode?)

JsonPath.cs

Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.

public JsonNode? EvaluateValue(JsonNode? root)
Parameters
root JsonNode?
The root JSON value to query. May be null.
Returns

JsonNode? The first matched value, or null when there is no match.

EvaluateValue(JsonNode?, JsonPathEvaluationMode)

JsonPath.cs

Evaluates this JSONPath expression and returns the first matched value, or null when there is no match.

public JsonNode? EvaluateValue(JsonNode? root, JsonPathEvaluationMode mode)
Parameters
root JsonNode?
The root JSON value to query. May be null.
mode JsonPathEvaluationMode
The evaluation mode.
Returns

JsonNode? The first matched value, or null when there is no match.

Exceptions
JsonPathEvaluationException
The path cannot be evaluated in JsonPathEvaluationMode.Strict mode.

EvaluateValue(JsonNode?, JsonPathEvaluationOptions, JsonPathEvaluationMode)

JsonPath.cs

Returns the first value with cooperative cancellation and resource limits. Strict mode validates later branches too.

public JsonNode? EvaluateValue(JsonNode? root, JsonPathEvaluationOptions options, JsonPathEvaluationMode mode = JsonPathEvaluationMode.Lax)
Parameters
root JsonNode?
options JsonPathEvaluationOptions
mode JsonPathEvaluationMode
Returns

JsonNode?

EvaluateValue<TValue>(TValue?, JsonPathNavigator<TValue>)

JsonPath.cs

Evaluates this JSONPath expression and returns the first matched custom value, or null when there is no match.

public TValue? EvaluateValue<TValue>(TValue? root, JsonPathNavigator<TValue> navigator)
Type parameters
TValue
The node type used by the JSONPath navigator.
Parameters
root TValue?
The root value to query. May be null when the root value is JSON null.
navigator JsonPathNavigator<TValue>
The navigator used to inspect values.
Returns

TValue? The first matched value, or null when there is no match.

Exceptions
ArgumentNullException
navigator is null.

EvaluateValue<TValue>(TValue?, JsonPathNavigator<TValue>, JsonPathEvaluationMode)

JsonPath.cs

Evaluates this JSONPath expression and returns the first matched custom value, or null when there is no match.

public TValue? EvaluateValue<TValue>(TValue? root, JsonPathNavigator<TValue> navigator, JsonPathEvaluationMode mode)
Type parameters
TValue
The node type used by the JSONPath navigator.
Parameters
root TValue?
The root value to query. May be null when the root value is JSON null.
navigator JsonPathNavigator<TValue>
The navigator used to inspect values.
mode JsonPathEvaluationMode
The evaluation mode.
Returns

TValue? The first matched value, or null when there is no match.

Exceptions
ArgumentNullException
navigator is null.
JsonPathEvaluationException
The path cannot be evaluated in JsonPathEvaluationMode.Strict mode.

EvaluateValue<TValue>(TValue?, JsonPathNavigator<TValue>, JsonPathEvaluationOptions, JsonPathEvaluationMode)

JsonPath.cs

Returns the first value with cooperative cancellation and resource limits. Strict mode validates later branches too.

public TValue? EvaluateValue<TValue>(TValue? root, JsonPathNavigator<TValue> navigator, JsonPathEvaluationOptions options, JsonPathEvaluationMode mode = JsonPathEvaluationMode.Lax)
Type parameters
TValue
Parameters
root TValue?
navigator JsonPathNavigator<TValue>
options JsonPathEvaluationOptions
mode JsonPathEvaluationMode
Returns

TValue?

Parse overloads

Parse(ReadOnlySpan<char>)

JsonPath.cs

Parses a JSONPath expression from a character span.

public static JsonPath Parse(ReadOnlySpan<char> expression)
Parameters
expression ReadOnlySpan<char>
A valid JSONPath expression (must start with $).
Returns

JsonPath A parsed JsonPath instance.

Exceptions
FormatException
The expression is not a well-formed or valid JSONPath query.

Parse(ReadOnlySpan<char>, JsonPathFunctionRegistry)

JsonPath.cs

Parses an expression span using an immutable opt-in custom function registry.

public static JsonPath Parse(ReadOnlySpan<char> expression, JsonPathFunctionRegistry functions)
Parameters
expression ReadOnlySpan<char>
functions JsonPathFunctionRegistry
Returns

JsonPath

Parse(string)

JsonPath.cs

Parses a JSONPath expression.

public static JsonPath Parse(string expression)
Parameters
expression string
A valid JSONPath expression string (must start with $).
Returns

JsonPath A parsed JsonPath instance.

Exceptions
ArgumentNullException
expression is null.
FormatException
The expression is not a well-formed or valid JSONPath query.

Parse(string, JsonPathFunctionRegistry)

JsonPath.cs

Parses an expression using an immutable opt-in custom function registry.

public static JsonPath Parse(string expression, JsonPathFunctionRegistry functions)
Parameters
expression string
functions JsonPathFunctionRegistry
Returns

JsonPath

ToString()

JsonPath.cs

Returns the original JSONPath expression string.

public override string ToString()

Returns

string

TryParse overloads

TryParse(ReadOnlySpan<char>, JsonPath?)

JsonPath.cs

Tries to parse a JSONPath expression from a character span.

public static bool TryParse(ReadOnlySpan<char> expression, out JsonPath? result)
Parameters
expression ReadOnlySpan<char>
A JSONPath expression.
result JsonPath?
When this method returns, contains the parsed JsonPath if parsing succeeded, or null if it failed.
Returns

bool true if parsing succeeded; otherwise, false.

TryParse(ReadOnlySpan<char>, JsonPathFunctionRegistry, JsonPath?)

JsonPath.cs

Tries to parse an expression span using an immutable opt-in custom function registry.

public static bool TryParse(ReadOnlySpan<char> expression, JsonPathFunctionRegistry functions, out JsonPath? result)
Parameters
expression ReadOnlySpan<char>
functions JsonPathFunctionRegistry
result JsonPath?
Returns

bool

TryParse(string?, JsonPath?)

JsonPath.cs

Tries to parse a JSONPath expression.

public static bool TryParse(string? expression, out JsonPath? result)
Parameters
expression string?
A JSONPath expression string.
result JsonPath?
When this method returns, contains the parsed JsonPath if parsing succeeded, or null if it failed.
Returns

bool true if parsing succeeded; otherwise, false.

TryParse(string?, JsonPathFunctionRegistry, JsonPath?)

JsonPath.cs

Tries to parse an expression using an immutable opt-in custom function registry.

public static bool TryParse(string? expression, JsonPathFunctionRegistry functions, out JsonPath? result)
Parameters
expression string?
functions JsonPathFunctionRegistry
result JsonPath?
Returns

bool