The "current value" or "current node", and the meaning thereof

[danielaparker]

This post opens a discussion of the meaning of "current value" or "current node" in JSONPath, with comparisons to similar concepts in JMESPath and XPath 3.1. (I've moved content here from a comment in the related but soon to be closed #59.)

First, consider the analogous notions of "current object", "current node", and "context item" in Goessner JSONPath, JMESPath, and XPath 3.1.

	Goessner JSONPath	JMESPath	XPath 3.1
What is it called?	"current object"1	"current node"2	"context item" (or "context node" if the context item is a node)3
Where is it defined?	Goessner	JMESPath Specification	XPath 3.1 W3C Recommendation
How is it represented?	@	@	.
How is it defined?	By example (see below) and "using the symbol '@' for the current object"	"The current-node token can be used to represent the current node being evaluated...At the start of an expression, the value of the current node is the data being evaluated by the JMESPath expression. As an expression is evaluated, the value the the current node represents MUST change to reflect the node currently being evaluated. "	"The context item is the item currently being processed. When the context item is a node, it can also be referred to as the context node. The context item is returned by an expression consisting of a single dot (.)."
How does it appear in the grammar?		current-node = "@"	ContextItemExpr | ::= | "."
Explicit or understood?	Always explicit	Usually understood - "JMESPath assumes that all function arguments operate on the current node unless the argument is a literal or number token. Because of this, an expression such as @.bar would be equivalent to just bar, so the current node is only allowed as a bare expression."	Sometimes explicit - .//para selects the para element descendants of the context node. Sometimes understood - para selects all para children of the context node
How is it used?	$.store.book[(@.length-1)].title $.store.book[?(@.price < 10)].title	foo[].[count(@), bar]4	.//para /books/book[fn:count(./author)>1])

1. In Goessner JSONPath, the term "object" used here seems to refer to any JSON value. The term "node" is only used when referring to XPATH 1.
2. In JMESPath, the term "node" is undefined, but can be considered synonymous with "JSON value". In JMESPath, results may be elements in the original JSON document, or newly created elements that don't exist in the JSON document, preserving paths into the original JSON document doesn't figure into it.
3. For XPath 3.1, "node" is defined in the XQuery and XPath Data Model 3.1 W3C Recommendation. Among other properties, each node must have a unique identity, distinct from all others. Element nodes have a property children and a property parent, possibly empty.
4. In this JMESPath expression, foo is understood to mean @.foo, and bar is understood to mean @.bar. The only place where the symbol @ is used explicitly is as a "bare expression", as shown in the argument to the count function.

"current object" in Goessner JSONPath as represented by @ is clearly underspecified, but can easily be understood in the more general sense in JMESPath, as "the node currently being evaluated", or in XPath 3.1, as " the item currently being processed".

The Goessner examples:

$.store.book[(@.length-1)].title                   (1)

$.store.book[?(@.price < 10)].title               (2)

are fully consistent with the more general sense. In (1), the "current value" @ represents the array $.store.book, in (2), the ? connotes iteration over the array, and @ represents an array element.

In my opinion, it's natural to generalize that at $, the current value @ represents the JSON document; at $.store, it represents the result of evaluating $.store, and so on.

[remorhaz]

Sounds reasonable. Legacy implementations don't show clear consensus on $[?(@.key)], but at least some of them (including JayWay's one) behave in the way you described.

Should we define "current value" only inside a filter explicitly? The only possible use outside of filter, as far as I can see it, is just replacing $ in the beginning; but in this case @ should represent the result of evaluating an empty string. So, this question may be related to the question "can $ in the beginning be optional"; and if yes - then empty string is evaluated equally to $, which makes your definition consistent outside of filter.