jmespath / jmespath/jmespath.jep

[Initial Feedback] Root Node Reference

Open
#36 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
10
Forks
3
PR merge metrics
No merged PRs in 30d

Description

# Root Reference

I would like to submit the following proposal, so that we can access root node from anywhere.

## Abstract

This document proposes grammar modifications to JMESPath
to support referring to the original input JSON document
inside an expression.

## Motivation

As a JMESPath expression is being evaluated, the current scope changes.
Given a simple sub expression such as `foo.bar`, first the `foo`
expression is evaluated with the starting input JSON document, and the
result of that expression is then used as the current scope when the
`bar` element is evaluated.

Once we’ve drilled down to a specific scope, there is no way, in the
context of the currently evaluated expression, to refer to any
elements outside of that element.

A common request when querying JSON objects is the ability to refer to
the input JSON document.

For example, suppose we had this data:

```
{
"first_choice": "WA",
"states": [
{"name": "WA", "cities": ["Seattle", "Bellevue", "Olympia"]},
{"name": "CA", "cities": ["Los Angeles", "San Francisco"]},
{"name": "NY", "cities": ["New York City", "Albany"]}
]
}
```

Let’s say we wanted to get the list of cities of the state corresponding
to our `first_choice` key. We’ll make the assumption that the state
names are unique in the `states` list. This is currently not possible
with JMESPath. In this example we can hard code the state `"WA"`:

```
states[?name==`"WA"`].cities
```

but it is not possible to base this on a value of `first_choice`, which comes from the parent element.
This JEP proposes a solution that makes this possible in JMESPath.

## Specification

The grammar will support a new token `$` that refers to the root of the original input JSON document.

The `$` token is inspired by the [JSONPath](https://goessner.net/articles/JsonPath/) specification which has a token with the same name.

The `$` token is also inspired by the [XPath](https://www.w3.org/TR/1999/REC-xpath-19991116) specification, where the `/` token designates the root of the original XML document.

This JEP introduces the following productions:

```
root-node = "$"
```

The `expression` production will also be updated like so:

```
expression =/ root-node
```

### Motivating Example

With these changes defined, the expression in the “Motivation” section can be be written as:

```
states[?name==$.first_choice].cities[]
```

Which evalutes to `["Seattle", "Bellevue", "Olympia"]`.

## Rationale

This JEP standardizes a common request when querying JSON document as seen in [existing library](https://github.com/nanoporetech/jmespath-ts) implementations.

Some alternatives to this JEP are considered. Most notably, the [Lexical Scoping](/jmespath/jmespath.jep/blob/main/proposals/0011-let-function.md) proposal introduces a `let` keyword that offers a more general and flexible way to achieve the desired result. For instance, with the `let` keyword, the expression in the “Motivation” section can be written as:

```
let $root = @ in states[?name==$root.first_choice].cities[]
```

Although the [Lexical Scoping](/jmespath/jmespath.jep/blob/main/proposals/0011-let-function.md) proposal covers this case in a more generic way, using the `$` root node reference provides a more succinct way to express a common case.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.