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

Commentary: ( This is a PR to PR ! ) 
 Approved with a suggestion and a nit .
Paragraph (version A):
The "dot-wildcard-shorthand" is shorthand for "[*]".
Paragraph (version A):
A "dot-member-name-shorthand" of the form ".<member-name>" is
shorthand for "['<member-name>']", but can only be used with member
names that are composed of certain characters.  Thus, for example,
"$.foo.bar" is shorthand for "$['foo']['bar']" (but not for
"$['foo.bar']").
Paragraph (version B):
".*", a "child-segment" directly built from a "wildcard-selector", is
shorthand for "[*]".
Paragraph (version B):
".<member-name>", a "child-segment" built from a "member-name-
shorthand", is shorthand for "['<member-name>']".  Note that this can
only be used with member names that are composed of certain
characters, as specified in the ABNF rule "member-name-shorthand".
Thus, for example, "$.foo.bar" is shorthand for "$['foo']['bar']"
(but not for "$['foo.bar']").
Paragraph (version A):
The "descendant-wildcard-shorthand" is shorthand for "..[*]".
Paragraph (version A):
A "descendant-member-name-shorthand" of the form "..<member-name>" is
shorthand for "..['<member-name>']".
Paragraph (version B):
"..*", the "descendant-segment" directly built from a "wildcard-
selector", is shorthand for "..[*]".
Paragraph (version B):
"..<member-name>", a "descendant-segment" built from a "member-name-
shorthand", is shorthand for "..['<member-name>']".  As with the
similar shorthand of a "child-segment", note that this can only be
used with member names that are composed of certain characters, as
specified in the ABNF rule "member-name-shorthand".
Draft: draft-ietf-jsonpath-base

Commentary: Delete the editor 's note as » Note that there is no deduplication of the nodelist . « is now the agreed behavior . 
 As currently specified , there is no deduplication of nodes input to the count ( ) function extension . But the spec contains a placeholder suggesting discussion of deduplication . This issue is for that discussion . This issue is related to because if function extensions do not have access to node location , then it would not be possible to deduplicate on node identity , only potentially on value . 
 2023 - 01 - 10 Interim : Remove the editor 's note now .
Paragraph (version B):
Its only argument is a nodelist.  The result is a value, an unsigned
integer, that gives the number of nodes in the nodelist.  Note that
there is no deduplication of the nodelist.
Paragraph (version A):
Other attacks can target the behavior of underlying technologies such
as UTF-8 (see RFC3629) and the Unicode character set.
Draft: draft-ietf-jsonpath-base

Commentary: clarify that filter expressions are side - effect free and therefore , short - circuiting does not make a difference 
 In C # ( and probably other C - style languages ) , there are two variants for these operators . and are simple boolean logic . They evaluate all of their operands always ( left to right ) . and are " short - circuit " logic . Their operands are evaluated left to right , and as soon as an outcome is known , it stops evaluating . For example , in , the is never evaluated because returns false so the evaluator knows the entire expression will be false . This becomes important for C # as the operands may be methods which have side effects . If I am trying to parse a , then use the I parsed , I can do that all in one statement : ( assume returns a ) In this case , never gets called , which means that no log entry is made . But if I use instead will always be called and a log entry will always be created . ( will be the default ( 0 ) , but it will still be called . ) I 'm not sure whether we care about such side effects in   ( I 'm leaning towards probably not ) , but it seems necessary to raise the issue . I expect that if we do n't care about side effects , this comes down to an optimization strategy and implementor 's choice . 
 This may become more important if certain function extensions end up having side effects . Perhaps we should say implementations MAY short circuit evaluation . Then it 's up to users and function extensions to cope . 
 Actually , it would already become important as soon as we have exception - like semantics on subexpressions . I 'd prefer not to have them . 
 2023 - 01 - 10 Interim : Add text that explicitly excludes side effects that affect the evaluation of JSONpath ( e.g. , beyond memoization or logging ) , but makes clear that short - circuiting is a valid implementation strategy ; functions need to be pure functions .
