Re: [Jsonpath] The draft: ambiguous language

[Tim Bray <[e-mail]>]

To Carsten's point about what we call things, the number of distinguished
terms per RFC8259 is pretty small: JSON text, value, object, array, number,
string.  Having spent quite a bit of time specifying JSON DSLs, I find that
using just those terms doesn't seem to get in the way or cause problems, so
I'd argue that we should stick to them (and build up to higher-level
constructs as required for JSONPath).

On Mon, Dec 7, 2020 at 2:37 PM Carsten Bormann <[e-mail]> wrote:

> 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
>
> --
> Jsonpath mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/jsonpath
>