JSONPath: Query expressions for JSON
draft-ietf-jsonpath-base-21

Received changes through RFC Editor sync (changed state to RFC, created became rfc relationship between draft-ietf-jsonpath-base and RFC 9535, changed IESG state to RFC Published)

[Ballot comment]
I've cleared my discuss position based on -20 (and hence not formally blocking), but there are still a few comments that it might be worth a bit more discussion on (via the existing email thread).

Thanks,
Rob

------
Previous comments (unchanged).

Minor level comments:

(4) p 10, sec 1.5.  JSONPath Examples

  Table 2 shows some JSONPath queries that might be applied to this
  example and their intended results.

Here, and in the table title below, it wasn't clear to me why it is "intended results" rather than just "results".


(5) p 12, sec 2.1.  Overview

  2.  Uses of function extensions must be _well typed_, as described in
      Section 2.4.

Isn't this an interop issue, hence shouldn't this be MUST?


(6) p 18, sec 2.3.1.3.  Examples

                      Table 5: Name selector examples

I think that it may be useful to also include an example that returns an object rather than just a value.


(7) p 18, sec 2.3.1.3.  Examples

                      Table 5: Name selector examples

Various table list "Result Paths", but I presume that these are only intended to help make the specification clear, and are not returned (by a standard implementation).  Would this be worth stating or clarifying?


(8) p 21, sec 2.3.3.2.  Semantics

  A negative index-selector counts from the array end.  For example,
  the selector -1 selects the last and the selector -2 selects the
  penultimate element of an array with at least two elements.  As with
  non-negative indexes, it is not an error if such an element does not
  exist; this simply means that no element is selected.

Perhaps "counts back from the array end" rather than "counts from the array end", or possibly it woudld be cleared to say that the absolute position is calculated by summing the length of the array with the negative index.  Otherwise, if counting for the end of the array, it isn't clear to me why -1 doesn't return the penultimate item, other than that not being helpful, of course.


(9) p 28, sec 2.3.5.1.  Syntax

  singular-query      = rel-singular-query / abs-singular-query
  rel-singular-query  = current-node-identifier singular-query-segments
  abs-singular-query  = root-identifier singular-query-segments
  singular-query-segments = *(S (name-segment / index-segment))
  name-segment        = ("[" name-selector "]") /
                        ("." member-name-shorthand)
  index-segment      = "[" index-selector "]"

Minor comment, there is no "intro" text above the "singular-query" block of ABNF so it reads a bit like it is part of the "Comparison expressions" text.


(10) p 29, sec 2.3.5.2.  Semantics

  The filter selector works with arrays and objects exclusively.  Its
  result is a list of _zero_, _one_, _multiple_ or _all_ of their array
  elements or member values, respectively.  Applied to primitive
  values, it selects nothing.

By "selects nothing" this presumably means that it returns an empty nodelist, i.e., and hence the JsonPath expression is likely to return nothing, as opposed to "does nothing" and the it just moves on to the next selector.  I think that the current text is probably obvious enough, but flagging just in case you want to consider rewording it.


(11) p 30, sec 2.3.5.2.1.  Existence Tests

  *  they work with queries that select structured values.
  To examine the value of a node selected by a query, an explicit
  comparison is necessary.  For example, to test whether the node
  selected by the query @.foo has the value null, use @.foo == null
  (see Section 2.6) rather than the negated existence test !@.foo
  (which yields false if @.foo selects a node, regardless of the node's
  value).

I presume that there is no way to change this, but from a correctness perspective, I wish that the existance check had to be explicit, (e.g., perhaps by a function call), to avoid the likely common mistake you describe above, particularly if the test is against a boolean value.  Possibly giving the example for the boolean value case may also be helpful to be explicit here.


(12) p 47, sec 2.5.2.3.  Examples

                  Table 16: Descendant segment examples

The row for "$..[*] $..*" is not clear to me.  I presume that this is meant the same query written two different ways rather than a single query?



Nit level comments:

(13) p 14, sec 2.1.3.  Example

  Consider this example.  With the query argument
  {"a":[{"b":0},{"b":1},{"c":2}]}, the query $.a[*].b selects the
  following list of nodes: 0, 1 (denoted here by their value).

