# 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
    }
}
```