Draft: draft-ietf-jsonpath-base

Commentary: Try to nail down the processing model some more , and raise four discussion points that we might be able to resolve now . 
 Seems to be related to . 
 Indeed , this tries to reflect the great discussion in . 
 It seems these are all terminology comments . Can we refrain from continuing the Brownian motion on terminology and focus on content for this PR ? Unless of course the terminology is wrong or not sufficiently sharp . We can go back to terminology discussions after having made some progress . 
 I have collected these items in so we do n't forget where we were . 
 I was thinking that line 183 .. 185 were doing that . But since you insist , in I have tried to clarify this paragraph and elevate it to its own definition . 
 wrote : Thank you . Your forbearance is appreciated :-) I was hoping for something more along the lines of XQuery and XPath Data Model 3.1 wording : " All nodes must satisfy the following general constraints : " " Elements [ Nodes ] have the following properties : " But I understand ( and largely agree with ) this sentence , which can be considered a working definition : " 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 . " I ( and no doubt would prefer " root value " to " argument " , and I would prefer " Normalized Path " to " Output Path " ( why use any other than the easily constructed canonical one ? ) but these then become terminological or minor issues . 
 This needs rebasing on main . Also the text includes some discussion points and I 'm not sure whether your intention is that these be addressed before merging ? 
 and I 'd like to get this PR merged with the discussion points inline . That would be a nice stake in the ground . Do either of you have objections to that or are you comfortable with merging ? 
 To make this easier , I rebased on main again , and I numbered the discussion points ( D1 to D4 ) . 
 the goal for putting a " processing model " in the spec is to have some algorithm to reference internally . It does n't need to consider edge cases or have much detail . It just needs to be sufficient for other parts of the spec to use . It 's not even intended as guidance . We want to leave as much as possible up to the implementor . 
 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 ) . 
 ( This was original raised in and now being split out ) 8259 , and that the word " object " should not be used for items that are not JSON objects in the sense of RFC 8259 . ( Daniel P ) terms per RFC8259 is pretty small : JSON text , value , object , array , number , string . Having spent quite a bit of time specifying JSON DSLs , I find that using just those terms does n't seem to get in the way or cause problems , so I 'd argue that we should stick to them ( and build up to higher - level constructs as required for JSONPath ) . (   ) (   ) (   ) " member " to mean (   uses " member " ) . ( Daniel P ) (   ) I understand , that within RFC8259 we have JSON values of different types . They are structured somehow , which is not so much of interest here . But while querying that structure with JSONPath it is vitally important to identify that hierarchical structure as a tree . So in fact we build up a higher - level construct here . We also need to call " the things " in the tree somehow . I was able to identify " node " or " item " of a tree " member " of an object " name / value " or " key / value " pair alias " member " " element " of an array but could not see an agreement here . I agree to  calling the term " union " poor ( s. below ) . 
 Also relates to . 
 Until the early discussions on the jsonpath list , I thought more about value selection , I had n't really thought much about nodes , or appreciated the importance of paths for identity ( duplicate removal ) and sorting , if the user wanted that . But having changed my thinking based on those conversations , I 'd like to understand better what exactly a node represents in JSONPath . In XML , we have the DOM , and DOM nodes . But in JSON we do n't really have anything like that . I do n't find it natural to think about a " tree of nodes " in the context of JSONPath . The implementations I know about do n't have a tree , they do n't identify location by the position in a tree , rather , they operate on path / value pairs . For example , looking at the slice operator code in there is no tree , just a selected value and an updated path . That 's typical I think of many implementations . Would it be better to talk about a node as a path - value pair , rather than a node in a tree ? 
 For me , regarding a JSON value as a tree is n't an implementation consideration - it 's an observation about the abstract structure of the data . Similarly , the notion of the position ( or perhaps location ) of a node in the tree is just an abstract way of identifying where the node is in the tree . A path is one implementation of the abstract notion of position , but not the only one . I think in the spec we should try to avoid implementation bias and speak of positions rather than paths , references , or pointers , all of which bring to mind implementations . It 's unfortunate that ( general ) trees are also common data structures and maybe that 's part of the problem here . But in reality , we also have binary trees , AVL trees , splay trees , B - trees , etc . , so I try to think of a general tree data structure as just one way of implementing an abstract tree . Does that help at all ? 
 wrote : Okay . So we want to talk about abstract input , abstract output . Tree of nodes in , tree of nodes out . It would be really helpful if you could answer two questions . Question 1 : What is a node in JSONPath ? What are its properties ? " node " appears 60 times in the draft , but I only found two mentions of what a node is . In section 3.2 , it says " Each node holds a JSON value " ( emphasis ) . And then there is " root node which is the input document " ( emphasis . ) I 'm assuming ( please correct me if I 'm wrong ) , that a JSON value as defined in RFC8259 can not itself be considered a " tree of nodes " . It 's a hierarchy of values , not nodes that contain values . What are the properties of a node ? We 're told it holds a JSON value . What else does it hold ? Does a node provide access to its parent node , like a DOM Node does ? Does a node provide access to its associated key , or index ? Question 2 : How do we interpret " root node which is the input document " The term " input document " , is that a real thing ? Actual JSON data ? No nodes ? Does the draft really mean that the root node is the input document ? Or that it represents the input document ? Suppose the input document is What value does the root node contain ? ? Apologies for questions that must seem self evident to you , but I do n't have any experience with nodes in the context of JSON . Thanks ,    draft defines Position , In section 1.1 , as follows : " A JSON data item identical to or nested within the  data item to which the query is applied to , expressed either by the value of that data item or by providing a Normalized Path Expression as a JSONPath Output Path . " I think this needs to be clearer . It would be easier to read if the phrase " the JSON data item to which the query is applied to " was replaced by a single term defined earlier , perhaps root , or whatever term the authors choose to use consistently that means the same thing . The statement that position can be expressed " by the value of that data item " is not clear . What is its intended meaning ? A " data item " is said earlier to be the the same as a " JSON value " . I do n't understand how " position " can be expressed as the value of that item . Is it its location within the data item ? Particularly when the alternative is " a Normalized Path Expression as a JSONPath Output Path " . I think it would be easier to read the sentence if " Normalized Path Expression as a JSONPath Output Path " was replaced by " Output Path " , which is defined earlier . 
 I agree , " node " is an important term to define clearly . Pragmatically quoting as not being a computer scientist gives : With this , for me " node " is either a primitive JSON value or a JSON container & ndash ; array or object & ndash ; as a possibly empty subtree . Nodes are either named or indexed ; thus have a unique tree location . Leaf nodes are either primitive values or empty containers . There is always a root node . What do you think & ndash ; I 'm not an expert with " abstract data types " . 
 A node is an item ( a term we have defined ) , with an emphasis on this item possibly being a specific part of a bigger item . ( Add same instance vs. equal value discussion here . ) 
 Oh well : " ( Data ) item " = = " JSON value " = = " node " . Maybe we should make that triple equivalence explicit . 
 Data item and JSON value , as defined in the draft , are crystal clear . But it is n't stated in the text of the draft that " node " = = " JSON value " . It 's stated that " Each node holds a JSON value " , and " the JSON value held by a node " ( emphasis ) . My reading of that text is that a node boxes a JSON value ( and possibly has additional attributes , such as location information if the JSON value is a descendent of the root . ) Also consider that a reader seeing the term " node " may have a priori understanding of the term by analogy to DOM nodes , where it 's possible to navigate back to the root from any child node . Note that my concern is with what the text says , what the authors intended , and the alignment thereof . I 'm less concerned with any particular resolution . 
 So we now have ( bold terms ): Living table ... Please edit . 
 Why not simply   instead of Normalized Path Expression , since an Output Path is always    ? 
 wrote : What my question really comes down to , considering both " JSON value " and " node " as abstract entities , is this : Is this abstract operation defined in one or both cases : For ( 1 ) , my expectation is " no " , since  values are generally regarded in JSON specifications as self - contained . Using RFC 6901 terminology , a " specific value " extracted from a " JSON document " has no connection anymore to the original " JSON document " . For ( 2 ) , my expectation is " yes " , by analogy to the DOM and DOM nodes . More generally , are there any abstract operations defined on " node " that are not also defined on " JSON value " ? If the answer is no , than introducing the term " node " serves no purpose . 
 I do n't think we should use " JSON value " ; we have the term " item " for that . " node " means exactly the same , so we do n't need it . In the same way that you do n't need both the term " flophouse " and " hotel " . I believe " node " is a good term when the emphasis is on the position that item has on a tree . 
 For the whole selector , the input is a JSON value which can be thought of abstractly as a tree of nodes , but the output is a sequence of JSON values each of which can be thought of as a subtree of the input tree . If you 're not familiar with trees and nodes , Wikipedia gives a reasonable definition of - see the terminology section for " node " . However , that page is about data structures , so is not particularly abstract . The page on may be more helpful . A JSON value can be considered as a tree of nodes . A JSON literal corresponds to a single node with value equal to the literal . A sequence corresponds to a node whose children ( indexed by position in the sequence ) correspond to the values of the sequence . An object corresponds to a node whose children ( indexed by name in the object ) correspond to the values of the object . I think it 's probably better to talk of a JSON value corresponding to the tree rooted in a node . For literals , the node holds the type and value of the literal . For sequences or objects , the node holds just the number of children or their names , respectively . Every node except the root node has a parent . I do n't think it " provides access " to anything , because this is an abstraction rather than a programming construct . No , a node does n't know its key or index - that 's the concern of its parent . The input document is JSON data and is also a JSON value . It corresponds to a tree of nodes as outlined above . Probably " represents " is closest . I used the word " corresponds " above because I have in mind a mapping from the JSON value to a tree of nodes . The tree in this case is something like this : 
 Is this a hint to rename " data item " to " item " ? ok ... " node " is self - explaining in the tree context , so I will delete it from the terms list . 
 Data item is just the long form . I still think we should have a terminology entry ( or add it to the “ item ” entry ) . Grüße ,  
 I do n't think its necessary to talk about a " tree of nodes " , which is a less abstract concept ; it is enough to define node , and identify its properties . " tree of nodes " suggests an arrangement of data that is never found in actual implementations , " node " by itself does n't have that connotation . It 's properties are all that matter . 
 I do n't think it 's necessary for a node to " know " about its parent . I personally think it 's easier to talk about a tree of nodes rather than a node in isolation . The tree structure is implicit in the way  is structured . Anyway , I feel we are talking somewhat at cross - purposes , but do you think we are converging on a common understanding yet ? 
 This is precisely how every .net solution I 've seen / created works . Also , seconding everything that . ( I was building such a response , but I upon reading it , I figured the horse was dead enough . ) Regarding access to parents , I 'd like to call out that the Newtonsoft parser results in a tree of items that do have such access , while the newer in - built System . Text . Json parser results in a tree of items that do not have access . NOTE These are represented by .Net classes internally , so naturally they have some extended properties besides the JSON value . The point here is that one points back to the parent while the other does n't . Therefore it 's completely up to the implementation / parser to determine how it wants to model the JSON internally . JSON does n't define how or whether such access should be supported . It 's just a data structure . Additionally , ( he 's on sabbatical , so I do n't want to tag him ) has released as an extension to the base JSON Pointers spec where the first action is to navigate up the tree before dereferencing the rest of the pointer . This spec assumes nothing of " nodes " that contain any metadata or their navigability . It 's just considering the structure as a tree of values . 
 I just read the current draft carefully and was left unconvinced that the term " node " needs to be used . In particular , consider the nice example in section 3.5 . I went through that and it seems to me that every instance of " node " could be replaced by " JSON Value " and be accurate , because I think every bit of the instance discussed there is a JSON value . ( If we were going to do this , we should probably have a terminology note that " Value " means " JSON Value " , just for brevity and readability . ) Are there other places in the spec where the use of the term " node " is necessary for accuracy or clarity ? To test my hypothesis , I 'll create a PR that updates section 3.5 to ( hopefully ) support my point . But if someone has a strong argument why we need to invent new terminology , I 'd be happy to avoid the effort . 
 There is no doubt that the draft could be made to work by calling the things " mugs " . One can adapt to anything . Value is a particularly bad term to use here because it focuses on the valueness , i.e. , comparison by value . Nodes focus on the place , the position , in the tree , i.e. , comparison by identity . Again , the draft can be written in a way that makes the reader make that distinction on their own , but that is not a good way to do tech doc . Why do n't the terms from 8259 suffice ? 8295 defines a JSON text , not its processing . It is rather natural that once processing is , new terms are , too . 
 ( Of course , I do n't have a strong argument for why we need to " invent " " new " terminology ; I think the term " node " has been used before . Jeez . ) 
 wrote : JSON = jsonPath(JSON , JSONPath - expression , value - option ) This is the most common case , and the entirety of the cburgmer   is devoted to it . I believe an implementation could match all of the consensus results , and where no consensus exists , the largest minority result , with doing nothing more than starting with a JSON value and working down through its children , without accumulating paths , and without concerning itself with identity . I note that the consensus is ( 32 out of 41 implementations ) ; with duplicates , there are issues with identity , but without , there are not . Now consider the evaluation of a  document that produces a JSON array of Normalized Paths , JSON = jsonPath(JSON , JSONPath - expression , path - option ) In terms of the processing model , in the case of duplicates allowed , not much is different , except that in addition to selecting a value at each step , a corresponding path needs to be accumulated . The paths are simply accumulated , we do n't do anything with them , we compute them along with the values , and we return a JSON array of them . At every step , the " current value " corresponds to an accumulated path , these two exist as a pair , so I think it makes sense to refer to that pair as a " node " . In the output , a path will be represented as a " string " . In the processing model , it need not be , we can talk about a " context position " if you like , but conceptually it 's a path . For either the value or path option , it 's in the minority position of " no duplicates " that things become interesting , where identity matters . But identity can be determined entirely by paths . Duplicate path - value pairs are straight forward to exclude . Of course , other processing models that result in no duplicates are interesting to look at also . Yes , but it seems to me that the items upon which the processing model operate should be from 8259 . New terms should n't be introduced gratuitously .    why are you talking about JSON documents , paths , children , etc . ? I completely agree on this one , but I think you made a great demonstration that a few new terms do help . 
 Well , you could call them mugs or nodes , but what they actually are is   , as defined in 8259 . I 'm having trouble parsing the phrase " the place , the position , in the tree , i.e. comparison by identity " . I 'll go ahead and do a PR to update 3.5 without introducing a new term and let 's see if we like how it reads . 
 wrote : Point taken :-) One does feel the need to call that first thing provided something other than a JSON value , JSONPointer uses " JSON document " ,   uses " JSON instance " , Goessner uses " root " . I think paths are required . " Children " can be dispensed with . 
 uses " argument " for the argument of the query . 
 wrote : Incidentally , specific language issues aside , if you 're thinking about processing models for preserving identity and removing duplicates , which is the impression I got from watching the last meeting video , I 'm actually quite interested in that .   In 8259 , the top - level production is " ws value ws " . Anyone who 's read that RFC is not going to have any trouble with the phrase " root value " . 8259 does not define or use the term " child " , so if we do need it ( not obvious to me ) we can define it as meaning " elements , if the value is an array , member values if it 's an object " . I note that the current draft does not actually define the term " node " . I think that if you did , the definition would be something like " synonym of JSON value " . So … 
 Please read at some point . 
 wrote : Right Still , when talking about " I prefer to talk about it as a " current node " rather than a " current value " . " current value " is n't enough for fulling describing the JSONPath processing model , when talking about producing Normalized Paths , the path associated with the current value matters too . It matters even more when we talk about no duplicates . I think is right to emphasize that aspect . Talking about @ as representing both the location in the root value as well as the value itself , and using node to mean that , seems reasonable to me . 
 I think it makes more sense to talk about the location of a node rather than the location of a JSON value because a JSON value could be present at multiple nodes whereas a node has a unique location . 
 thanks for bringing it to the point pragmatically . In we have five JSON values , from which two values are 5 , i.e. identical . They belong to two different name / value pairs ( members ) according to 8259 . Now consider with three JSON values , from which again two values are 5 , i.e. identical . They belong to two different ... hmm ... 8259 does not tell . But JSONPath needs to identify them uniquely by their location . Looking at JSON Pointer 6901 we read So JSON Pointer also needs to identify things uniquely by their location and uses ... ... for addressing members in objects and elements in arrays by a single term , since alone simply does not work . For us in fact two additional & ndash ; location specifying & ndash ; terms would suffice , or or skipping , then only one . 
 JSON pointer is about references , so they might have that word in their terminology ; I do n't think we need that .  and item are in . root is interesting , because that is an argument to the query — I called that argument in . We can always change these terms more if we want to , but at some point we need to enable ourselves to work on the content of the draft . 
 wrote : But it only makes sense to talk about the location of a " node " if the term " node " is defined , which I do n't believe it is in the current draft . is what " node " means in XPath 3.1 , but what does it mean in JSONPath ? It is meaningless to talk about " node " unless " node " is defined , and its properties enumerated , as they are in the XPath 3.1 reference . I think terms are being introduced into the draft that are suggestive of terms in XPath , such as " item " and " node " , but surely the one thing that we can all agree on is that we do not want the JSONPath spec to look anything like XPath , with its horrendously complicated data model . It 's also unnecessary to introduce " node " to fully describe JSONPath , including selection of values or references from a root value with duplicates , selection of Normalized Paths from a root value with duplicates , and both of these operations without duplicates ( when identity matters . ) It is enough to have the notion of path / value pairs , where " path " describes the location of the value in the root value . Nothing else is needed . Daniel 
 ... this was merely an answer for  's wish , restricting to 8259 terms exclusively . ... so you are proposing to use and ? 
 — yes , I explained why limiting ourselves to 8259 terminology is misguided . We can certainly invent more and more complex terminology , or we can accept that " node " is the term of art here . 
 wrote : proposed , so I 'll stick to that term in my commentary , unless another term is agreed to . I 'm broadly in favour of  's wish to adhere to 8259 terms to the extent possible . I 'm happy with " value location " , since it seems to be nicely symmetrical with the other terms . I believe all operations in the JSONPath processing model can be fully described with just the notions of " root value " , " value " and " value location " .    query language for JSON Comparison table update from . Thanks for adding  column . 
 Regrading the table with terminology compared , not sure where I can comment on this , as the issue has been closed , and I do n't see it in a pull request . " XPath " in column heading should specify the version . If " what is it " references " XDM 3.0 " , it should be " XPath 3.0 " . You could also specify , and change " what is it " to reference If XPath is 3 or 3.1 , " expression evaluates to " should n't have " node - set " , node - set disappeared with XPath 1.0 . It should have sequences . Quoting from XPath 3.1 , " Sequences replace node - sets from XPath 1.0 . In XPath 1.0 , node - sets do not contain duplicates . In generalizing node - sets to sequences in XPath 3.0 and XPath 3.1 , duplicate removal is provided by functions on node sequences . " 
 Hi Daniel , This way of reporting things is fine , but even better is raising an issue -- yes , even small editorial fixes are best handled as issues ( you may want to label them " editorial " ) . Re XPath versions , I 'm not sure how much we need to dwell on this in this document . I think I will try to come up with a pull request that moves some of this material into an appendix as we said , but I think I 'll focus on for a couple of days . 
 Approving with discussion points left inline . Better to make progress on the rest . I'm happy with this for its purpose . I 'd like to deal with at some point , but it 's not crucial to this PR .
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_.  The term _node_ has the same meaning, but is used to
emphasize the location of an item within the Argument, i.e., an
item identical to or nested within the JSON data item to which the
query is applied.
Paragraph (version B):
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 B):
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 B):
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):
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 A):
A JSON value is logically a tree of nodes.
Paragraph (version A):
Each node holds a JSON value (as defined by RFC8259) of one of the
types object, array, number, string, or one of the literals "true",
"false", or "null".  The type of the JSON value held by a node is
sometimes referred to as the type of the node.
Paragraph (version A):
An implementation of this specification, from now on referred to
simply as "an implementation", SHOULD takes two inputs, a JSONPath
and a JSON value, and produce a possibly empty list of nodes of the
JSON value which are selected by the JSONPath or an error (but not
both).
Paragraph (version A):
If no node is selected and no error has occurred, an implementation
MUST return an empty list of nodes.
Paragraph (version A):
Syntax errors in the JSONPath SHOULD be detected before selection is
attempted since these errors do not depend on the JSON value.
Therefore, an implementation SHOULD take a JSONPath and produce an
optional syntax error and then, if and only if an error was not
produced, SHOULD take a JSON value and produce a list of nodes or an
error (but not both).
Paragraph (version A):
Alternatively, an implementation MAY take a JSONPath and a JSON value
and produce a list of nodes or an optional error (but not both).
Paragraph (version A):
For any implementation, if a syntactically invalid JSONPath is
provided, the implementation MUST return an error.
Paragraph (version A):
If a syntactially invalid JSON value is provided, any implementation
SHOULD return an error.
Paragraph (version A):
Syntactically, a JSONPath consists of a root selector ("$"), which
selects the root node of a JSON value, 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 document.
Paragraph (version B):
A string to be used as a JSONPath query needs to be _well-formed_ and
_valid_.  A string is a well-formed JSONPath query if it conforms to
the syntax of JSONPath.  A well-formed JSONPath query is valid if it
also fulfills all semantic requirements posed by this document.
Paragraph (version B):
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):
Discussion (D1): are we ready for the error model defined here,
i.e. one that does not have runtime errors, but only compile time
errors?
Paragraph (version B):
In this specification, the semantics of a JSONPath query are defined
in terms of a _processing model_.  That model is not prescriptive of
the internal workings of an implementation: Implementations may wish
(or need) to design a different process that yields results that
conform to the model.
Paragraph (version B):
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 B):
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 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 "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 B):
Discussion (D2): We haven't decided yet whether there is only one
_combine1_ or a choice, with for instance simple concatenation and
concatenation with duplicate removal, based on a definition of
duplicate, are candidates.
Paragraph (version B):
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 B):
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 B):
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 A):
But a selector doesn't just act on a single node: each selector acts
on a list of nodes and produces a list of nodes, as follows.
Paragraph (version A):
After the root selector, the remainder of the JSONPath is processed
by passing lists of nodes from one selector to the next ending up
with a list of nodes which is the result of applying the JSONPath to
the input JSON value.
Paragraph (version A):
Each selector acts on its input list of nodes as follows.  For each
node in the list, the selector selects zero or more nodes, each of
which is a descendant of the node or the node itself.  The output
list of nodes of a selector is the concatenation of the lists of
selected nodes for each input node.
Paragraph (version A):
A specific, non-normative example will make this clearer.  Suppose
the input document is: "{"a":[{"b":0},{"b":1},{"c":2}]}".  As we will
see later, the JSONPath "$.a[*].b" selects the following list of
nodes: "0", "1".  Let's walk through this in detail.
Paragraph (version B):
But a selector doesn't just act on a single node: a selector acts on
each of the nodes in its input nodelist and selects an output
nodelist for each of them, as follows, which are then combined using
the combine1 algorithm to form the result nodelist of the selector.
Paragraph (version B):
Discussion (D3): Do we allow selectors that have their own
combine1 variant, or can we always use the same?
Paragraph (version B):
For each node in the list, the selector selects zero or more nodes,
each of which is a descendant of the node or the node itself.
Paragraph (version B):
Discussion (D4): Is that a common requirement?  Or can a selector
also go up, or to the query Argument?
Paragraph (version B):
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.