As a very minor comment, for this example, and others in this section, you are generally eliding spaces (after : and ,) which makes reading the examples slightly harder.  I note in other places you do seem to include whitespace in the queries/results.

Regards,
Rob

[Ballot comment]
Thanks for the work done in this document. Not easy to herd existing implementations around a specification.

Due to $dayjob and vacations, I only had time for a quick review. No need to reply, but answers will be read with interest.

Hope this helps

-éric

## Figure 1

Just wonder why book is an array and bicycle is not.

## Section 2.3.5.2.2

From my reading of the '<' operator, strings are compared only to unicode ignoring any collation sequence, i.e., "eric" < "zoe" < "éric", which is weird...

Possibly due to my quick browsing through the I-D, but is there a way to make case-insensitive comparaison ? "2001:DB8::A" == "2001:db8::a" ?

[Ballot discuss]
Hi,

Thanks for this document, and thanks Joe for his review.  I agree with Joe and Warren that this specification is well written and clear, and much better than the XPath spec ;-).

However, I'm flagging a DISCUSS because there are 3 points that I think make the specification unclear and need to be addressed (or at least discussed) before this doc is approved.  I think/hope that it should be trivial to clarify these (if necessary).

(1) p 12, sec 2.1.  Overview                                                                                                                                                                                                                               
                                                                                                                                                                                                                                                           
    Specifically, if a valid JSONPath query is evaluated                                                                                                                                                                                                   
  against a structured value whose size does not fit in the range of                                                                                                                                                                                       
  exact values, interfering with the correct interpretation of the                                                                                                                                                                                         
  query, the implementation MUST provide an indication of overflow.                                                                                                                                                                                       
                                                                                                                                                                                                                                                           
I found this paragraph to be not particularly clear.  Is this saying that using a value larger than 2^53 as an integer will cause problems?                                                                                                                 
                                                                                                                                                                                                                                                           
                                                                                                                                                                                                                                                           
(2) p 29, sec 2.3.5.1.  Syntax                                                                                                                                                                                                                             
                                                                                                                                                                                                                                                           
                  Table 10: Filter expression operator                                                                                                                                                                                                     
                                precedence                                                                                                                                                                                                                 
                                                                                                                                                                                                                                                           
Should function invocation be part of this list (although not an operator)?  Otherwise, I don't recall seeing anything about precedence or operators vs functions.                                                                                                                                               
                                                                                                                                                                                                                                                           
                                                                                                                                                                                                                                                           
(3) p 33, sec 2.3.5.3.  Examples                                                                                                                                                                                                                           
                                                                                                                                                                                                                                                           
  Comparisons:                                                                                                                                                                                                                                             
    +========================+========+============================+                                                                                                                                                                                       
    |      Comparison      | Result |          Comment          |                                                                                                                                                                                       
    +========================+========+============================+
    | $.absent1 == $.absent2 |  true  |      Empty nodelists      |
    +------------------------+--------+----------------------------+
    | $.absent1 <= $.absent2 |  true  |      == implies <=        |
    +------------------------+--------+----------------------------+
    |    $.absent == 'g'    | false  |      Empty nodelist      |
    +------------------------+--------+----------------------------+
    | $.absent1 != $.absent2 | false  |      Empty nodelists      |
    +------------------------+--------+----------------------------+
    |    $.absent != 'g'    |  true  |      Empty nodelist      |
    +------------------------+--------+----------------------------+
    |        1 <= 2        |  true  |    Numeric comparison    |
    +------------------------+--------+----------------------------+
    |        1 > 2          | false  | Strict, numeric comparison |
    +------------------------+--------+----------------------------+
    |      13 == '13'      | false  |      Type mismatch        |
    +------------------------+--------+----------------------------+
    |      'a' <= 'b'      |  true  |    String comparison      |
    +------------------------+--------+----------------------------+
    |      'a' > 'b'        | false  | Strict, string comparison  |
    +------------------------+--------+----------------------------+
    |    $.obj == $.arr    | false  |      Type mismatch        |
    +------------------------+--------+----------------------------+
    |    $.obj != $.arr    |  true  |      Type mismatch        |
    +------------------------+--------+----------------------------+
    |    $.obj == $.obj    |  true  |    Object comparison      |
    +------------------------+--------+----------------------------+
    |    $.obj != $.obj    | false  |    Object comparison      |
    +------------------------+--------+----------------------------+
    |    $.arr == $.arr    |  true  |      Array comparison      |
    +------------------------+--------+----------------------------+
    |    $.arr != $.arr    | false  |      Array comparison      |
    +------------------------+--------+----------------------------+
    |      $.obj == 17      | false  |      Type mismatch        |
    +------------------------+--------+----------------------------+
    |      $.obj != 17      |  true  |      Type mismatch        |
    +------------------------+--------+----------------------------+
    |    $.obj <= $.arr    | false  | Objects and arrays are not |
    |                        |        |          ordered          |
    +------------------------+--------+----------------------------+
    |    $.obj < $.arr      | false  | Objects and arrays are not |
    |                        |        |          ordered          |
    +------------------------+--------+----------------------------+
    |    $.obj <= $.obj    |  true  |      == implies <=        |
    +------------------------+--------+----------------------------+
    |    $.arr <= $.arr    |  true  |      == implies <=        |
    +------------------------+--------+----------------------------+
    |      1 <= $.arr      | false  |  Arrays are not ordered  |
    +------------------------+--------+----------------------------+
    |      1 >= $.arr      | false  |  Arrays are not ordered  |
    +------------------------+--------+----------------------------+
    |      1 > $.arr        | false  |  Arrays are not ordered  |
    +------------------------+--------+----------------------------+
    |      1 < $.arr        | false  |  Arrays are not ordered  |
    +------------------------+--------+----------------------------+
    |      true <= true      |  true  |      == implies <=        |
    +------------------------+--------+----------------------------+
    |      true > true      | false  |  Booleans are not ordered  |
    +------------------------+--------+----------------------------+

