Skip to main content

JSONPath Functions

Standard functions​

These are the standard, built-in functions available to JSONPath filters. You can also create your own function extensions.

count()​

count(nodes: JSONPathNodeList): number

Return the number of nodes in a node list. Usually, count() will be given a filter query as its argument, and a call to count() must be part of a comparison expression.

Example query
$.users[?count(@.*) > 2]

length()​

length(value: JSONValue): number | undefined

Return the length of a string or array, or the number of items in an object. Usually, length() will be given a filter query as its argument, and a call to length() must be part of a comparison expression.

Example query
$.users[?length(@) > 2]

match()​

match(value: string, pattern: string): boolean

Return true if value is a full match to the regular expression pattern, or false otherwise.

Example query
$.users[?match(@.name, '[Ss].*')]
search(value: string, pattern: string): boolean

Return true if value contains pattern, or false otherwise.

Example query
$.users[?search(@.name, '[Aa]')]

value()​

value(nodes: JSONPathNodeList): JSONValue | undefined

Return the value associated with the first node in nodes, if nodes has exactly one JSONPathNode. Usually, value() will be called with a filter query as its argument.

info

Filter queries that can result in at most one node are known as "singular queries", and all singular queries will be implicitly replaced with their value as required, without the use of value(). value() is useful when you need the value from a query that can, theoretically, return multiple nodes.

Well-typedness​

The JSONPath specification defines a type system for function expressions, and rules for how those types can be used within an expression. JSON P3 will throw a JSONPathTypeError at query compile time if it contains expressions that are not deemed to be well-typed.

Please see Section 2.4.3 Well-Typedness of Function Expressions.

Function extensions​

Add, remove or replace filter functions by updating the function register on a JSONPathEnvironment. It is a regular Map, mapping function names to objects implementing the FilterFunction interface.

info

You can update the function register on the default environment (import { DEFAULT_ENVIRONMENT } from "json-p3"), and use convenience functions like query() and compile(). Here we'll create a new JSONPathEnvironment, then use its methods directly.

Every filter function must define the types of its parameters and the type of its return value, according to the JSONPath specification's type system. This example implements a typeof() function, which accepts a parameter of ValueType and returns a ValueType.

import {
  FilterFunction,
  FunctionExpressionType,
  JSONPathEnvironment,
} from "json-p3";

class TypeOfFilterFunction implements FilterFunction {
  readonly argTypes = [FunctionExpressionType.ValueType];
  readonly returnType = FunctionExpressionType.ValueType;

  public call(value: unknown): string {
    return typeof value;
  }
}

We would then register an instance of TypeOfFilterFunction with a JSONPathEnvironment, and use the environment's query(), compile() or match() methods.

// .. continued from above
const env = new JSONPathEnvironment();
env.functionRegister.set("typeof", new TypeOfFilterFunction());

const nodes = env.query("$.users[?typeof(@.score) == 'number']", data);