Draft: draft-ietf-jsonpath-base

Commentary: See discussion in . To do : What exactly does n't $ .. * stand for -- the table currently says " member values " ( i.e. , no array elements ) . Is that true ? 
 Clusters of terms :    value ( data )   location These are related , but different . We probably do not need all four . ( Of course , JSON value is a 8259 term , so it does not go away . ) We should decide which of these terms we want to use , and what they exactly mean . A node seems to be a combination of a discrete JSON value and its location . JSON value seems to imply equivalence by value ( even though equivalence is undefined in RFC 8259 ) , while node is based on equivalence by identity . Location seems to imply that you can get to the node ( and thus the value ) from it . Cluster 2 Argument : input to executing JSON query root value , root node ( used as Argument , may be used in nested queries ) current  ( current item ): input to selector function invocation , maybe used inside filtering / indexing selectors Cluster 3 selector ( part of the selector chain that makes up a JSONPath query ) ( we probably need a word for ) selector function [ invocation ] This is needed if we stick to the model that each node in the input node list is treated separately and the results are then combined using ( TBD ) combine1 .  ( placeholder for what combines the outputs of the selector function invocations ) This becomes important when we either resolve there is only one combine1 function or we resolve that combine1 functions are ( within limits ) implemenation specific ( i.e. , we give up ) or that different selectors have different combine1 functions . All these can only be meaningfully decided once we have agreement on a processing model . 
 ... ( we probably need a word for ) selector function [ invocation ] ... perhaps ... selection selection process selection step ( atomic ) 
 We are using way more generic terms : value , object etc . ( I ’d rather get rid of those first . ) The Argument is the JSON value that goes into the evaluation of the query . The Argument is then viewed as a tree and has a root node .  ,  
 ... using some examples ... ... is the name of a member value of object . ... is the index of an entry value of array . location is a general / abstract term for name and index . So and are both locations . is name and location of the root value . A ( normalized ) path is a sequence of locations enclosed in brackets . A is a pair . A in its simpliest case is a location . Special selectors are . I think with this we have a minimalistic and complete term set . 
 Unless I 've missed a strict definition in our discussions , there can be more than one normalised path for a given location . For instance , to identify the child node of the root node with name , and assuming we are using the more general " bracket " form of child name ( the production in the current grammar ) , we could use an array consisting of any one of the following name components : " a " ' a ' " u0061 " ' \u0061 ' To accommodate this , we could associate a location with an of normalised paths . Alternatively , we could define a unique normalised path for each location ( e.g. for names by stipulating double quotes and unicode escapes for every character , even if that would be unfriendly to end users and , for indices , by stipulating non - negative indices ) . I guess we could even standardise on basic Latin unicode characters and use unicode escapes for everything else , but that seems a little biased . 
 That is not exactly a terminology issue . If we want the output paths to be normalized , we would need to define that normalization . If we just want them to be stylized ( e.g. , bracket notation only , unsigned integer indexing or quoted name indexing ) and leave representation details to the implementations , we could do that , too . ( My personal view is that they should be normalized . Single quotes are very un - JSON , and escaping non - control characters is  , so it is pretty clear that " a " would be the normalized form . ) 
 I think that works best the other way around : a location is an abstraction that can be represented by a path ( full path , path from the root , ... ) . We do n't really need locations for member names , so I would limit this to nodes . If we have normalization of paths , a normalized path can indeed be derived from the path ( from the root ) of the location . ( But I do n't know yet whether we opt for normalization of output paths . ) 
 charming aspect of single quotes in normalized pathes would be to use them as JSON values itself without escaping ... We should care for : There can be only one normalized path per JSON value ! If is defined as the complete path , we need another universal term for . hmm ... why not simply use instead of from root to value and redefine as local location relative to parent value ... ? 
 I really , really like  's approach here . I it is precise and easy to understand and does the minimum amount of invention required . 
 a " canonical form " of anything , I think we could get away with it here . Any JSON string can be represented as a sequence of Unicode codepoints - granted , some of them might not be valid codepoints - and for the purpose of a normalized path , we could either ( a ) specify UTF-8 or ( b ) say that the codepoints are all that matters , the syntactic expression is not significant . Or am I missing something ? 
 I do n't feel strongly . I think we could define an abstract " path " term , but I wonder if it might sound a bit odd in places in context of JSONpath ? I 'm not sure we need a term for that . We already have names in objects and indices in arrays . 
 It would help the concision to have a single common term for indexing by name and indexing by index . I do n't have a proposal , though ... ( " location " probably is not it , that term is better used the way it is now . A location in that sense can be expressed by an output path , but it " is " not an output path . ) 
 This has been brought up before . To me , is the only sensible term that covers both objects and arrays . I know there 's other discussion regarding this term , but I 'm on mobile and ca n't find it right now . 
 " child " gives me the XPath heebie - jeebies ... But that is a reasonable working term for array element or member value ( i.e. , data items that result from indexing a container ) . What 's missing is a term for the parameter that goes into the indexing ( array index or member name ) . Maybe we need to rename array index so we can use index for the combined term ( which also would solve the fact that indexing otherwise is n't always related to indexes ) . 
 This works for me . I tend to think of a thing inside as an index , whether it 's a number or a string ( because the in .Net is called the " index " operator ) . It also helps define a union as " a set of indices " where a single " index " could be a number , a string , a slice , etc . Unions can then be any combination of these things . ( We should also decide on " indices " vs " indexes " . I 'm not sure which is more correct . seems to indicate there 's not a " correct , " but we should decide on one or the other . ) 
 Search engine of my choice offers " tag , label , mark " as kind of synonyms for " name / index " . So how do we like to talk about ( including  's proposal ): tag / value pair label / value pair mark / value pair index / value pair " tag " may be too HTML'ish ... ? 
 Given those options , I think I 'll stick with my vote for " index " . 
 Do n't forget " key " ... key / value pair 
 I think we can stick with 8259 for member name . Key is maybe indeed a candidate for " member name or array index " . I 'll propose a PR as soon as is through ( too many conflicts otherwise ) . 
 Following on from the previous comments , I propose to add two additional terms to the terminology list : Key : Synonym for array index or object member name . Selector : An atomic component of a query expression . Different selector types are ... Root selector Current item selector Nested descendants selector . Dot selector , used with object member names exclusively . Dot wild card selector . Key selector , where is either an ( possibly negative ) array index or an object member name . Key wild card selector . Array slice selector , where , , are integer literals . Union selector , holding a comma delimited list of keys . Filter selector I hope I did not miss a selector type . Also , I dislike the current fact , that union selectors are first class citizens in the spec . They should be equal among equal . Let 's discuss ... 
 How about maybe index / key ? index key ? indexing key ?  ,    will use that mostly in the form " key / value pair " , where " index / key / value pair " is confusing . " index / value pair " would be better then , but " index " alone is often mentally completed to " array index " . 
 ... if agreement goes to " index / value pair " , I can live with it ... 
 ~I still think " index " denotes an array specifically.~ Thinking over this again , yeah , index / value . For reasons I 've mention above . ( Sorry , typing without thinking ) 
 ok ... then ... Index : Synonym for array index or object member name . Selector : An atomic component of a query expression . Different selector types are ... Root selector Current item selector Nested descendants selector . Dot selector , used with object member names exclusively . Dot wild card selector . Index selector , where is either an ( possibly negative ) array index or an object member name . Index wild card selector . Array slice selector , where , , are integer literals . Union selector , holding a comma delimited list of indices ( indexes ? ) . Filter selector 
 " Indices " is more correct , but " indexes " has become more common recently . Also , I still think we should include the selector . I 've already explained its uses in other issues , but we should keep it for no other reason than people will complain if it 's not supported . 
 Well ... I would like to get filter selector syntax straight first . Then discuss , if and what subset of it we want to support with index selectors . 
 I would expect that the expression syntax would be the same . The resulting value would need to , instead of being truthy , be able to evaluate to a well - defined index , e.g. a number or string . 
 I think we should summarize all the above kinds of selector into " indexing selectors " . ( Note that the wild card selector is not there , as there is no indexing key . ) 
 The current draft says : Thus a an indexing expression can include multiple slice expressions : 
 We may want to adjust that after agreeing on a term 
 ( but " resolves " does n't trigger closing the issue , so I 'm doing this by hand here ) . 
 LGTM , thanks .
Paragraph (version A):
A structure complying to the generic data model of JSON, i.e.,
composed of containers, namely JSON objects and arrays, and of
atomic data, namely null, true, false, numbers, and text strings.
Also called a JSON value.  In this document, often abbreviated to
_item_.
Paragraph (version A):
A Data Item, with an emphasis on the location of the item within
the Argument.  I.e., an item identical to or contained within the
JSON data item 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 B):
As per RFC8259, a structure complying to the generic data model of
JSON, i.e., composed of components such as containers, namely JSON
objects and arrays, and atomic data, namely null, true, false,
numbers, and text strings.
Paragraph (version B):
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):
Short name for the JSON data item 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
data items.
Paragraph (version B):
Short name for the JSON value a JSONPath expression is applied to.
Paragraph (version B):
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 A):
Finding data interactively and extracting them out of RFC8259 data
items without special scripting.
Paragraph (version B):
Finding data interactively and extracting them out of RFC8259 JSON
values without special scripting.
Paragraph (version A):
in popular programming languages such as JavaScript, Python and PHP,
with a variable x holding the JSON data item.  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 JSON value.  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 data item in the same way
as XPath expressions are used in combination with an XML document.
Since a JSON data item is anonymous, JSONPath uses the abstract name
"$" to refer to the top level data item of the argument.
Paragraph (version B):
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 A):
The examples in tbl-example use the expression mechanism to obtain
the number of items in an array, to test for the presence of a member
in a object, and to perform numeric comparisons of member values with
a constant.
Paragraph (version B):
This section provides some more examples for JSONPath expressions.
The examples are based on the simple JSON value shown in fig-example-
value, which was patterned after a typical XML example representing a
bookstore (that also has bicycles).
Paragraph (version B):
The examples in tbl-example use the expression mechanism to obtain
the number of elements in an array, to test for the presence of a
member in a object, and to perform numeric comparisons of member
values with a constant.