Re: [Jsonpath] Opsdir last call review of draft-ietf-jsonpath-base-16

[Glyn Normington <[e-mail]>]

Hi Joe

Thanks for your feedback and I'm glad you enjoyed reading the spec. Perhaps
some editorial changes along the lines you suggest would be beneficial and
I'm not vetoing that if others agree, but let me try to justify the current
wording (inline below).

Regards,
Glyn
On Wed, 2 Aug 2023 at 18:00, Joe Clarke via Datatracker <[e-mail]>
wrote:

> Reviewer: Joe Clarke
> Review result: Ready
>
> I have been tasked to review this draft on behalf of OPS DIR.  When I got
> the
> assignment I thought, "64 pages of JSONPath...this is going to hurt."  But
> I
> found this document very well-written and informative.  All in all, it was
> an
> easy and enjoyable read.  I like that examples were both frequent and
> addressed
> positive and negative cases.
>
> I also liked how the authors addressed the origin of JSONPath and the
> rationale
> for creating a standard and why the standard might deviate from other
> usages.
> That said, I expected to see a more thorough comparison of the original
> unofficial JSONPath specification and what is being standardized.  For
> example,
> I like https://cburgmer.github.io/json-path-comparison/ as a means to
> know how
> JSONPath is implemented in each language.  I'm not saying this draft needs
> such
> an extensive comparison of all languages, but perhaps specific instances
> where
> it deviates from its direct and explicit ancestor would be helpful.
>

I have a couple of hesitations. Firstly, I'm not sure it would be
particularly helpful to pick one of the many existing variants of JSONPath
for comparison (even if it was the original). Secondly, one of the reasons
for standardising JSONPath was the lack of formality, completeness,
etc. in Gössner's
rather brief article. So I feel the comparison would end up being rather
shallow unless we attempted to compare Gössner two implementations which
would be an open-ended exercise.

I'm sure migration guides will arise naturally as implementations of the
JSONPath standard become more common. These can be written from the
perspective of a particular language implementation and how to migrate from
an older implementation to an implementation of the standard. I feel these
would be much more useful than a brief "diff" in the spec.


> I had two comments otherwise:
>
> * In Section 1.5, two of your examples use parentheses whereas in Section
> 1.4.3
> the book example filter does not.  I didn't find clear guidance on when to
> use
> the paren-expression and when not to.


When writing a JSONPath query that needs to work with both standard and
non-standard implementations, parentheses would be necessary. However, I
think we might suffer from scope creep if the spec was to discuss how to
support non-standard implementations. Other than that, using or omitting
the parentheses is a matter of taste and not something I would say the spec
needs to provide guidance on. I guess we could strip out the parentheses in
1.5 for consistency.


> * In Section 2.3.5.2, sentence, "Applied
> to primitive values, it selects nothing." my gut was perhaps an additional,
> "and MUST NOT raise and error" should be added to be explicit that in this
> case
> an empty nodelist is expected and not an error.  Moreover, as I read
> further
> and "Nothing" is called out as a special type, I felt some explicit text
> that
> an empty nodelist is returned would add clarity.
>
>
The overview in 2.1.2 states "A syntactically valid segment MUST NOT
produce errors when executing the query." This principle applies throughout
and I'd like to avoid repeating this in specific sections.

The confusion between an empty nodelist and "Nothing" is a concern and may
need more wording to sort out, but again I'd prefer not to scatter this
throughout the spec.