The comment "Arrays are not ordered" could be misinterpreted.  May "Array comparisons are not ordered"?  A similar comment applies to "Objects and arrays are not ordered" above.

[Ballot comment]
Minor level comments:

(4) p 10, sec 1.5.  JSONPath Examples

  Table 2 shows some JSONPath queries that might be applied to this
  example and their intended results.

Here, and in the table title below, it wasn't clear to me why it is "intended results" rather than just "results".


(5) p 12, sec 2.1.  Overview

  2.  Uses of function extensions must be _well typed_, as described in
      Section 2.4.

Isn't this an interop issue, hence shouldn't this be MUST?


(6) p 18, sec 2.3.1.3.  Examples

                      Table 5: Name selector examples

I think that it may be useful to also include an example that returns an object rather than just a value.


(7) p 18, sec 2.3.1.3.  Examples

                      Table 5: Name selector examples

Various table list "Result Paths", but I presume that these are only intended to help make the specification clear, and are not returned (by a standard implementation).  Would this be worth stating or clarifying?


(8) p 21, sec 2.3.3.2.  Semantics

  A negative index-selector counts from the array end.  For example,
  the selector -1 selects the last and the selector -2 selects the
  penultimate element of an array with at least two elements.  As with
  non-negative indexes, it is not an error if such an element does not
  exist; this simply means that no element is selected.

Perhaps "counts back from the array end" rather than "counts from the array end", or possibly it woudld be cleared to say that the absolute position is calculated by summing the length of the array with the negative index.  Otherwise, if counting for the end of the array, it isn't clear to me why -1 doesn't return the penultimate item, other than that not being helpful, of course.


(9) p 28, sec 2.3.5.1.  Syntax

  singular-query      = rel-singular-query / abs-singular-query
  rel-singular-query  = current-node-identifier singular-query-segments
  abs-singular-query  = root-identifier singular-query-segments
  singular-query-segments = *(S (name-segment / index-segment))
  name-segment        = ("[" name-selector "]") /
                        ("." member-name-shorthand)
  index-segment      = "[" index-selector "]"

Minor comment, there is no "intro" text above the "singular-query" block of ABNF so it reads a bit like it is part of the "Comparison expressions" text.


(10) p 29, sec 2.3.5.2.  Semantics

  The filter selector works with arrays and objects exclusively.  Its
  result is a list of _zero_, _one_, _multiple_ or _all_ of their array
  elements or member values, respectively.  Applied to primitive
  values, it selects nothing.

