Draft: draft-ietf-jsonpath-base

Commentary: LGTM - as a first step to „ pull the cow from the ice “
Paragraph (version A):
The terminology of RFC8259 applies.
Paragraph (version A):
A JSONPath query is applied to a JSON value that is supplied to it as
its Argument.  The node referring to the entirety of this JSON value
is also referred to as its root node.
Paragraph (version A):
A JSON value, with an emphasis on its location within the
Argument.  I.e., a JSON value that is identical to or contained
within the JSON value to which the query is applied.  A node can
be viewed as a combination of a (1) JSON value and (2) its
location in the Argument; the latter can, if desired, be
represented as an Output Path.
Paragraph (version A):
A JSON object as defined in RFC8259.  Never used in its generic
sense, e.g., for programming language objects.
Paragraph (version A):
A JSON array as defined in RFC8259.  Never used in its generic
sense, e.g., for programming language objects.
Paragraph (version A):
A non-negative integer that identifies a specific element in an
array.  The term, in particular in the form indexing, is also
sometimes used for either an index or a member name, when both
arrays and objects can be fed to the indexing operation.
Paragraph (version A):
Short name for the JSON value a JSONPath expression is applied to.
Paragraph (version A):
Output of applying a query to an argument: a list of nodes within
that argument.  While this list can be represented in JSON, e.g.
as an array, the nodelist is an abstract concept unrelated to JSON
values.
Paragraph (version B):
The terminology of RFC8259 applies except where clarified below.
Definitions for "Object", "Array", and "Number" remain unchanged.
Importantly "object" and "array" in particular do not take on a
generic meaning, such as they would in a general programming context.
Paragraph (version B):
Additional terms used in this specification are defined below.
Paragraph (version B):
The name in a name/value pair constituting a member.  (Also known
as "key", "tag", or "label".)  This is also used in RFC8259, but
that specification does not formally define it.  It is included
here for completeness.
Paragraph (version B):
A non-negative integer that identifies a specific element in an
array.
Paragraph (version B):
Short name for the value a JSONPath expression is applied to.
Paragraph (version B):
The pair of a value along with its location within the argument.
Paragraph (version B):
The unique node whose value is the entire argument.
Paragraph (version B):
A list of nodes.  The output of applying a query to an argument is
manifested as a list of nodes.  While this list can be represented
in JSON, e.g. as an array, the nodelist is an abstract concept
unrelated to JSON values.
Paragraph (version B):
A query is applied to an argument, and the output is a nodelist.
Paragraph (version A):
in popular programming languages such as JavaScript, Python and PHP,
with a variable x holding the JSON value.  Here we observe that such
languages already have a fundamentally XPath-like feature built in.
Paragraph (version B):
in popular programming languages such as JavaScript, Python and PHP,
with a variable x holding the argument.  Here we observe that such
languages already have a fundamentally XPath-like feature built in.
Paragraph (version A):
JSONPath expressions always apply to a JSON value in the same way as
XPath expressions are used in combination with an XML document.
Since a JSON value is anonymous, JSONPath uses the abstract name "$"
to refer to the entire JSON value ("root node") of the argument.
Paragraph (version B):
JSONPath expressions always apply to a value in the same way as XPath
expressions are used in combination with an XML document.  Since a
value is anonymous, JSONPath uses the abstract name "$" to refer to
the root node of the argument.
Paragraph (version A):
A JSONPath is a string which selects zero or more nodes of a piece of
JSON.  A valid JSONPath conforms to the ABNF syntax defined by this
document.
Paragraph (version A):
A JSONPath MUST be encoded using UTF-8.  To parse a JSONPath
according to the grammar in this document, its UTF-8 form SHOULD
first be decoded into Unicode code points as described in RFC3629.
Paragraph (version B):
A JSONPath query is a string which selects zero or more nodes of a
piece of JSON.  A valid query conforms to the ABNF syntax defined by
this document.
Paragraph (version B):
A query MUST be encoded using UTF-8.  To parse a query according to
the grammar in this document, its UTF-8 form SHOULD first be decoded
into Unicode code points as described in RFC3629.
Paragraph (version A):
The well-formedness and the validity of JSONPath queries are
independent of the JSON value the query is applied to; no further
errors can be raised during application of the query to a JSON value.
Paragraph (version B):
The well-formedness and the validity of JSONPath queries are
independent of the value the query is applied to; no further errors
can be raised during application of the query to a value.
Paragraph (version A):
The JSONPath query is a sequence of zero or more _selectors_, each of
which is applied to the result of the previous selector and provides
input to the next selector.  These results and inputs take the form
of a _nodelist_, i.e., a sequence of zero or more nodes.
Paragraph (version A):
The nodelist going into the first selector contains a single node,
holding the Argument.  The nodelist resulting from the last selector
is presented as the result of the query; depending on the specific
API, it might be presented as an array of the JSON values at the
nodes, an array of Output Paths referencing the nodes, or both -- or
some other representation as desired by the implementation.  Note
that the API must be capable of presenting an empty nodelist as the
result of the query.
Paragraph (version A):
A selector performs its function on each of the nodes in its input
nodelist, during such a function execution, such a node is referred
to as "current node".  Each of these function executions produces a
result nodelist, which are then combined by algorithm _combine1_ into
the result of the selector.
Paragraph (version A):
The processing within a selector may execute nested JSONPath queries,
which are in turn handled with the processing model defined here.
Typically, the argument to that query will be the current node of the
selector or a set of nodes subordinate to that current node.
Paragraph (version A):
Syntactically, a JSONPath consists of a root selector ("$"), which
stands for a nodelist that contains the root node of the Argument,
followed by a possibly empty sequence of _selectors_.
Paragraph (version A):
The root selector "$" not only selects the root node of the input
document, but it also produces as output a list consisting of one
node: the input JSON value.
Paragraph (version B):
In the processing model, a valid query is executed against a value,
the _argument_, and produces a list of zero or more nodes of the
value.
Paragraph (version B):
The query is a sequence of zero or more _selectors_, each of which is
applied to the result of the previous selector and provides input to
the next selector.  These results and inputs take the form of a
_nodelist_, i.e., a sequence of zero or more nodes.
Paragraph (version B):
The nodelist going into the first selector contains a single node,
the argument.  The nodelist resulting from the last selector is
presented as the result of the query; depending on the specific API,
it might be presented as an array of the JSON values at the nodes, an
array of Output Paths referencing the nodes, or both -- or some other
representation as desired by the implementation.  Note that the API
must be capable of presenting an empty nodelist as the result of the
query.
Paragraph (version B):
A selector performs its function on each of the nodes in its input
nodelist, during such a function execution, such a node is referred
to as the "current node".  Each of these function executions produces
a nodelist, which are then combined by algorithm _combine1_ into the
result of the selector.
Paragraph (version B):
The processing within a selector may execute nested queries, which
are in turn handled with the processing model defined here.
Typically, the argument to that query will be the current node of the
selector or a set of nodes subordinate to that current node.
Paragraph (version B):
Syntactically, a JSONPath query consists of a root selector ("$"),
which stands for a nodelist that contains the root node of the
argument, followed by a possibly empty sequence of _selectors_.
Paragraph (version B):
The root selector "$" not only selects the root node of the argument,
but it also produces as output a list consisting of one node: the
argument itself.
Paragraph (version A):
For instance, with the Argument "{"a":[{"b":0},{"b":1},{"c":2}]}",
the JSONPath "$.a[*].b" selects the following list of nodes: "0", "1"
(denoted here by their value).  Let's walk through this in detail.
Paragraph (version A):
The JSONPath consists of "$" followed by three selectors: ".a",
"[*]", and ".b".
Paragraph (version A):
Firstly, "$" selects the root node which is the input document.  So
the result is a list consisting of just the root node.
Paragraph (version B):
For instance, with the 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).  Let's walk through this in detail.
Paragraph (version B):
The query consists of "$" followed by three selectors: ".a", "[*]",
and ".b".
Paragraph (version B):
Firstly, "$" selects the root node which is the argument.  So the
result is a list consisting of just the root node.
Paragraph (version A):
As a consequence of this approach, if any of the selectors selects no
nodes, then the whole JSONPath selects no nodes.
Paragraph (version B):
As a consequence of this approach, if any of the selectors selects no
nodes, then the whole query selects no nodes.
Paragraph (version A):
TBD: Define a media type for JSON Path expressions.
Paragraph (version B):
TBD: Define a media type for JSONPath expressions.