Paragraph (version B):
As the expression is composed of side-effect free components, the
order of evaluation does not need to be (and is not) defined.
Similarly, for "&&"/"||", both a short-circuiting and a fully
evaluating implementation will lead to the same result; both
implementation strategies are therefore valid.
Draft: draft-ietf-jsonpath-base

Commentary: mention nested filter - selectors , disambiguate which current node is meant .
Paragraph (version A):
The current node is accessible via the current node identifier "@".
Paragraph (version B):
The current node is accessible via the current node identifier "@".
This identifier addresses the current node of the filter-selector
that is directly enclosing the identifier; note that within nested
filter-selectors, there is no syntax to address the current node of
any other than the directly enclosing filter-selector (i.e., of
filter-selectors enclosing the filter-selector that is directly
enclosing the identifier).
Draft: draft-ietf-jsonpath-base

Commentary: Remove single - valued type " Absent " . This is not useful as a function signature type ( parameter or result ) . 
 I 'm looking at 2.6.1 and wondering if it would be meaningful for a function to have a result type of . How could such a function be used in a filter ? If it is the case that this does n't make sense , that should probably be noted in the text . 
 By " absent " do you mean " no return value , " like a function in C ? If so , what would be the point ? The usefulness of functions is that they perform calculations on inputs and provide a result . 
 Indeed , the clarification should be that not all types that make up the type hierarchy are useful as return types . ( Which does not mean they need to be outlawed -- they are just not useful . ) 
 No . is a type with one instance ( ) . 
 I can just about conceive of a logging function that does n't need to return a value returning type . It could be used in a filter expression like this . I 'm not suggesting that 's a good idea , but it could be done . 
 That has no impact on the output of the query , though . Why would one include such a thing ? Logging is an implementation / application concern . What ? I 'm asking about the meaning of . How is it used ? What 's it 's purpose ? It does n't appear in the spec anywhere , so why even ask the question ? 
 2023 - 01 - 10 Interim : Remove Absent type .
Paragraph (version A):
"OptionalValue" is an abstraction of a primitive value that may
also be absent.
Paragraph (version A):
"Absent" is an abstraction of an empty nodelist.
Paragraph (version B):
"OptionalValue" is an abstraction of a primitive value that may
alternatively be absent ("Nothing").
Draft: draft-ietf-jsonpath-base

Commentary: Add note that using the extension point mechanism does n't imply the " function extensions " to be non - mandatory .
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 mandatory to implement.
Draft: draft-ietf-jsonpath-base

Commentary: Add pair of surrogate escapes to note on string format . 
 LGTM , thanks . Just one editorial suggestion .
Paragraph (version A):
Note: "double-quoted" strings follow the JSON string syntax
(RFC8259); "single-quoted" strings follow an analogous pattern
(syntax-index).
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
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).
Draft: draft-ietf-jsonpath-base

Commentary: Signed - off - by :   < fancy here , just like the title says . 
 LGTM , thanks .
Paragraph (version A):
So nodes are the selectable parts of the argument.  The only parts of
an object that can be selected by a query are the member values.
Member names and members (name/value pairs) cannot be selected.  So
member values have nodes, but members and member names do not.
Similarly, member values are children of an object, but members and
member names are not.
Paragraph (version B):
Nodes are the selectable parts of the argument.  The only parts of an
object that can be selected by a query are the member values.  Member
names and members (name/value pairs) cannot be selected.  Thus,
member values have nodes, but members and member names do not.
Similarly, member values are children of an object, but members and
member names are not.
Paragraph (version A):
In this document, the semantics of a JSONPath query define the
required results and do not prescribe the internal workings of an
implementation.
Paragraph (version B):
In this document, the semantics of a JSONPath query define the
required results and do not prescribe the internal workings of an
implementation.  This document may describe semantics in a procedural
step-by-step fashion, but such descriptions are normative only in the
sense that any implementation MUST produce an identical result, but
not in the sense that implementors are required to use the same
algorithms.
Paragraph (version A):
A "dot-member-name-shorthand" of the form ".<member-name>" is
shorthand for "['<member-name>']", but can only be used with member
names that are composed of certain characters.  Thus, for example,
"$.foo.bar" is shorthand for "$['foo']['bar']" (and not for
"$['foo.bar']").
Paragraph (version B):
A "dot-member-name-shorthand" of the form ".<member-name>" is
shorthand for "['<member-name>']", but can only be used with member
names that are composed of certain characters.  Thus, for example,
"$.foo.bar" is shorthand for "$['foo']['bar']" (but not for
"$['foo.bar']").
Draft: draft-ietf-jsonpath-base