By "selects nothing" this presumably means that it returns an empty nodelist, i.e., and hence the JsonPath expression is likely to return nothing, as opposed to "does nothing" and the it just moves on to the next selector.  I think that the current text is probably obvious enough, but flagging just in case you want to consider rewording it.


(11) p 30, sec 2.3.5.2.1.  Existence Tests

  *  they work with queries that select structured values.
  To examine the value of a node selected by a query, an explicit
  comparison is necessary.  For example, to test whether the node
  selected by the query @.foo has the value null, use @.foo == null
  (see Section 2.6) rather than the negated existence test !@.foo
  (which yields false if @.foo selects a node, regardless of the node's
  value).

I presume that there is no way to change this, but from a correctness perspective, I wish that the existance check had to be explicit, (e.g., perhaps by a function call), to avoid the likely common mistake you describe above, particularly if the test is against a boolean value.  Possibly giving the example for the boolean value case may also be helpful to be explicit here.


(12) p 47, sec 2.5.2.3.  Examples

                  Table 16: Descendant segment examples

The row for "$..[*] $..*" is not clear to me.  I presume that this is meant the same query written two different ways rather than a single query?



Nit level comments:

(13) p 14, sec 2.1.3.  Example

  Consider this example.  With the query argument
  {"a":[{"b":0},{"b":1},{"c":2}]}, the query $.a[*].b selects the
  following list of nodes: 0, 1 (denoted here by their value).

As a very minor comment, for this example, and others in this section, you are generally eliding spaces (after : and ,) which makes reading the examples slightly harder.  I note in other places you do seem to include whitespace in the queries/results.

Regards,
Rob

[Ballot comment]
Staling a quote from Joe Clarke's OpsDir review (https://datatracker.ietf.org/doc/review-ietf-jsonpath-base-16-opsdir-lc-clarke-2023-08-02/) "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."

This is a remarkably well written document - thank you! In fact, it is so well written that I suddenly find that I'm able to understand some of the XPath concepts (I'd usually avoid XPath like the plague and hand-parse XML...)



Thank you very much to Joe for his OpsDir review, and to the authors for addressing the comments.

[Ballot comment]
Thank you to Dan Harkins for the SECDIR review.

** Section 4.2.  Recommend unpacking “translated” to be more specific.

OLD
  These variables need to be translated into the
  form they take in a JSONPath query, e.g., by escaping string
  delimiters, or by only allowing specific constructs such as .name to
  be formed when the given values allow that.

NEW
These input variables will need to be validated against application-specific constraints (e.g., only allowing specific constructs such as .name to be formed when the given values allow that) and reformatted (e.g., by escaping string delimiters).

** Section 4.2.  I found the language of “Availability, Confidentiality, and Integrity breaches” generic.  Consider:

OLD
  Failure to perform these
  translations correctly can lead to unexpected failures, which can
  lead to Availability, Confidentiality, and Integrity breaches, in
  particular if an adversary has control over the values (e.g., by
  entering them into a Web form).  The resulting class of attacks,
  _injections_ (e.g., SQL injections), is consistently found among the
  top causes of application security vulnerabilities and requires
  particular attention.

NEW
In certain applications (e.g., a web-form), an adversary might be able to directly control the input into a JSONPath.  Failure to validate and escape input can result in variety of injection attacks whose result could include compromise of the endpoint running the application and arbitrary code execution; corruption or alteration of data assessable to the endpoint (e.g., SQL injection); or altering the security context of execution (e.g., XSS).

[Ballot comment]
Thanks for the hard work put behind this specification. I have not found transport related issues in my review and the overall document looks good to me.

[Ballot comment]
# GEN AD review of draft-ietf-jsonpath-base-19

CC @larseggert

Thanks to Linda Dunbar for the General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/cnQJKq1Dow65ZjgWZxwNUZpVPxE).

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### URLs

These URLs in the document can probably be converted to HTTPS:

* http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf

### Grammar/style

#### Section 1.1, paragraph 12
```
recursively. More formally, the descendants relation between nodes is the tr
                                ^^^^^^^^^^^
```
An apostrophe may be missing.

#### Section 1.5, paragraph 3
```
book[?@.isbn] | all books with an ISBN number | +------------------------+---
                                  ^^^^^^^^^^^
```
This phrase is redundant ("N" stands for "number"). Consider using "ISBN".

