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.
Methods
| Name | Description |
|---|---|
| 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.csAppends a value to the arrays that this query selects in a JSON value.
Parameters
rootJsonNode?- The root JSON value to change. May be
null. valueJsonNode?- The value to append. Each array receives a copy, so
valueis never attached toroot.
Returns
int The number of arrays changed. Selected values that are not arrays are ignored.
Exceptions
InvalidOperationException- A location is part of a
JsonValuethat wraps an object or an array.
Remarks
The query is evaluated in JsonPathEvaluationMode.Lax mode before anything changes.
Evaluate overloads
Evaluate(JsonDocument?)
JsonPath.csEvaluates this JSONPath expression against a JSON document.
public JsonPathResult<JsonElement> Evaluate(JsonDocument? root)Parameters
rootJsonDocument?- The root JSON document to query. May be
null.
Returns
JsonPathResult<JsonElement> A JsonPathResult<TValue> containing all matched nodes.
Evaluate(JsonDocument?, JsonPathEvaluationMode)
JsonPath.csEvaluates this JSONPath expression against a JSON document.
public JsonPathResult<JsonElement> Evaluate(JsonDocument? root, JsonPathEvaluationMode mode)Parameters
rootJsonDocument?- The root JSON document to query. May be
null. modeJsonPathEvaluationMode- The evaluation mode.
Returns
JsonPathResult<JsonElement> A JsonPathResult<TValue> containing all matched nodes.
Exceptions
JsonPathEvaluationException- The path cannot be evaluated in
JsonPathEvaluationMode.Strictmode.
Evaluate(JsonDocument?, JsonPathEvaluationOptions, JsonPathEvaluationMode)
JsonPath.csEvaluates 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)Evaluate(JsonElement)
JsonPath.csEvaluates this JSONPath expression against a JSON element.
public JsonPathResult<JsonElement> Evaluate(JsonElement root)Parameters
rootJsonElement- The root JSON element to query.
Returns
JsonPathResult<JsonElement> A JsonPathResult<TValue> containing all matched nodes.
Evaluate(JsonElement, JsonPathEvaluationMode)
JsonPath.csEvaluates this JSONPath expression against a JSON element.
public JsonPathResult<JsonElement> Evaluate(JsonElement root, JsonPathEvaluationMode mode)Parameters
rootJsonElement- The root JSON element to query.
modeJsonPathEvaluationMode- The evaluation mode.
Returns
JsonPathResult<JsonElement> A JsonPathResult<TValue> containing all matched nodes.
Exceptions
JsonPathEvaluationException- The path cannot be evaluated in
JsonPathEvaluationMode.Strictmode.
Evaluate(JsonElement, JsonPathEvaluationOptions, JsonPathEvaluationMode)
JsonPath.csEvaluates 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)Evaluate(JsonNode?)
JsonPath.csEvaluates this JSONPath expression against a JSON value.
public JsonPathResult Evaluate(JsonNode? root)Parameters
rootJsonNode?- The root JSON value to query. May be
null.
Returns
JsonPathResult A JsonPathResult containing all matched nodes.
Evaluate(JsonNode?, JsonPathEvaluationMode)
JsonPath.csEvaluates this JSONPath expression against a JSON value.
public JsonPathResult Evaluate(JsonNode? root, JsonPathEvaluationMode mode)Parameters
rootJsonNode?- The root JSON value to query. May be
null. modeJsonPathEvaluationMode- The evaluation mode.
Returns
JsonPathResult A JsonPathResult containing all matched nodes.
Exceptions
JsonPathEvaluationException- The path cannot be evaluated in
JsonPathEvaluationMode.Strictmode.
Evaluate(JsonNode?, JsonPathEvaluationOptions, JsonPathEvaluationMode)
JsonPath.csEvaluates 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)Evaluate(Utf8JsonReader)
JsonPath.csEvaluates 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
readerUtf8JsonReader- 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. UseJsonCommentHandling.Skipinstead. 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.
EvaluateStream(Stream, JsonReaderOptions)
JsonPath.csEvaluates 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
utf8JsonStream- The UTF-8 JSON data. The stream is read up to its end, and is not disposed.
readerOptionsJsonReaderOptions- 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
ArgumentNullExceptionutf8Jsonisnull.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.csEvaluates 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
utf8JsonStream- The UTF-8 JSON data. The stream is read up to its end, and is not disposed.
readerOptionsJsonReaderOptions- The options of the reader, such as the maximum depth or whether comments are allowed.
cancellationTokenCancellationToken- 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
ArgumentNullExceptionutf8Jsonisnull.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.csEvaluates this JSONPath expression and returns the first matched value, or null when there is no match.
public JsonElement? EvaluateValue(JsonDocument? root)Parameters
rootJsonDocument?- 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.csEvaluates this JSONPath expression and returns the first matched value, or null when there is no match.
public JsonElement? EvaluateValue(JsonDocument? root, JsonPathEvaluationMode mode)Parameters
rootJsonDocument?- The root JSON document to query. May be
null. modeJsonPathEvaluationMode- 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.Strictmode.
EvaluateValue(JsonDocument?, JsonPathEvaluationOptions, JsonPathEvaluationMode)
JsonPath.csReturns 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)EvaluateValue(JsonElement)
JsonPath.csEvaluates this JSONPath expression and returns the first matched value, or null when there is no match.
public JsonElement? EvaluateValue(JsonElement root)Parameters
rootJsonElement- The root JSON element to query.
Returns
JsonElement? The first matched value, or null when there is no match.
EvaluateValue(JsonElement, JsonPathEvaluationMode)
JsonPath.csEvaluates this JSONPath expression and returns the first matched value, or null when there is no match.
public JsonElement? EvaluateValue(JsonElement root, JsonPathEvaluationMode mode)Parameters
rootJsonElement- The root JSON element to query.
modeJsonPathEvaluationMode- 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.Strictmode.
EvaluateValue(JsonElement, JsonPathEvaluationOptions, JsonPathEvaluationMode)
JsonPath.csReturns 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)EvaluateValue(JsonNode?)
JsonPath.csEvaluateValue(JsonNode?, JsonPathEvaluationMode)
JsonPath.csEvaluates this JSONPath expression and returns the first matched value, or null when there is no match.
public JsonNode? EvaluateValue(JsonNode? root, JsonPathEvaluationMode mode)Parameters
rootJsonNode?- The root JSON value to query. May be
null. modeJsonPathEvaluationMode- 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.Strictmode.
EvaluateValue(JsonNode?, JsonPathEvaluationOptions, JsonPathEvaluationMode)
JsonPath.csReturns 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)Parse overloads
Parse(ReadOnlySpan<char>)
JsonPath.csParses a JSONPath expression from a character span.
public static JsonPath Parse(ReadOnlySpan<char> expression)Parameters
expressionReadOnlySpan<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.csParses an expression span using an immutable opt-in custom function registry.
public static JsonPath Parse(ReadOnlySpan<char> expression, JsonPathFunctionRegistry functions)Parse(string)
JsonPath.csParses a JSONPath expression.
Parameters
expressionstring- A valid JSONPath expression string (must start with
$).
Returns
JsonPath A parsed JsonPath instance.
Exceptions
ArgumentNullExceptionexpressionisnull.FormatException- The expression is not a well-formed or valid JSONPath query.
Parse(string, JsonPathFunctionRegistry)
JsonPath.csParses an expression using an immutable opt-in custom function registry.
public static JsonPath Parse(string expression, JsonPathFunctionRegistry functions)Remove(JsonNode?)
JsonPath.csRemoves the values that this query selects from a JSON value.
Parameters
rootJsonNode?- 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
JsonValuethat 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.csReplaces the values that this query selects in a JSON value.
Parameters
rootJsonNode?- The root JSON value to change. May be
null. valueJsonNode?- The new value. Each location receives a copy, so
valueis never attached toroot.
Returns
int The number of locations set.
Exceptions
InvalidOperationException- The query selects the root value, a location is part of a
JsonValuethat 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.csTryParse overloads
TryParse(ReadOnlySpan<char>, JsonPath?)
JsonPath.csTries to parse a JSONPath expression from a character span.
public static bool TryParse(ReadOnlySpan<char> expression, out JsonPath? result)Parameters
expressionReadOnlySpan<char>- A JSONPath expression.
resultJsonPath?- When this method returns, contains the parsed
JsonPathif parsing succeeded, ornullif it failed.
Returns
bool true if parsing succeeded; otherwise, false.
TryParse(ReadOnlySpan<char>, JsonPathFunctionRegistry, JsonPath?)
JsonPath.csTries 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)TryParse(string?, JsonPath?)
JsonPath.csTries to parse a JSONPath expression.
TryParse(string?, JsonPathFunctionRegistry, JsonPath?)
JsonPath.csTries to parse an expression using an immutable opt-in custom function registry.
public static bool TryParse(string? expression, JsonPathFunctionRegistry functions, out JsonPath? result)