187 lines
3.2 KiB
Markdown
187 lines
3.2 KiB
Markdown
# Predicates: JSON
|
|
|
|
Refer to [Terminology](./terminology.md) for information about specific terms.
|
|
|
|
[[_TOC_]]
|
|
|
|
## Description
|
|
|
|
These predicates are focused on reasoning about JSON values.
|
|
|
|
## Input
|
|
|
|
All key-value predicates accept a single input: some JSON value.
|
|
|
|
## JSON Query Strings
|
|
|
|
This library may query JSON values using query strings. These are deliberately
|
|
_not_ powerful and are not intended for `jq`-like functionality.
|
|
|
|
These query strings directly interact with the query system.
|
|
|
|
### Empty Query
|
|
|
|
An empty query string indicates that the predicate should address the value
|
|
verbatim.
|
|
|
|
#### Example: Plain String
|
|
|
|
**Input**:
|
|
|
|
This example will match.
|
|
|
|
```json
|
|
"some string"
|
|
```
|
|
|
|
**Predicate**:
|
|
|
|
```json
|
|
{
|
|
"predicate": "json-value-equals",
|
|
"parameters": {
|
|
"queryString": "",
|
|
"value": "some string"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Value (`.`)
|
|
|
|
The `.` operator accesses a named value by key within the current object. This
|
|
will not match if the current value is not an object.
|
|
|
|
#### Example: Mismatched Types
|
|
|
|
**Input**:
|
|
|
|
This example will not match, because the value at `x` is a string, so no key can
|
|
possibly be accessed through it.
|
|
|
|
```json
|
|
{ "x": "some string" }
|
|
```
|
|
|
|
**Predicate**:
|
|
|
|
```json
|
|
{
|
|
"predicate": "json-value-equals",
|
|
"parameters": {
|
|
"queryString": "x.y",
|
|
"value": "some string"
|
|
}
|
|
}
|
|
```
|
|
|
|
### JSON Key
|
|
|
|
Any text aside from `.` and the contents of `[]` is considered a key. These keys
|
|
refer to named elements of the JSON structure.
|
|
|
|
```json
|
|
{
|
|
"x": { "y": { "z": 100 } }
|
|
}
|
|
```
|
|
|
|
`x`, `y`, and `z` are all keys.
|
|
|
|
### Array Operator
|
|
|
|
The `[any|all|<index>]` syntax is used to reason about arrays:
|
|
|
|
- `[any]` indicates that the predicate will match if _any_ of the selected
|
|
values based on traversing the array match.
|
|
- `[all]` indicates that the predicate will match only if _all_ of the selected
|
|
values based on traversing the array match.
|
|
- `[<index>]` indicates that the predicate will match only if the specified
|
|
index exists within the array and the selected value at that index matches.
|
|
|
|
#### Example: Value Equals (Any)
|
|
|
|
The following scenario will _match_:
|
|
|
|
**Input**:
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"things": [
|
|
{ "x": 100, "y": 200 }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Predicate**:
|
|
|
|
```json
|
|
{
|
|
"predicate": "json-value-equals",
|
|
"parameters": {
|
|
"queryString": "data.things[any].x",
|
|
"value": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Example: Value Equals (All)
|
|
|
|
The following scenario will _match_:
|
|
|
|
**Input**:
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"things": [
|
|
{ "x": 100, "y": 200 },
|
|
{ "x": 100, "y": 300 },
|
|
{ "x": 100, "y": 400 }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Predicate**:
|
|
|
|
```json
|
|
{
|
|
"predicate": "json-value-equals",
|
|
"parameters": {
|
|
"queryString": "data.things[all].x",
|
|
"value": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Example: Value Equals (Index)
|
|
|
|
The following scenario will _match_:
|
|
|
|
**Input**:
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"things": [
|
|
{ "x": 100, "y": 200 },
|
|
{ "x": 999, "y": 300 },
|
|
{ "x": 100, "y": 400 }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Predicate**:
|
|
|
|
```json
|
|
{
|
|
"predicate": "json-value-equals",
|
|
"parameters": {
|
|
"queryString": "data.things[1].x",
|
|
"value": 999
|
|
}
|
|
}
|
|
```
|