jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-jsonpath-base

Commentary: Deleting the text should have addressed your original editorial issue . This PR also adds the missing cross - reference . If you 're happy , please approve .
Paragraph (version A):
Note that comparisons using the operator "<" yield false if either
value being compared is an object, array, boolean, or "null".
Draft: draft-ietf-jsonpath-base

Commentary: Also , delete a term which is used only in the definition of the next term . Fixes 
 I only found the two occurrences you suggested changing . If there are others , please let me know ! 
 Sometimes the spec uses " Singular Query " and sometimes " singular query " . We should be consistent . ( If we decide to use lower case , it 's probably best to address this issue after PR has been merged , since that PR adds some usages of " Singular Query " . ) Also , there is one instance of " Logical context " , which I think would be better uncapitalised ( " logical context " ) . 
 Thanks .
Paragraph (version A):
A JSONPath implementation MUST raise an error for any query which is
not well-formed and valid.  The well-formedness and the validity of
JSONPath queries are independent of the JSON value the query is
applied to.  No further errors relating to the well-formedness and
the validity of a JSONPath query can be raised during application of
the query to a value.
Paragraph (version B):
A JSONPath implementation MUST raise an error for any query which is
not well formed and valid.  The well-formedness and the validity of
JSONPath queries are independent of the JSON value the query is
applied to.  No further errors relating to the well-formedness and
the validity of a JSONPath query can be raised during application of
the query to a value.
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.
Paragraph (version A):
Any function expressions in a query must be well-formed (by
conforming to the above ABNF) and well-typed, otherwise the JSONPath
implementation MUST raise an error (see synsem-overview).  To define
which function expressions are well-typed, a type system is first
introduced.
Paragraph (version B):
Any function expressions in a query must be well formed (by
conforming to the above ABNF) and well typed, otherwise the JSONPath
implementation MUST raise an error (see synsem-overview).  To define
which function expressions are well typed, a type system is first
introduced.
Draft: draft-ietf-jsonpath-base

Commentary: Thanks to for spotting this . 
 I presume you are ok with this change , so I 'm going to merge it . Any concern , let me know and we can adjust the result . 
 Yes . Just did n't have chance to check this in context , but if I remember this properly , this change is good ( and necessary ) .
Paragraph (version A):
Comparison expressions are available for comparisons between
primitive values (that is, numbers, strings, "true", "false", and
"null").  These can be obtained via literal values; Singular Queries,
each of which selects at most one node the value of which is then
used; and function expressions (see fnex) of type "ValueType" or
"NodesType" (see type-conv).
Paragraph (version B):
Comparison expressions are available for comparisons between
primitive values (that is, numbers, strings, "true", "false", and
"null").  These can be obtained via literal values; Singular Queries,
each of which selects at most one node the value of which is then
used; and function expressions (see fnex) of type "ValueType".
Paragraph (version A):
If it occurs directly as a "comparable" in a comparison, the
function is declared to have a result type of "ValueType", or
(conversion applies) "NodesType".
Paragraph (version B):
If it occurs directly as a "comparable" in a comparison, the
function is declared to have a result type of "ValueType".
Draft: draft-ietf-jsonpath-base

Commentary: PR changed the spec to use " path " only for paths , and " query " for queries . The term " JSONPath " is then left in need of some motivation . This is provided in the History section so as not to interfere with the normative text . 
 ... fine ...
Paragraph (version B):
identifying nodes in the JSON argument.
Draft: draft-ietf-jsonpath-base

Commentary: These editorial changes from PR are needed in the base . 
 I confess I tend to write tedious text when precision is at stake . Hopefully , the second commit avoids the tedium . 
 Why was this merged so quickly ? ! 
 We merged this editorial change quickly so we could rebase the other substantive PRs on it and put us in a better position to compare their pro 's and con 's . 
 Looks good now ! Should merge this quickly so we can rebase the others .
Paragraph (version A):
To test the value of a node selected by a path, an explicit
comparison is necessary.  For example, to test whether the node
selected by the path "@.foo" has the value "null", use "@.foo ==
null" (see null-semantics) rather than the negated existence test
"!@.foo" (which yields false if "@.foo" selects a node, regardless of
the node's value).
Paragraph (version B):
To examine the value of a node selected by a path, an explicit
comparison is necessary.  For example, to test whether the node
selected by the path "@.foo" has the value "null", use "@.foo ==
null" (see null-semantics) rather than the negated existence test
"!@.foo" (which yields false if "@.foo" selects a node, regardless of
the node's value).
Paragraph (version A):
a comparison using the operator "==" yields true if and only if
the comparison is between two paths each of which result in an
empty nodelist.
Paragraph (version B):
a comparison using the operator "==" yields true if and only the
other side also results in an empty nodelist or "Nothing".
Paragraph (version A):
Each parameter and the result of a function extension must have a
declared type.
Paragraph (version B):
Each parameter as well as the result of a function extension must
have a declared type.
Paragraph (version A):
Otherwise, it is occurring as an argument to a further function
expression, and the following rules for function arguments apply
to its declared result type.
Paragraph (version B):
Otherwise, it occurs as an argument in another function
expression, and the following rules for function arguments apply
to its declared result type.
Draft: draft-ietf-jsonpath-base

Commentary: Would n't mind if we could get these editorials merged quickly so the bulk of the other PRs shrinks a bit . 
 LGTM , thanks .
Paragraph (version A):
Note: "double-quoted" strings follow the JSON string syntax
(RFC8259); "single-quoted" strings follow an analogous pattern
(syntax-index).  No attempt was made to improve on this syntax, so
characters with scalar values above 0x10000, such as U+0026 U+0023
U+0031 U+0032 U+0039 U+0033 U+0030 U+0030 U+003B ("&#129300;",
AMPERSAND, NUMBER SIGN, DIGIT ONE, DIGIT TWO, DIGIT NINE, DIGIT
THREE, DIGIT ZERO, DIGIT ZERO, SEMICOLON), need to be represented by
a pair of surrogate escapes (""\uD83E\uDD14"" in this case).
Paragraph (version A):
Applying the "name-selector" to an object node selects a member value
whose name equals the member name M, or selects nothing if there is
no such member value.  Nothing is selected from a value that is not
an object.
Paragraph (version A):
Note that processing the name selector requires comparing the member
name string M with member name strings in the JSON to which the
selector is being applied.  Two strings MUST be considered equal if
and only if they are identical sequences of Unicode scalar values.
In other words, normalization operations MUST NOT be applied to
either the member name string M from the JSONPath or to the member
name strings in the JSON prior to comparison.
Paragraph (version B):
Note: "double-quoted" strings follow the JSON string syntax
(RFC8259); "single-quoted" strings follow an analogous pattern
(syntax-index).  No attempt was made to improve on this syntax, so if
it is desired to escape characters with scalar values above 0x10000,
such as U+0026 U+0023 U+0031 U+0032 U+0039 U+0033 U+0030 U+0030
U+003B ("&#129300;", AMPERSAND, NUMBER SIGN, DIGIT ONE, DIGIT TWO,
DIGIT NINE, DIGIT THREE, DIGIT ZERO, DIGIT ZERO, SEMICOLON), they
need to be represented by a pair of surrogate escapes
(""\uD83E\uDD14"" in this case).
Paragraph (version B):
Applying the "name-selector" to an object node selects a member value
whose name equals the member name "M", or selects nothing if there is
no such member value.  Nothing is selected from a value that is not
an object.
Paragraph (version B):
Note that processing the name selector requires comparing the member
name string "M" with member name strings in the JSON to which the
selector is being applied.  Two strings MUST be considered equal if
and only if they are identical sequences of Unicode scalar values.
In other words, normalization operations MUST NOT be applied to
either the member name string "M" from the JSONPath or to the member
name strings in the JSON prior to comparison.
Draft: draft-ietf-jsonpath-base

Commentary: There are some syntactical representations , e.g. : LogicalTrue can be represented by ( 1==1 ) . LogicalFalse can be represented by ( 1==0 ) . Nothing can be represented by a query that always returns the empty nodelist , such as $ [ ? 1==0 ] . But these are somewhat circuitous rather than direct . See 
 I also considered deleting the statements about there being no ( direct ) syntactical representation of the values of certain types because I 'm not sure they add much . The text in this PR adds an air of mystery - what are " direct syntactical representations " ?  ? 
 I 'm not sure how " direct " clarifies " syntactical representation . " Either something can be represented in the syntax or it ca n't . Merge if you like . 
 This is obviously an improvement . We also could say " literals " , but then we would assume knowledge about this programming language construct . So I think this should simply be merged .
Paragraph (version A):
"LogicalType" is an abstraction of the result of a "logical-expr".
Its two instances, "LogicalTrue" and "LogicalFalse", are not
related to the JSON literals "true" and "false" and have no
syntactical representation in JSONPath.
Paragraph (version A):
"NodesType" is an abstraction of a "filter-path" (which appears in
a test expression or as a function argument).  Members of
"NodesType" have no syntactical representation in JSONPath.
Paragraph (version B):
"LogicalType" is an abstraction of the result of a "logical-expr".
Its two instances, "LogicalTrue" and "LogicalFalse", are not
related to the JSON literals "true" and "false" and have no direct
syntactical representation in JSONPath.
Paragraph (version B):
"NodesType" is an abstraction of a "filter-path" (which appears in
a test expression or as a function argument).  Members of
"NodesType" have no direct syntactical representation in JSONPath.
Draft: draft-ietf-jsonpath-base

Commentary: Fix a right margin incursion , as well . 
 I 'm commenting on the editor 's draft . Section 2.6 says , of len ( ) , count ( ) , match ( ) , and search ( ) , that “ they are an integral part of the JSONPath specification and are mandatory to implement . ” My intuition is that this is not consistent with the WG charter . I think we 're supposed to be specifying the GCD of JSONPath implementations , not enriching the language . The actual words of the charter are “ based on the common semantics and other aspects of existing implementations ” . Do len ( ) , count ( ) , match ( ) , and search ( ) qualify ? 
 Most implications support regexps in filters , so we need to support those somehow . A function extension seems like the neatest solution . 
 Most implementations also support length in some way , usually , which we 've decided against . 
  as charged . In that sentence I tried to express that , although the four functions make use of an extension point , they are not extensions of the base standard , as are none of the other features defined in the document . We do n't define compliance , but we do fan the expectation that a JSONPath implementation will not leave out a feature that seems inconvenient to implement ( say , descendants segments ) . If you have better wording , we could take that . 
 In all implementations there is some degree or level of compliance with the specification . No matter what the wording is in the specification the implementations will stand as they are and users will evaluate them based on how well or how compliant it is with the spec but more importantly how useful they are to them . In my implementation for go I have not yet implemented functions but do support regex with a . As this specification solidifies I 'll also support the changes but in the interest of not breaking existing code that uses the OjG package I 'll keep the original implementation as well . 
 that 's expected from most implementers , including myself . However , also as one of the editors , I would hope that implementors default to spec compliant behavior , offering other functionality behind options that the user must explicitly set . This is fairly common for spec implementations and what I will be doing if I decide to support extra - spec functionality . 
 I may not put it as eloquently as you do but I agree 100 % . I hope I can contribute at some point .
Paragraph (version A):
This section defines the extension point as well as four function
extensions that use this extension point.  While these mechanisms are
designed to use the extension point, they are an integral part of the
JSONPath specification and are mandatory to implement.
Paragraph (version B):
This section defines the extension point as well as four function
extensions that use this extension point.  While these mechanisms are
designed to use the extension point, they are an integral part of the
JSONPath specification and are expected to be implemented like any
other integral part of this specification.
Draft: draft-ietf-jsonpath-base

Commentary: This change looks good , thank you . I have one more , though ( looking more closely at the diagnostics ): I do n't think the " Alternative result " can be generated , as outside arrays come before inside arrays . 
 Yes , nodes are visited before their descendants . Fixed in .
Paragraph (version A):
"{"k": 6}" must appear before "6".
Paragraph (version B):
"{"j": 4}" must appear before "{"k": 6}",
Paragraph (version B):
"4" must appear before "6".
Draft: draft-ietf-jsonpath-base

Commentary: Fixes 
 I pushed to clarify optional arguments . 
 raised this in a PR review . 
 I think the answer is " yes " because that allows the function to be used on a Singular Path rather than on just a literal . 
 Yes . I would expect any function that can take a path must allow any value . 
 That should be enough to remove this double - take .
Paragraph (version A):
Its only argument is a value (possibly taken from a singular path as
in the example above).  The result also is a value, an unsigned
integer.
Paragraph (version B):
Its only argument is an optional value (possibly taken from a
singular path as in the example above).  The result also is an
optional value, an unsigned integer.
Paragraph (version A):
Its first argument is a string that is matched against the iregexp
contained in the string that is the second argument.  The result is
"true" if the string matches the iregexp and "false" otherwise.
Paragraph (version B):
Its first argument is an optional string that is matched against the
iregexp contained in the string that is the second argument.  The
result is "true" if the string matches the iregexp and "false"
otherwise.
Paragraph (version A):
Its first argument is a string that is searched for at least one
substring that matches the iregexp contained in the string that is
the second argument.  The result is "true" if such a substring
exists, "false" otherwise.
Paragraph (version B):
Its first argument is an optional string that is searched for at
least one substring that matches the iregexp contained in the string
that is the second argument.  The result is "true" if such a
substring exists, "false" otherwise.
Draft: draft-ietf-jsonpath-base

Commentary: Fixes 
 The ABNF is not currently subject to the I - JSON range restriction that applies to array indices and array slice parameters , but I do n't see why it should n't be . 
 I do n't understand -- the grammar can not express this restriction . Indices and slice parameters are integers , not numbers , BTW . 
 I was thinking of the integer subset of . It seems strange to have to cope with arbitrary precision integers there , but not for array indices and slices . 
 As for the grammar expressing the restriction , this is a question of validity rather than well - formedness . 
 Ah , so this would be a text fix . 
 Indeed . Sorry for the ABNF red herring . I was trying to be precise about which " number " I was talking about . 
 I guess we 'll have to worry about decimal as well as integers in , for consistency . I wonder if there 's a suitable precedent like the I - JSON range ? 
  , is not really discussed in the unnumbered (  ) section " comparisons " . ( There is text for . ) 
 How about this text ? 
 ( and in case anyone thinks we could get away with comparing the string forms of the numbers , remember scientific notation . ) 
 Oh , I see now . We should mention the I - JSON restrictions for numbers , in the comparison section . That seems like a reasonable way to fix this issue . 
 the complement of " both interoperate " is " at least one does n't interoperate " ...
Paragraph (version A):
equal primitive values,
Paragraph (version B):
numbers expected to interoperate as per RFC7493 that compare
equal using normal mathematical equality,
Paragraph (version B):
numbers at least one of which is not expected to interoperate
as per I-JSON, where the numbers compare equal using an
implementation specific equality,
Paragraph (version B):
equal primitive values which are not numbers,
Draft: draft-ietf-jsonpath-base

Commentary: Fixes 
 Section 1.4 says : A JSONPath expression consists of an identifier followed by a series of zero or more segments each of which contains one or more selectors . So this includes relative paths ( starting with ) . However , section 1.4.1 contradicts this : Similarly , section 2.4 says : Every JSONPath query MUST begin with the root identifier . ( Remember that , according to our terminology , " query " is a short name for a JSONPath expression . ) A possible solution is for sections 1.4.1 and 2.4 to talk about JSONPath expressions / queries which do not appear inside a filter expression .
Paragraph (version A):
The root node identifier "$" refers to the root node of the argument,
i.e., to the argument as a whole.  Every JSONPath expression begins
with the root node identifier.
Paragraph (version B):
The root node identifier "$" refers to the root node of the argument,
i.e., to the argument as a whole.
Paragraph (version A):
Every JSONPath query MUST begin with the root identifier "$".
Paragraph (version B):
Every JSONPath query (except those inside filter expressions, see
filter-selector) MUST begin with the root identifier "$".
Draft: draft-ietf-jsonpath-base

Commentary: E.g. , 
 I propose a slightly more compact naming of ABNF of - and -segment , which should be more consistent between them two . is well known from LaTeX and means or there . 
 above is wrong ( and so it is in the current spec ) . It needs to read ... to not allow triple dot ( :-) 
 Would n't dotdot - wildcard etc . be less cryptic ? 
 Here are some quibbles with the current ABNF ( prior to PR being merged ) which we can sort out after The Great Renaming : 
 Yes , yes . See . Fixed in I like the way this looks like now . Maybe I do n't understand ; can you elaborate ? Fixed this ( and following ) in Removed in To be fixed in overall overhaul , next Yes ! To be fixed in overall overhaul , next To be fixed in overall overhaul , next Fixed in Discuss this in its own issue , I 'd say . Fixed in It certainly does not -- it is the subset that is actually needed for normalized paths . To stay normalized , we do n't allow random other ones . 
 Of course ... I 'm quite dispassionate here . 
 Please see my proposal in 
 With merged , we still have the expression cleanup the separate issue ( enhancement ) whether should be allowed , to mean 
 My remaining points are covered by PRs , , and . 
 Should n't be named according to all other above ? 
 Yes , I agree . See 
 Are we ready to close this issue now the PRs have been merged or did you have more expression cleanup in mind ? 
 The only thing that comes to my mind is standardizing on the column where the is -- this is currently rather chaotic . But that can be a new issue . 
 Indentation of : number of lines such indented 
 ( And it does n't need to be consistent , just a bit less chaotic . ) 
 Let 's make the a new issue . ( I have n't got a good feel for the optimal solution . ) 
 Before we close this issue , slipped through the net in my earlier PRs . 
 Then could resolve to either or . We would introduce an ambiguity , we already found with   ( ) ... 
 OK , with the latest blank space realignments that are part of ( ) , I think we are done with this . 
 Thank you !
Mailing list commentary: ... or do we need two selectors here ( Ch.2.61 ) child - longhand = " [ " S selector 1(S " , " S selector ) S " ] " given that ' 1 ' means ' at least one ' .
Paragraph (version A):
According to filter-selector, a "function-expression" is valid as a
"filter-path" or a "comparable".
Paragraph (version B):
According to filter-selector, a "function-expr" is valid as a
"filter-path" or a "comparable".
Draft: draft-ietf-jsonpath-base

Commentary: For , the spec defines Why return 1 ? That 's a possible value for to return for valid inputs . Would n't it make sense to return a value that ca n't be returned by a valid input , like -1 ? Currently , this returns the both objects in the array , which is counter - intuitive . The length of the property in is nonsensical because it does n't contain an property . 
 Well , I picked this hoping people would notice this ... We have two different cases that probably also need different answers . The one the text addresses : A non - container , non - string value , e.g. , length(3 ) I think I can argue that 1 is a good value for that . The one the text does not address : An empty nodelist ( Nothing ) . 1 is definitely not a good value for that . Nothing speaks for -1 except FORTRAN - era conventions . I think we want to be able to return Nothing here . 
 I disagree . I do n't think the " length " of is 1 . I think it 's nonsensical . Numbers , booleans , nulls , and ( really all that 's left ) do n't have a " length . " ( We 've also decided that we do n't do any kind of type coersion , so interpreting as is invalid . ) I 'm happy with this . 
 I 'd be comfortable with returning . 
 LGTM , thanks .
Paragraph (version A):
For any other argument value, the result is one.
Paragraph (version B):
For any other argument value, the result is "Nothing".