Draft: draft-ietf-jsonpath-base

Commentary: I actually ordered the two definition lists in the order the production appear in the grammar , so this is now easy to check ( and I have checked it ) . 
 The section in question ( and subject to some change soon ) is The part that feels clunky to me is the first line : While not wrong , when you get into the bullet points , it feels odd that we 're saying " all of the following are true " when only one things ever applies due to the conditions each item defines . We 're saying we have three options , A , B , and C and then we define rules : If A , then ... If B , then ... Otherwise C , then ... ( I know I made a about changing " rules " to " scenarios " in a previous PR , but each of these statements conforms to the definition I gave for a " rule . " ) The thing that feels weird is that we 're saying they all _ must be true , which ... is " correct " because the requirements are conditionally applied , but also it seems that ( because of the conditions ) only one ever actually applies , meaning that the other two are more " not applicable " than they are " true . " Maybe if we instead said : Previous to the current text ( before the type system was introduced ) , we had : 
 I was also thinking of turning this into a table . 
 A table could be nice , too , but the " all of following must be true " language still needs adjustment . 
 I agree this section is rather tedious to read . 
 Oh , and regardless of whether a table could be crammed into the document , it would be good to somehow check that all the permutations have been covered correctly . It 's too hard to hold the possibilities in my small head while reading the current text ...
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 result
type is declared as "LogicalType" (see typesys), it tests whether the
result is "LogicalTrue"; if the function result type is declared as
"NodesType", it tests whether the result is non-empty.  If the
declared function 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.
Paragraph (version A):
If the function expression occurs as a "test-expr" in a logical
expression, the function is declared to have a result type of
"LogicalType", or (by conversion as per type-conv) "NodesType".
Paragraph (version A):
If the function expression occurs directly as a "comparable" in a
comparison, the function is declared to have a result type of
"ValueType".
Paragraph (version A):
Otherwise (the function expression occurs as an argument in
another function expression), the following rules for function
arguments apply to its declared result type.
Paragraph (version A):
The arguments of the function expression are well-typed, as
follows.
Paragraph (version A):
The argument is a function expression with declared result type
that is the same as the declared type of the parameter.
Paragraph (version A):
The argument is a function expression with declared result type
"NodesType" and the declared type of the parameter is
"LogicalType".  In this case the argument is converted to
"LogicalType" as per type-conv.
Paragraph (version A):
The argument is a value expressed as a literal and the declared
type of the parameter is "ValueType".
Paragraph (version A):
If the query results in a nodelist consisting of a single node,
the argument is the value of the node.
Paragraph (version A):
If the query results in an empty nodelist, the argument is
"Nothing".
Paragraph (version A):
The argument is a query (including singular query) and the
declared type of the parameter is "NodesType".
Paragraph (version A):
The argument is a "logical-expr" and the declared type of the
parameter is "LogicalType".
Paragraph (version A):
Note that the last bullet item includes the case that the argument is
a query (including singular query) and the declared type of the
parameter is "LogicalType".  In this case the nodelist resulting from
the query is interpreted as a logical-expr in the same way (extest)
it would be converted to "LogicalType" as per type-conv.
Paragraph (version B):
its arguments must be well typed for the declared type of the
corresponding parameters.