Commentary: Now we have switched to using function extensions for regexp filter matches , the current syntax requires the result to be compared against a boolean , as shown in this example from PR 330 : This is consistent with the following statement in the " Existence Tests " section of the spec : If we wanted the following syntax to act as a regexp test : we would have to allow a function expression ( returning a boolean result ) to be treated as a ( rather than an or a ) . This would require ( a ) considerable rework of filter selectors and ( b ) making a special case of functions which return booleans . To be clear : I am not in favour of such a change . The reason for raising this issue was so that it does n't come as a surprise to the WG . Thanks to who spotted it when reviewing some draft input to PR 330 . 
 This was fixed by the above PR . 
 Excellent !
Paragraph (version B):
"Boolean" is an abstraction of a primitive value that is either
"true" or "false".
Paragraph (version A):
If it occurs as a "filter-path" in an existence test, the function
is defined to have result type "OptionalNodes" or one of its
subtypes.
Paragraph (version B):
If it occurs as a "filter-path" in an existence test, the function
is defined to have result type "OptionalNodes" or one of its
subtypes, or to have result type "OptionalBoolean" or one of its
subtypes.
Draft: draft-ietf-jsonpath-base

Commentary: thanks for spotting this !
Paragraph (version A):
The example above with the query "$.a[?@.b, ?@.b]" shows that the
filter selector may produce nodelists in distinct orders each time it
appears in the child segment.
Paragraph (version B):
The example above with the query "$.o[?@<3, ?@<3]" shows that the
filter selector may produce nodelists in distinct orders each time it
appears in the child segment.
Draft: draft-ietf-jsonpath-base

Commentary: ... so that they appear in the table of contents . More editorial polishing may be required afterward , but this gets a block move of some examples out of the way while there are n't many other PRs in flight .
Paragraph (version B):
Filter selectors may use function extensions, which are covered in
Section fnex.
Paragraph (version B):
The first set of examples shows some comparison expressions and their
result with a given JSON value as input.
Draft: draft-ietf-jsonpath-base

Commentary: Nice ! Thank you .
Paragraph (version B):
The syntax and semantics of segments are defined in Section segments-
details.
Paragraph (version B):
The syntax and semantics of each kind of segment are defined below.
Draft: draft-ietf-jsonpath-base

Commentary: I like this structure . We might come up with more validity requirements , so we may want to keep this even if = ~ goes away ( which is pretty much what we decided last week ) .
Paragraph (version A):
To be valid, strings on the right-hand side of the "=~" regex
matching operator need to conform to I-D.draft-ietf-jsonpath-iregexp.
Paragraph (version B):
Strings on the right-hand side of the "=~" regex matching operator
MUST conform to I-D.draft-ietf-jsonpath-iregexp.
Draft: draft-ietf-jsonpath-base