#### Section 1.5, paragraph 6
```
as a JSONPath query needs to be _well formed_ and _valid_. A string is a well
                                ^^^^^^^^^^^
```
This word is normally spelled with a hyphen.

#### Section 1.5, paragraph 6
```
error for any query which is not well formed and valid. The well-formedness
                                ^^^^^^^^^^^
```
This word is normally spelled with a hyphen.

#### Section 2.3.4.2.2, paragraph 9
```
filter expression is composed of side-effect free constituents, the order of
                                ^^^^^^^^^^^
```
Did you mean "side effect" (=adverse effect, unintended consequence)? Open
compounds are not hyphenated.

#### Section 2.3.5.3, paragraph 11
```
ined such that its evaluation is side-effect free, i.e., all possible orders
                                ^^^^^^^^^^^
```
Did you mean "side effect" (=adverse effect, unintended consequence)? Open
compounds are not hyphenated.

#### Section 2.3.5.3, paragraph 12
```
n expressions in a query must be well formed (by conforming to the above ABNF
                                ^^^^^^^^^^^
```
This word is normally spelled with a hyphen.

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF], You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT].

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments
[IRT]: https://github.com/larseggert/ietf-reviewtool

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-jsonpath-base-16. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator has a question about the second action requested in the IANA Considerations section of this document.

The IANA Functions Operator understands that, upon approval of this document, there are two actions which we must complete.

First, in the application namespace in the Media Types registry group located at:

https://www.iana.org/assignments/media-types/

a single new media type will be registered as follows:

Name: jsonpath
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

Second, a new registry is to be created called the Function Extensions sub-registry.


IANA QUESTION -> Wherever possible, IANA prefers that the word "Registry" be omitted from registry names, unless doing so will cause confusion. Is "Function Extensions" an acceptable registry name?


The new registry is to be created in a new registry group at:

https://www.iana.org/protocols

with a reference of [ RFC-to-be ]. The name of the new registry group will be JSONPath Parameters.

The new Function Extensions registry will be managed via Expert Review as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Function Name Brief description Parameters Result Change Controller Reference
---------------+----------------+-----------+------+-----------------+-----------
length length of string, array, object ValueType ValueType IETF [ RFC-to-be ]
count size of nodelist NodesType ValueType IETF [ RFC-to-be ]
match regular expression full match ValueType, ValueType LogicalType IETF [ RFC-to-be ]
search regular expression substring match ValueType, ValueType LogicalType IETF [ RFC-to-be ]
value value of single node in nodelist NodesType ValueType IETF [ RFC-to-be ]

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

David Dong
IANA Services Sr. Specialist

The following Last Call announcement was sent out (ends 2023-08-09):

From: The IESG
To: IETF-Announce
CC: draft-ietf-jsonpath-base@ietf.org, jsonpath-chairs@ietf.org, jsonpath@ietf.org, superuser@gmail.com, tbray@textuality.com
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (JSONPath: Query expressions for JSON) to Proposed Standard


The IESG has received a request from the JSON Path WG (jsonpath) to consider
the following document: - 'JSONPath: Query expressions for JSON'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2023-08-09. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  JSONPath defines a string syntax for selecting and extracting JSON
  (RFC 8259) values from a JSON value.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/



No IPR declarations have been submitted directly on this I-D.

# Document Shepherd Write-Up for draft-ietf-jsonpath-base

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

As broad agreement as possible. The JSONPath working group list and meetings
hold very small attendance, but consensus for the document's adoption and
progress was, as a whole, consistent.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

It has been pointed out that there are JSONPath expressions which will work well
in popular implementations that are not blessed by this draft. However, we feel
that the WG charter has been met: To specify a useful subset of JSONPath
expression syntax such that any conforming expression should have a high
probability of correct interoperation (i.e. producing the same effect) in a wide
variety of implementations.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There is a large number of JSONPath implementations, including at least one for
every popular programming language. The goal of this WG was to produce a
specification such that JSONPath expressions conforming to it will have a high
probability of interoperating across a large number of these implementations.

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

We understand that draft-ietf-regext-rdap-redacted has taken a dependency on
this draft, and we have notified that WG of this request for publication.

6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

This document does propose creating an IANA registry for JSONPath extension
functions, with care to specifying a process similar to other such
registries.

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

This draft contains no YANG modules.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

