gs-predicate/docs/predicates-json.md

Predicates: JSON

Refer to Terminology 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.

"some string"

Predicate:

{
    "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.

{ "x": "some string" }

Predicate:

{
    "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.

{
    "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:

{
    "data": {
        "things": [
            { "x": 100, "y": 200 }
        ]
    }
}

Predicate:

{
    "predicate": "json-value-equals",
    "parameters": {
        "queryString": "data.things[any].x",
        "value": 100
    }
}

Example: Value Equals (All)

The following scenario will match:

Input:

{
    "data": {
        "things": [
            { "x": 100, "y": 200 },
            { "x": 100, "y": 300 },
            { "x": 100, "y": 400 }
        ]
    }
}

Predicate:

{
    "predicate": "json-value-equals",
    "parameters": {
        "queryString": "data.things[all].x",
        "value": 100
    }
}

Example: Value Equals (Index)

The following scenario will match:

Input:

{
    "data": {
        "things": [
            { "x": 100, "y": 200 },
            { "x": 999, "y": 300 },
            { "x": 100, "y": 400 }
        ]
    }
}

Predicate:

{
    "predicate": "json-value-equals",
    "parameters": {
        "queryString": "data.things[1].x",
        "value": 999
    }
}