uBO flavored JSONPath

The following documentation refers to the most recent implementation of "uBO flavored JSONPath" (uBO 1.72.0+) which is meant to be conform to "RFC 9535: JSONPath: Query Expressions for JSON". The legacy implementation was not conformant and should no longer be used starting with uBO 1.72.0, and legacy syntax should be replaced as soon as feasible -- eventually support for the legacy syntax will be dropped.

In order to keep compatibility of existing filter lists with the legacy implementation, filter list authors must prefix their JSONpath with v2: to ensure it is not interpreted using legacy implementation code paths. Eventually when support for the legacy implementation is completely removed, the prefix will become unnecessary.

uBO's JSONPath is a partial implementation of the official RFC9535, such that existing JSONPath tools (i.e. JSONPath Online Evaluator) can be used to help craft valid JSONPath queries. Not all the syntax details are supported because there were no need for them while a primary goal is to keep the JSONPath implementation small.

Not supported:

• Array slice selector: $[1:5:2], $..book[:2]
• Child segment with multiple filter selectors: $.o[?@<3, ?@>7]
• Selectors with logical operators: $.o[?@.u || @.x], $.o[?@>1 && @<4]
• Function-based selectors: $.a[?match(@.b, "[jk]")], $.a[?search(@.b, "[jk]")]
• Parenthesis in selectors: these are not required anyway as per spec

Supported:

• Root identifier: $
• Current node identifier: @
• Bracket-notation selector: $.o['j j'], $["'"]["@"]
• Dot-notation selector: $..j, $.store..price
• Wildcard selector: $[*], $.store.*
• Index selector: $[1], $..book[-1]
• Filter selector: $.a[?@>3.5], $..book[?@.price<10]
• Comparison operator in filter selectors: ==, !=, <. <=, >, >=

uBO's JSONPath implementation extends the syntax of the official spec in order to accomplish its duty as a filtering tool for filter list authors. Details of the extended syntax is documented in the following sections.

Regex-based selector

Ability to select using a regex, example: v2:$../^b/..price. Regex-based selectors can be used with either the bracket- or dot-notation syntax, so this also works: v2:$..[/^b/]..price.

String-related comparison operators

• ^=: to test that the string value looked up by the query starts with a specific pattern, examples:
  • v2:$..book[?@.author^="E"]
• $=: to test that the string value looked up by the query ends with a specific pattern, examples:
  • v2:$..book[?@.author$="h"]
• *=: to test that the string value looked up by the query includes a specific pattern, examples:
  • v2:$..book[?@.author*="n"]
• =/.../: to test that the string value looked up by the query matches a specific regex, examples:
  • v2:$..book[?@.author=/R/]

Assignments

Typically when a JSONPath query results in a non empty resultset, the looked up properties are removed from the target object:

• v2:$..book[?@.price>10] will remove all the books which price is higher than 10.

When a JSONPath query is used in a trusted context, new values can be assigned, example:

• v2:$..book[?@.price>20].price=0 will look up all the books which price is higher than 20 and set their price to 0.

If present, the assignment value must be one of:

• A JSON-parseable value: =0, ="zero", ={"a":1,"b":"foo","c":[]}, =["a","b",{"c":1}]
• +={...}, to add properties to a looked up object
• =repl({"pattern":"...","replacement":"..."}), to find pattern in a looked up string and replace it with replacement
• =repl({"regex":"...","replacement":"..."}), to execute a regex on a looked up string and replace matches with replacement
• =call([context, name, ...args]), to call a specific method on a specific instance using a specific list of arguments:
  • context is the context to be used for the call:
    • Use ${obj} to set the context to the target object, typically to call a specific method on an instance
    • Use null to call a global function
  • name is the name of the function to call, i.e. setAttribute, alert, etc.
  • ...args is the list of arguments to be used when calling the function or method:
    • Use ${obj} to replace an argument in the list with the looked up object
    • Use ${key} to replace an argument in the list with the looked up property name
    • Use ${val} to replace an argument in the list with the looked up property value
  • Example: v2:$.["onload","onerror"]=call(["${obj}","removeAttribute","${key}"])

Chaining

The official JSONPath specification does not support looking up properties in one path conditional to the existence (or absence) of a property in another path. This is often a requirement for filter list authors.

The solution for uBO's JSONPath implementation is to chain multiple ;-separated sub-queries, whereas processing is aborted when a segment in the chain fails to match a quantifier.

A quantifier is one of the forms {x}, {x,}, {,y}, {x,y}, and is used to either assert the presence of a specific number of matches in the resultset of a sub-query. Quantifiers can only be used in chained sub-queries, and never for the last sub-query in the chain. Example:

v2:$.store.bicycle{1,};$..book[?@.price<10]

The above query is composed of two chained sub-queries. The first one is to assert that the cardinality of $.store.bicycle must one or more. If the assertion fails, the whole query returns an empty set even if the second sub-query would otherwise return a non-empty resultset. When the quantifier is exactly {1,}, it can be omitted:

v2:$.store.bicycle;$..book[?@.price<10]

The quantifier can also be used to test for the absence of a property:

v2:$.store.bicycle{0};$..book[?@.price<10]