[Jsonpath] The draft: ambiguous language

[Daniel P <[e-mail]>]

My general comment is that there is a lot of ambiguous language in the
draft, and ambiguous language is the bane of implementers. Some
examples below:

One. "Data Item: A structure complying to the generic data model of
JSON, i.e., composed of containers such as arrays and maps (JSON
objects), and of atomic data such as null, true, false, numbers, and
text strings."

Why introduce the term "map" as the preferred (unparenthized) term?
RFC 8259 doesn't mention "map", it uses JSON object.  By following
"arrays and maps" with "(JSON objects)", it could be read that "arrays
and maps" will collectively be referred to as "JSON objects". Later in
the draft we read "the root object" ($) and "the current object" (@),
which almost suggest that that is the intended meaning.

My own view is that the terminology should stay consistent with RFC
8259, and that the word "object" should not be used for items that are
not JSON objects in the sense of RFC 8259.

What is the purpose of "such as" in the sentence? Aren't the
itemizations exclusive?

Two. "Since a JSON data item is usually anonymous and doesn't
necessarily have a "root member object", JSONPath used the abstract
name $ to refer to the top level object of the data item."

I realize this sentence is mostly copied from Goessner, but I didn't
understand it there either. Regarding "doesn't necessarily" have a
"root member object", what is that supposed to mean? It seems to me
that the root is _always_ going to be an anonymous JSON value, which,
when Goessner was writing, could be a JSON array or object, and since
RFC 8259, any JSON value.

Three.  "Where a JSONPath processor uses JSONPath expressions as
output paths, these will always be converted to the more general
bracket-notation."

For output paths, Goessner uses the term "normalized path
expressions", which should be unambiguously defined. For uniqueness,
in addition to avoiding dot-notation, there would need to be other
restrictions, including avoiding the descendant operator .., and
filters.

Four. "The symbol @ is used for the current object."

Only if you interpret "object" to mean _any_ JSON value. In the
example above this sentence,

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

the symbol @ refers to a JSON array, with a JavaScript like property "length".

That arrays must support a JavaScript like property length is not
explicitly stated in the draft, but is implied in two examples. This
should be clarified. Not all implementations do, for example,
implementations that support functions that can be invoked at the tail
end of a path typically support a function call length() instead.

I also think the @ notation could be better explained, this particular
reader struggled to understand what was meant by "current object" in
original Goessner, and had to figure it out from examples.

Daniel