Re: [Jsonpath] The draft: ambiguous language

[Carsten Bormann <[e-mail]>]

On 2020-12-07, at 21:38, Daniel P <[e-mail]> wrote:
> 
> My general comment is that there is a lot of ambiguous language in the
> draft,

As I said, work is needed.

I don’t plan to wait for adoption to start this work, so I created a PR:

https://github.com/jsonpath-standard/internet-draft/pull/46

> 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.  

Sure.  That is probably one of the mistakes that were made in defining the JSON terminology.

(Historically, what happened is that JavaScript has objects and atoms, but arrays are almost, but not entirely unlike objects.  When JSON was defined, it only called the maps “objects”, making the term object be ambiguous between its standard meaning and the “JSON object” meaning.  So to be unambiguous, it is best to have a term that unambiguously refers to “JSON objects”.  Maps naturally is that term, as would be longer terms such as dictionary.  If the WG does not like that term, we can of course revert to the more ambiguous JSON terminology.)

> By following
> "arrays and maps" with "(JSON objects)", it could be read that "arrays
> and maps" will collectively be referred to as "JSON objects”.

Yep, that is better the other way around.

> Later in
> the draft we read "the root object" ($) and "the current object" (@),
> which almost suggest that that is the intended meaning.

That should be item.

> 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.

I agree with the latter, but the reason for that is that the RFC 8259 terminology is confusing, so we could try to be more unambiguous.

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

Here, they are, so I replaced “such as” with “namely”.

> 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."

Yep, item (and no need to open the “member” discussion, see below).

> 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.

Many people who actually work with JSON don’t think in terms of data items, but in terms of members (entries of a map, i.e. key/value pairs).  Because JSON values are data items and members cannot exist outside a map, this creates a need to wrap those members into maps, and to unwrap them again what talking about them as members.

See https://ietf-wg-asdf.github.io/SDF/sdf.html#name-sdfchoice for an example how that thinking looks like in practice (yes, I wrote that, fully cognizant of the dissonance).

But that prevalent thinking does not have to be reflected here, and I’m proposing a change in the PR.

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

Fixed in PR.

> 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."

Fixed in PR.

> 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.

Defining .length is part of the outstanding work on the expression language.

> 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.

Please send text.

Grüße, Carsten