JsonPath Class

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
Add(JsonNode?, JsonNode?)Appends a value to the arrays that this query selects in a JSON value.
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(Utf8JsonReader)Evaluates this JSONPath expression on the JSON value that a reader holds, reading it once from start to end.
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.
EvaluateStream(Stream, JsonReaderOptions)Evaluates this JSONPath expression on a JSON document read from a stream, without loading it in memory.
EvaluateStreamAsync(Stream, JsonReaderOptions, CancellationToken)Evaluates this JSONPath expression on a JSON document read asynchronously from a stream, without loading it in memory.
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.
Remove(JsonNode?)Removes the values that this query selects from a JSON value.
Set(JsonNode?, JsonNode?)Replaces the values that this query selects in a JSON value.
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.

Add(JsonNode?, JsonNode?)

JsonPath.cs

Appends a value to the arrays that this query selects in a JSON value.

public int Add(JsonNode? root, JsonNode? value)

Parameters

root JsonNode?
The root JSON value to change. May be null.
value JsonNode?
The value to append. Each array receives a copy, so value is never attached to root.

Returns

int The number of arrays changed. Selected values that are not arrays are ignored.

Exceptions

InvalidOperationException
A location is part of a JsonValue that wraps an object or an array.

Remarks

The query is evaluated in JsonPathEvaluationMode.Lax mode before anything changes.

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.

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.

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.

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.

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.

Evaluate(Utf8JsonReader)

JsonPath.cs

Evaluates this JSONPath expression on the JSON value that a reader holds, reading it once from start to end.

public JsonPathResult Evaluate(ref Utf8JsonReader reader)
Parameters
reader Utf8JsonReader
A reader that holds a complete JSON value. When it is positioned on a value, the evaluation starts from that value; otherwise it reads the next one. When the method returns, the reader is positioned on the last token of the value.
Returns

JsonPathResult The matches, in document order.

Exceptions
ArgumentException
The reader uses JsonCommentHandling.Allow. Use JsonCommentHandling.Skip instead.
JsonException
The data is not valid JSON, or the reader does not hold a complete value.
JsonPathEvaluationException
The evaluation exceeds a depth limit.
Remarks

Only the selected values, and the values that a filter tests, are parsed into JsonNode instances, so the document does not have to be loaded in memory. The matches are the ones of JsonPath.Evaluate, in document order rather than in the order of the selectors. A query whose filters use $ parses the whole document.

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>

EvaluateStream(Stream, JsonReaderOptions)

JsonPath.cs

Evaluates this JSONPath expression on a JSON document read from a stream, without loading it in memory.

public IEnumerable<JsonPathMatch> EvaluateStream(Stream utf8Json, JsonReaderOptions readerOptions = default)

Parameters

utf8Json Stream
The UTF-8 JSON data. The stream is read up to its end, and is not disposed.
readerOptions JsonReaderOptions
The options of the reader, such as the maximum depth or whether comments are allowed.

Returns

IEnumerable<JsonPathMatch> The matches, in document order. They are returned as soon as they are read, and the stream is read as they are enumerated.

Exceptions

ArgumentNullException
utf8Json is null.
JsonException
The data is not valid JSON. It is thrown during the enumeration.
JsonPathEvaluationException
The evaluation exceeds a depth limit. It is thrown during the enumeration.

Remarks

Only the selected values, and the values that a filter tests, are parsed into JsonNode instances. The matches are the ones of JsonPath.Evaluate, in document order rather than in the order of the selectors. A query whose filters use $ parses the whole document.

EvaluateStreamAsync(Stream, JsonReaderOptions, CancellationToken)

JsonPath.cs

Evaluates this JSONPath expression on a JSON document read asynchronously from a stream, without loading it in memory.

public IAsyncEnumerable<JsonPathMatch> EvaluateStreamAsync(Stream utf8Json, JsonReaderOptions readerOptions = default, CancellationToken cancellationToken = default)

Parameters

utf8Json Stream
The UTF-8 JSON data. The stream is read up to its end, and is not disposed.
readerOptions JsonReaderOptions
The options of the reader, such as the maximum depth or whether comments are allowed.
cancellationToken CancellationToken
The token to monitor for cancellation requests.

Returns

IAsyncEnumerable<JsonPathMatch> The matches, in document order. They are returned as soon as they are read, and the stream is read as they are enumerated.

Exceptions

ArgumentNullException
utf8Json is null.
JsonException
The data is not valid JSON. It is thrown during the enumeration.
JsonPathEvaluationException
The evaluation exceeds a depth limit. It is thrown during the enumeration.

Remarks

Only the selected values, and the values that a filter tests, are parsed into JsonNode instances. The matches are the ones of JsonPath.Evaluate, in document order rather than in the order of the selectors. A query whose filters use $ parses the whole document.

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.

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.

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.

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

Remove(JsonNode?)

JsonPath.cs

Removes the values that this query selects from a JSON value.

public int Remove(JsonNode? root)

Parameters

root JsonNode?
The root JSON value to change. May be null.

Returns

int The number of values removed.

Exceptions

InvalidOperationException
The query selects the root value, or a location is part of a JsonValue that wraps an object or an array.

Remarks

The query is evaluated in JsonPathEvaluationMode.Lax mode before anything changes, so removing an array element does not change which elements the other indexes of the query select.

Set(JsonNode?, JsonNode?)

JsonPath.cs

Replaces the values that this query selects in a JSON value.

public int Set(JsonNode? root, JsonNode? value)

Parameters

root JsonNode?
The root JSON value to change. May be null.
value JsonNode?
The new value. Each location receives a copy, so value is never attached to root.

Returns

int The number of locations set.

Exceptions

InvalidOperationException
The query selects the root value, a location is part of a JsonValue that wraps an object or an array, or an object that ignores the case of names has a member whose name differs from the one to set only by case.

Remarks

When the query ends with a name, such as $.users[*].active, the member is set on every object the rest of the query selects, whether the member exists or not. When the query is a path of names and indexes, such as $.logging.level, the objects missing on the path are created too. Indexes out of range are never created.

The query is evaluated in JsonPathEvaluationMode.Lax mode before anything changes.

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