JSON expressions

Some filters take parameters that are JSON expressions. A JSON expression is a specification of a JSON path and value.

A JSON expression uses the name of the attributes (or indexes for arrays) in the document, and specifies their value. It either matches a document, or it does not.

At this point, the only supported operators are = (equals) and != (not equals). The values specified after the operator are stripped of any leading or trailing spaces, so if you need to do a match with a value that begins or ends with a space, you'll need to do that in the filter code.

The best way to explain JSON expressions is to demonstrate them. Let's assume that we're working against the following JSON document:

{
"fullName": "Jane Doe",
"age": 34,
"dues paid": true,
"addresses": {
"home":{
"city": "Peoria",
"state": "Illinois"
}
},
"pets": [
{
"species": "dog",
"name": "Max",
"weight": 25
},
{
"species": "iguana",
"name": "Darwin",
"weight": 8
}
]
}

The following JSON expressions will be satisfied by this document:

age=34
age != 35
age != null
dues paid = true
fullName=Jane Doe
fullName = regex:Jane.*
addresses.home.city = Peoria
addresses.home.state != Texas
pets != null
pets[1].species=iguana
pets[*].species=iguana

An array index of * means at least one member of the array must satisfy the condition.

The following JSON expressions will not be satisfied by this document:

age=67
age=null
age!=34
fullName=John Doe
addresses.home=null
foo.bar=123
pets[10].name=Fido
pets[*].weight=99

Multiple JSON expressions can be specified by separating them with semicolons (spaces before and after semicolons are ignored):

age=34; fullName!=Jimmy; pets[0].name=Max

Some filters will define a variable called matchPath that will contain the value of the path that caused the match. This allows your code in the filter to be able to find the part of the document that caused the match, which is useful when your JSON expressions contain *.