Draft: draft-ietf-jsonpath-base

Commentary: This PR is a series of changes which are submitted together since they would tread on each other 's toes if submitted separately . Fixes Fixes 
 I 'm going to merge this so I can progress other changes . I 'd still appreciate your review and I will apply any fixes in a subsequent PR . 
 Currently , the JSONPath spec is insufficiently non - deterministic . According to the current draft , in a descendant nodelist , nodes appear immediately before all their descendants . In the example given in the spec , the selector applied to the JSON value : can not produce the result shown in the table : since does not appear immediately before and ( there is an intervening ) . Solution : delete the word " immediately " . The iteration order of objects is not guaranteed to be the same from one iteration to the next . ( For instance , in Go , a JSON object is usually implemented as a map and , according to the , " The iteration order over maps is not specified and is not guaranteed to be the same from one iteration to the next " . ) So a list with more than one entry applied to an object can result in a nodelist in which there are sublists in distinct orders . This is the case if each list entry in turn is used to select a nodelist from the object . For example , the JSONPath applied to the value : could produce the nodelist : The descendant selectors can produce similar effects , both in the ordering of the descendant nodelists and in the list form with examples similar to that above . For example , the JSONPath applied to the value : can produce the nodelist : Repeated applications of a JSONPath to a value can result in nodelists which are ordered differently . For example , the JSONPath applied to the value : could produce the nodelist : on one occasion and the nodelist : on a subsequent occasion . Currently , there is no text to define the order of the nodelist resulting from a dot wildcard , index wildcard , or filter selector . The order should preserve array order , but be non - deterministic for objects . 
 Clarification : Do you mean that the spec should be more non - deterministic ? I expect that you mean you want more determinism . 
 How would you get 4 results from this ? I 'd expect the output to be just and ( in any order ) . 
 I agree with the sentiment here . The unorderedness of objects in general is likely going to be an issue for testing . 
 No . I want less determinism to allow sufficient freedom for implementations . 
 Oops . Of course . Fixed above . 
 Should we avoid specifying the order of results at all then ? Or , more directly , explicitly state the the order of elements in a nodelist may be determined by the implementation and , because of non - determinism among various JSON implementations , is not subject to consistency ? 
 No , that would be going much too far . For example , it 's important that arrays still produce array - ordered nodelists . I agree with that statement , but I would n't want to litter the spec with that in multiple places . I 'd prefer to use similar language to the current draft , e.g. : 
 As part of addressing this issue , if PR is merged , we should also define the ordering of resultant nodelists from child and descendant * selectors . 
 I think the spec should be specific and say that when the nodelist is constructed from members of objects , its ordering is undefined , because the fact that the ordering is not defined for objects . Let 's take this issue up tomorrow . 
 At the 2022 - 9 - 27 interim , there was general agreement to implement this issue . There is a need for more extensive examples , especially showing multi - layered cases . There is a concern about how to make a test suite tractable given the level of non - determinism which is being allowed by the spec . The plan is to attack this issue after lands . 
 The current draft applies descendant selectors to the ( strict ) descendants of the input value . However , as mentioned in , it would better reflect current implementations if descendant selectors applied to the input value as well as its descendants . The comparison project has a for this which shows a consensus among existing implementations . 
 See 
 I think it would still be legitimate to call the descendant selectors by that name since the values they select are all descendants of the input value . ( The one exception would be if we were to allow on its own , in which case the input value would be in the resultant nodelist . ) 
 At the 2022 - 9 - 27 interim meeting there was a consensus for implementing this issue . 
 This sounds a lot better . Just a minor grammatical issue .
Paragraph (version B):
This document treats the bracket notations as canonical and defines
the above shorthands in terms of the canonical bracket notation.
Paragraph (version B):
Segments can be added to a query to drill further into the structure
of the input value.
Paragraph (version B):
If a query may produce a nodelist with more than one possible
ordering, a particular implementation may also produce distinct
orderings in distinct runs of the query.
Paragraph (version B):
In what follows, the semantics of each segment are defined for each
type of node.
Paragraph (version A):
A "wildcard" selector selects the nodes of all children of an object
or array.
Paragraph (version B):
A "wildcard" selector selects the nodes of all children of an object
or array.  The order in which the children of an object appear in the
resultant nodelist is not stipulated, since JSON objects are
unordered.  Children of an array appear in array order in the
resultant nodelist.
Paragraph (version B):
The example above with the query "$.o[*, *]" shows that the wildcard
selector may produce nodelists in distinct orders each time it
appears in the child segment.
Paragraph (version B):
The order in which the children of an object appear in the resultant
nodelist is not stipulated, since JSON objects are unordered.
Children of an array appear in array order in the resultant nodelist.
Paragraph (version B):
The example above with the query "$.a[?@.b, ?@.b]" shows that the
filter selector may produce nodelists in distinct orders each time it
appears in the child segment.
Paragraph (version B):
So a child segment drills down one more level into the structure of
the input value.
Paragraph (version A):
nodes of any array appear in array order,
Paragraph (version A):
nodes appear immediately before all their descendants.
Paragraph (version A):
This definition does not stipulate the order in which the children of
an object appear, since JSON objects are unordered.
Paragraph (version A):
The resultant nodelist of a descendant segment of the form
"..[<selectors>]" is the result of applying the child segment
"[<selectors>]" to a descendant nodelist.
Paragraph (version B):
nodes are visited before all their descendants.
Paragraph (version B):
It applies the child segment "[<selectors>]" to each node and
concatenates the resultant nodelists together in the order in which
the nodes were visited.
Paragraph (version B):
This definition does not stipulate the order in which the children of
an object are visited, since JSON objects are unordered.
Paragraph (version B):
Where a selector can produce a nodelist in more than one possible
order, the selector may produce nodelists in distinct orders each
time it appears in the descendant segment.
Paragraph (version B):
So a descendant segment drills down one or more levels into the
structure of the input value.
Paragraph (version B):
The example above with the query "$.o..[*, *]" shows that a selector
may produce nodelists in distinct orders each time it appears in the
descendant segment.