Preview

Lexical Scopes

JMESPath Community introduces the let() function to supports nested lexical scopes.

any let(object scope, expression->any expr)

The first argument is a JSON object that introduces a new lexical scope.

The second argument is an expression-type that is evaluated against the current context – i.e the current result of JMESPath evaluation context, that can be referred to by the @ node. The expression-type also has access to the stack of nested scopes.

Consider the following example:

let( {first_choice: first_choice}, &states[?name==first_choice].cities[] )
{"first_choice": "WA",
 "states": [
   {"name": "WA", "cities": ["Seattle", "Bellevue", "Olympia"]},
   {"name": "CA", "cities": ["Los Angeles", "San Francisco"]},
   {"name": "NY", "cities": ["New York City", "Albany"]}
 ]
}

When evaluating the states identifier, JMESPath no longer has access to the root scope, where first_choice is defined. Therefore, under normal circumstances, the filter-expression [?name === first_choice] would evaluate the first_choice identifier and return an empty array.

Instead, let() defined the identifier first_choice has taking the value of the property with the same name in the input JSON document. It effectively created a scope that can be represented as the following JSON object:

{ "first_choice": "WA" }

Therefore, when evaluating the filter-expression, the first_choice identifier is indeed defined, and produces the correct result.