Commentary: Thanks for those suggestions . I rebased on HEAD and applied them .
Paragraph (version B):
Segments select children ("[]") or descendants ("..[]") of an input
value.
Paragraph (version A):
A wildcard "*" (wildcard) in the expression "[*]" selects all
children of an object or an array and in the expression "..[*]"
selects all descendants of an object or an array.
Paragraph (version A):
An array slice "start:end:step" (slice) selects a series of elements
from an array, giving a start position, an end position, and possibly
a step value that moves the position from the start to the end.
Paragraph (version A):
tbl-overview provides a quick overview of the JSONPath syntax
elements.
Paragraph (version B):
A wildcard "*" (wildcard) in the expression "[*]" selects all
children of a node and in the expression "..[*]" selects all
descendants of a node.
Paragraph (version B):
An array slice "start:end:step" (slice) selects a series of elements
from an array, giving a start position, an end position, and an
optional step value that moves the position from the start to the
end.
Paragraph (version B):
tbl-overview provides a brief overview of JSONPath syntax.
Draft: draft-ietf-jsonpath-base

Commentary: This is currently done inconsistently and does n't add much value . Instead , define terms in the Terminology section . Reviewers please note : is not modified . This avoids a clash with which deletes the term . 
 Let 's wait until lands before sorting this PR out . Meanwhile , rebased on main and kept one of the italicisations which was previously removed . 
 I 've reinstated the other italics which favoured .
Paragraph (version B):
A JSONPath expression is applied to a JSON value, known as the
argument.  The output is a nodelist.
Paragraph (version A):
of the argument, i.e., to the argument as a whole.  Every JSONPath
expression begins with the root node identifier.
Paragraph (version A):
in the context of the evaluation of a filter expression (described
later).
Paragraph (version B):
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 current node identifier "@" refers to the current node in the
context of the evaluation of a filter expression (described later).
Paragraph (version B):
The query is a root identifier followed by a sequence of zero or more
segments, each of which is applied to the result of the previous root
identifier or segment and provides input to the next segment.  These
results and inputs take the form of a nodelist.
Draft: draft-ietf-jsonpath-base

Commentary: Avoid the term indexing , so we do n't need to worry about whether it applies only to arrays or to arrays and objects .
Paragraph (version A):
A syntactically valid segment MUST NOT produce errors when executing
the query.  This means that some operations that might be considered
erroneous, such as indexing beyond the end of an array, simply result
in fewer nodes being selected.
Paragraph (version B):
A syntactically valid segment MUST NOT produce errors when executing
the query.  This means that some operations that might be considered
erroneous, such as using an index lying outside the range of an
array, simply result in fewer nodes being selected.
Paragraph (version A):
The "index-selector" applied to an array selects an array element
using a zero-based index.  For example, the selector "0" selects the
first and the selector "4" selects the fifth element of a
sufficiently long array.  Nothing is selected, and it is not an
error, if the index lies outside the range of the array.  Nothing is
selected from a value that is not an array.
Paragraph (version B):
A non-negative "index-selector" applied to an array selects an array
element using a zero-based index.  For example, the selector "0"
selects the first and the selector "4" selects the fifth element of a
sufficiently long array.  Nothing is selected, and it is not an
error, if the index lies outside the range of the array.  Nothing is
selected from a value that is not an array.
Paragraph (version A):
The result of the array indexing expression "i" applied to an array
of length "len" is defined to be the result of the array slicing
expression "Normalize(i, len):Normalize(i, len)+1:1".
Paragraph (version B):
The result of the array index expression "i" applied to an array of
length "len" is defined to be the result of the array slicing
expression "Normalize(i, len):Normalize(i, len)+1:1".
Paragraph (version A):
The slice expression selects elements with indices between the lower
and upper bounds.  In the following pseudocode, the "a(i)" construct
expresses the 0-based indexing operation on the underlying array.
Paragraph (version B):
The slice expression selects elements with indices between the lower
and upper bounds.  In the following pseudocode, "a(i)" is the "i+1"th
element of the array "a" (i.e., "a(0)" is the first element, "a(1)"
the second, and so forth).
Draft: draft-ietf-jsonpath-base

Commentary: We wanted to add examples , but maybe we can merge this as is . Marking as ready for review . 
 Let 's get this in and polish it later .
