Draft: draft-ietf-jsonpath-base

Commentary: Fixes 
 You 're welcome . The issue needed a bit of " show , do n't tell " . I currently agree , but I 'd like to let this PR go " cold " for a while and then compare how this section reads relative to the main branch . Meanwhile , others may like to give their opinions . 
 I now ran the tests ( and updated a few details with changing external tests ) 
 The organization of the expansion of point 2 in " Well - Typedness of Function Expressions " can be improved . Currently , it 's grouped by the kind of argument , but it 's much easier to consume if you group by function parameter type . ( Also , I think we 're missing some cases . ) I 'm going to put it in a table so it 's a bit easier to see . The above answers the question I do n't think that 's going to be a very common question   authors will have . I think the more common question will be To that end , we need to invert the grouping by using parameter type as the key . Doing this , we get This is a lot easier to consume and mentally digest . It also better serves as a reference for   authors . ( We lose the " function type matches parameter type " thing , but I do n't think we need to explicitly say that . ) 
 Questions : ( 1 ) A is defined in the draft as a list of location - value pairs . Is there a distinction between and ? ( 2 ) If a function has a parameter that accepts arguments of , does it receive a list of location - value pairs ? 
 Abstractly , yes . A nodelist is an instance ( or member ) of . Yes . 
 thanks . Are the following statements correct ? The JSONPath query in its entirety always evaluates to a nodelist ( a list of location - value pairs ) Within a filter , a JSONPath query evaluates to either a value of type or a nodelist of type . If the query satisfies the requirements of a Singular Query , it evaluates to a value of type , otherwise it evaluates to a nodelist of type . 
 Yes A query always evaluates to a nodelist ( ) . In the context of a filter expression , if it 's a singular query , the resulting nodelist can be implicitly converted to a value ( ) by extracting the single node 's value ( or for an empty nodelist ) . 
 Yes . Types only exist in the function interface . The declared type of the function you use a query for determines what the function gets . 
 thanks . What about the operator interface ? Operators are much like functions . Would it be correct to say that the comparison operators take arguments of type ValueType ? 
 The spec does n't say that . It could , be we decided against rolling out the ( function ) type system across the whole spec as it did n't seem to add much value , it would impact readability , and it is not without its own complexity . If you 'd like to explore that option , please could we do it on the mailing list so it gets appropriate visibility ? I do n't think that topic is so relevant to this particular issue . 
 Back to the issue as proposed . We definitely need to say that . We also have to transfer all the other information from what is there now to the transposed form . I do n't think the result would be an improvement . 
 We do say it , just not in those words . It 's explicitly listed in the ( new ) table . < img width="572 " alt="image " src="https://user-"What other information is there ? I 've stated all of the possible arguments for each parameter type . The improvement is the question that is answered . " Where can I put this argument ? " vs " What kinds of things can I use for arguments to this function ? " Users are going to ask the second question , not the first . 
 I think part of the difficulty in comparing the approach in this issue with the draft is that it 's not obvious ( at least to me ) how much of section 2.4.3 the table would be replacing . I think it would be just section ( 2 ) . Right ? Even replacing just section ( 2 ) , the following information is missing : What to do when a singular query is used as an argument for a parameter of type What to do when a query ( including a singular query ) is used as an argument for a parameter of type What to do when a function expression with result type is used as an argument for a parameter of type 
 I reordered ( 2 ) of 2.4.3 so related items are closed to each other ( and the declared types also happen to be in alphabetical order ) .
Paragraph (version A):
A test expression either tests the existence of a node designated by
an embedded query (see extest) or tests the result of a function
expression (see fnex).  In the latter case, if the function's
declared result type is "LogicalType" (see typesys), it tests whether
the result is "LogicalTrue"; if the function's declared result type
is "NodesType", it tests whether the result is non-empty.  If the
function's declared result type is "ValueType", its use in a test
expression is not well typed.
Paragraph (version B):
A test expression either tests the existence of a node designated by
an embedded query (see extest) or tests the result of a function
expression (see fnex).  In the latter case, if the function's
declared result type is "LogicalType" (see typesys), it tests whether
the result is "LogicalTrue"; if the function's declared result type
is "NodesType", it tests whether the result is non-empty.  If the
function's declared result type is "ValueType", its use in a test
expression is not well typed (see well-typedness).
Paragraph (version B):
When the argument is a function expression with declared result
type the same as the declared type of the parameter.
Paragraph (version B):
A function expression with declared result type "NodesType".
In this case the argument is converted to LogicalType as per
type-conv.
Paragraph (version B):
A "logical-expr" that is not a function expression.
Paragraph (version B):
When the declared type of the parameter is "NodesType" and the
argument is a query (which includes singular query).
Paragraph (version B):
A value expressed as a literal.
Paragraph (version B):
If the query results in a nodelist consisting of a single
node, the argument is the value of the node.
Paragraph (version B):
If the query results in an empty nodelist, the argument is
Nothing.