Draft: draft-ietf-jsonpath-base

Commentary: This is based on main , as  does n't seem to be able to base on timbray / main , which is the PR this is based on .  . 
 Please only look at 
 Rebased on main after merging  's PR . There now remains just the salient commit . 
 OK , resolving with main fixed the " files changed " view . 
 Looks like you already did that , thanks . 
 I think we need to qualify the defined term " argument " as " query argument " , to distinguish it from a function expression argument . 
 Making a PR right now ... 
 LGTM , after rebasing and sorting out a small merge issue .
Paragraph (version A):
This document models the argument as a tree of JSON values, each with
its own node.  A node is either the root node or one of its
descendants.
Paragraph (version A):
This document models the result of applying a query to the argument
as a nodelist (a list of nodes).
Paragraph (version A):
Nodes are the selectable parts of the argument.  The only parts of an
object that can be selected by a query are the member values.  Member
names and members (name/value pairs) cannot be selected.  Thus,
member values have nodes, but members and member names do not.
Similarly, member values are children of an object, but members and
member names are not.
Paragraph (version B):
This document models the query argument as a tree of JSON values,
each with its own node.  A node is either the root node or one of its
descendants.
Paragraph (version B):
This document models the result of applying a query to the query
argument as a nodelist (a list of nodes).
Paragraph (version B):
Nodes are the selectable parts of the query argument.  The only parts
of an object that can be selected by a query are the member values.
Member names and members (name/value pairs) cannot be selected.
Thus, member values have nodes, but members and member names do not.
Similarly, member values are children of an object, but members and
member names are not.
Paragraph (version A):
identifying nodes in the JSON argument.
Paragraph (version B):
identifying nodes in the JSON query argument.
Paragraph (version A):
A JSONPath expression is applied to a JSON value, known as the
argument.  The output is a nodelist.
Paragraph (version B):
A JSONPath expression is applied to a JSON value, known as the query
argument.  The output is a nodelist.
Paragraph (version A):
The root node identifier "$" refers to the root node of the argument,
i.e., to the argument as a whole.
Paragraph (version B):
The root node identifier "$" refers to the root node of the query
argument, i.e., to the argument as a whole.
Paragraph (version A):
The nodelist resulting from the root identifier contains a single
node, the argument.  The nodelist resulting from the last segment 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 Normalized Paths referencing the nodes, or both -- or some
other representation as desired by the implementation.  Note that an
empty nodelist is a valid query result.
Paragraph (version B):
The nodelist resulting from the root identifier contains a single
node, the query argument.  The nodelist resulting from the last
segment 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 Normalized Paths referencing the nodes, or
both -- or some other representation as desired by the
implementation.  Note that an empty nodelist is a valid query result.
Paragraph (version A):
Consider this example.  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).
Paragraph (version A):
Firstly, "$" produces a nodelist consisting of just the argument.
Paragraph (version B):
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).
Paragraph (version B):
Firstly, "$" produces a nodelist consisting of just the query
argument.
Paragraph (version A):
The root identifier "$" represents the root node of the argument and
produces a nodelist consisting of that root node.
Paragraph (version B):
The root identifier "$" represents the root node of the query
argument and produces a nodelist consisting of that root node.
Paragraph (version A):
A type is a set of instances.  Declared types enable checking a
JSONPath query for well-typedness independent of any argument the
JSONPath query is applied to.
Paragraph (version B):
A type is a set of instances.  Declared types enable checking a
JSONPath query for well-typedness independent of any query argument
the JSONPath query is applied to.
Paragraph (version A):
Attacks on availability may attempt to trigger unusually expensive
runtime performance exhibited by certain implementations in certain
cases.  (See RFC8949 for issues in hash-table implementations, and I-
D.draft-ietf-jsonpath-iregexp for performance issues in regular
expression implementations.)  Implementers need to be aware that good
average performance is not sufficient as long as an attacker can
choose to submit specially crafted JSONPath queries or arguments that
trigger surprisingly high, possibly exponential, CPU usage or, for
example via a naive recursive implementation of the descendant
segment, stack overflow.  Implementations need to have appropriate
resource management to mitigate these attacks.
Paragraph (version B):
Attacks on availability may attempt to trigger unusually expensive
runtime performance exhibited by certain implementations in certain
cases.  (See RFC8949 for issues in hash-table implementations, and I-
D.draft-ietf-jsonpath-iregexp for performance issues in regular
expression implementations.)  Implementers need to be aware that good
average performance is not sufficient as long as an attacker can
choose to submit specially crafted JSONPath queries or query
arguments that trigger surprisingly high, possibly exponential, CPU
usage or, for example via a naive recursive implementation of the
descendant segment, stack overflow.  Implementations need to have
appropriate resource management to mitigate these attacks.
Paragraph (version A):
Unexpected or unpredictable behavior can arise from an argument with
certain constructs described as unpredictable by RFC8259.
Predictable behavior can be expected, except in relation to the
ordering of objects, for any argument conforming with RFC7493.
Paragraph (version B):
Unexpected or unpredictable behavior can arise from a query argument
with certain constructs described as unpredictable by RFC8259.
Predictable behavior can be expected, except in relation to the
ordering of objects, for any query argument conforming with RFC7493.