[Jsonpath] Early description of "selectors"

[Erik Auerswald <[e-mail]>]

Hello JSONPath Working Group,

thanks for your work on standardizing query expressions for JSON!

I have not yet used JSONPath and looked at the current I-D to learn
about it.  While reading draft-ietf-jsonpath-base-13, I wondered for
quite some time how "selectors" fit into a JSONPath expression.

I also wondered about the meaning of early examples using selector
lists inside a segment, e.g., "$..book[0,1]", and if this only supported
index selectors.  Next came the "$.o[*,*]" example, that additionally
showed wildcard selectors.  But only section 2.5.1 "Child Segment", much
later in the document, introduced the generic "comma-separated sequence
of selectors" without restriction to one or two selector variants.

Perhaps the initial descriptions of "segments" could be expanded a bit
to already mention "selectors"?

I'd like to suggest the following small additions to the early parts of
the draft:

1. Fill the square brackets in the definition of "segment" in the
   "Terminology" section 1.1 with "<selectors>":

   OLD:

     Segment:  One of the constructs which select children ([]) or
        descendants (..[]) of an input value.

   NEW:

     Segment:  One of the constructs which select children ([<selectors>])
        or descendants (..[<selectors>]) of an input value.

2. Fill the square brackets in the description in section 1.4.2 "Segments"
   with "<selectors>":

   OLD:

      Segments select children ([]) or descendants (..[]) of an input
      value.

   NEW:

      Segments select children ([<selectors>]) or descendants
      (..[<selectors>]) of an input value.

3. Mention in section 1.4.2 "Segments" that bracket notation allows to use
   one or more selectors per segment (and supports all selector variants):

   OLD:

      A JSONPath expression may use a combination of bracket and dot
      notations.

   NEW:

      Bracket notation supports all selector variants.  It also allows to
      use more than one selector per segment (commas between selectors).

      A JSONPath expression may use a combination of bracket and dot
      notations.

Best regards,
Erik

P.S. Please keep me in Cc: of replies, since I am not subscribed to this
     mailing list.