Paragraph (version B):
attack vectors on JSONPath implementations,
Paragraph (version B):
JSONPath queries are often not static, but formed from variables that
provide index values, member names, or values to compare with in a
filter expression.  These variables need to be translated into the
form they take in a JSONPath query, e.g., by escaping string
delimiters, or by only allowing specific constructs such as ".name"
to be formed when the given values allow that.  Failure to perform
these translations correctly can lead to unexpected failures, which
can lead to Availability, Confidentiality, and Integrity breaches, in
particular if an adversary has control over the values (e.g., by
entering them into a Web form).  The resulting class of attacks,
Draft: draft-ietf-jsonpath-base

Commentary: Two potential further improvements .
Paragraph (version A):
The JSON value the JSONPath query is applied to is, by definition, a
valid JSON value.  The parsing of a JSON text into a JSON value and
what happens if a JSON text does not represent valid JSON are not
defined by this specification.  Sections RFC8259 and RFC8259 of
RFC8259 identify specific situations that may conform to the grammar
for JSON texts but are not interoperable uses of JSON, as they may
cause unpredictable behavior.  The present specification does not
attempt to define predictable behavior for JSONPath queries in these
situations.
Paragraph (version B):
The JSON value a JSONPath query is applied to is, by definition, a
valid JSON value.  A JSON value is often constructed by parsing a
JSON text.
Paragraph (version B):
The parsing of a JSON text into a JSON value and what happens if a
JSON text does not represent valid JSON are not defined by this
specification.  Sections RFC8259 and RFC8259 of RFC8259 identify
specific situations that may conform to the grammar for JSON texts
but are not interoperable uses of JSON, as they may cause
unpredictable behavior.  The present specification does not attempt
to define predictable behavior for JSONPath queries in these
situations.
Draft: draft-ietf-jsonpath-base

Commentary: Also delete syntactic noise from semantics section .
Paragraph (version A):
The child segment consists of a non-empty, comma-delimited sequence
of selectors enclosed in square brackets.
Paragraph (version B):
The child segment consists of a non-empty, comma-separated sequence
of selectors enclosed in square brackets.
Paragraph (version A):
A child segment contains a comma-delimited sequence of selectors,
each of which selects zero or more children of the input value.
Paragraph (version B):
A child segment contains a sequence of selectors, each of which
selects zero or more children of the input value.
Draft: draft-ietf-jsonpath-base

Commentary: Non - normative may be a better option , throughout , because surely normative sections are informative too ?  ? 
 Given we use Informative for the non - normative references , I guess we should do the same throughout . Hopefully no - one will misunderstand ...
Paragraph (version A):
This section is non-normative.
Paragraph (version B):
This section is informative.
Draft: draft-ietf-jsonpath-base

Commentary: Move the initial examples into the introduction since the purpose of the examples is introductory .  certain sections as informative ( rather than normative ) . 
 That still feels a little vacuous . How about " This section is non - normative . " ? Too formal ? 
 Merging , to avoid clashes with another PR . 
 This works for me . That said , " This section is for information only " might be a less SDO - geeky way of saying this .
Paragraph (version A):
This section provides examples of JSONPath expressions.  The examples
are based on the simple JSON value shown in fig-example-value,
representing a bookstore (that also has a bicycle).
Paragraph (version B):
This section is informative.  It provides examples of JSONPath
expressions.
Paragraph (version B):
The examples are based on the simple JSON value shown in fig-example-
value, representing a bookstore (that also has a bicycle).
Draft: draft-ietf-jsonpath-base

Commentary: We expect to use this term in the description of extensions .
Paragraph (version A):
A segment performs its function on each of the nodes in its input
nodelist.  Each of these function executions produces a nodelist,
which are then concatenated to produce the result of the segment.  A
node may be selected more than once and appears that number of times
in the nodelist.  Duplicate nodes are not removed.
Paragraph (version B):
A segment operates on each of the nodes in its input nodelist in
turn, and the resultant nodelists are concatenated to produce the
result of the segment.  A node may be selected more than once and
appears that number of times in the nodelist.  Duplicate nodes are
not removed.