Tooling has been written by the authors and made public along with the document
itself to validate and test the ABNF present in it, which is present in the
document's Github Repository.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

Note that reference [6] is a broken link.  Since this draft specifies an
extremely limited string syntax for a single narrow use case, it seems
unlikely that it would encounter the sort of issues raised in this question.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed Standard. Since it is designed for use by people who write JSONPath
expressions and the software that processes them, this seems like the appropriate
type of publication.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

We have been diligent about Note Well protocol, and the authors have been
reminded to ensure their IPR disclosure obligations are fulfilled where
appropriate.

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes. There are three editors.

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

The current version of the document has minor nits reported by idnits:

    Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 12 comments (--).

However these appear to be false positives. I believe those aside, the structure and
sections as described in the Content Guidelines are in check.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

We believe the references are in the correct sections.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

All normative references are publicly available documents.

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No, there are no downward references.  Idnits thinks [Unicode] is one but we
assume this can be ignored.

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

There is a normative reference to draft-ietf-jsonpath-iregexp-05 whose current
status is IESG Evaluation.

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No other document statuses will be impacted.

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

The draft registers a new media type, application/jsonpath.  It also defines
a registry for JSONPath extension functions. This was one of the most
heavily-discussed parts of the document and I believe it is in a satisfactory
state.

21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

The draft specifies a new "Function Extensions sub-registry" in a new "JSONPath
Parameters registry", with the policy "expert review", per Section 4.5 of [BCP26].
I believe the instructions are acceptably clear.


[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://trac.ietf.org/trac/ops/wiki/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://trac.ietf.org/trac/iesg/wiki/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/

# Document Shepherd Write-Up for draft-ietf-jsonpath-base

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

As broad agreement as possible. The JSONPath working group list and meetings
hold very small attendance, but consensus for the document's adoption and
progress was, as a whole, consistent.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

It has been pointed out that there are JSONPath expressions which will work well
in popular implementations that are not blessed by this draft. However, we feel
that the WG charter has been met: To specify a useful subset of JSONPath
expression syntax such that any conforming expression should have a high
probability of correct interoperation (i.e. producing the same effect) in a wide
variety of implementations.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There is a large number of JSONPath implementations, including at least one for
every popular programming language. The goal of this WG was to produce a
specification such that JSONPath expressions conforming to it will have a high
probability of interoperating across a large number of these implementations.

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

We understand that draft-ietf-regext-rdap-redacted has taken a dependency on
this draft, and we have notified that WG of this request for publication.

6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

This document does propose creating an IANA registry for JSONPath extension
functions, with care to specifying a process similar to other such
registries.

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

This draft contains no YANG modules.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

Tooling has been written by the authors and made public along with the document
itself to validate and test the ABNF present in it, which is present in the
document's Github Repository.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

Note that reference [6] is a broken link.  Since this draft specifies an
extremely limited string syntax for a single narrow use case, it seems
unlikely that it would encounter the sort of issues raised in this question.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed Standard. Since it is designed for use by people who write JSONPath
expressions and the software that processes them, this seems like the appropriate
type of publication.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

We have been diligent about Note Well protocol, and the authors have been
reminded to ensure their IPR disclosure obligations are fulfilled where
appropriate.

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes. There are three editors.

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

The current version of the document has minor nits reported by idnits:

    Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 12 comments (--).

However these appear to be false positives. I believe those aside, the structure and
sections as described in the Content Guidelines are in check.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

We believe the references are in the correct sections.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

All normative references are publicly available documents.

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No, there are no downward references.  Idnits thinks [Unicode] is one but we
assume this can be ignored.

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

There is a normative reference to draft-ietf-jsonpath-iregexp-05 whose current
status is IESG Evaluation.

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No other document statuses will be impacted.

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

The draft registers a new media type, application/jsonpath.  It also defines
a registry for JSONPath extension functions. This was one of the most
heavily-discussed parts of the document and I believe it is in a satisfactory
state.

21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

The draft specifies a new "Function Extensions sub-registry" in a new "JSONPath
Parameters registry", with the policy "expert review", per Section 4.5 of [BCP26].
I believe the instructions are acceptably clear.


[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://trac.ietf.org/trac/ops/wiki/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://trac.ietf.org/trac/iesg/wiki/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/