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

Commentary: There may be some more shake - out as filter semantics are scattered through the syntax section . We may need to live with this because it makes more sense to talk about semantics in the context of each particular piece of syntax . But let 's use the current PR just to use the current node term consistently .
Paragraph (version A):
The filter selector has the form "?<expr>".  It works via iterating
over structured values, i.e. arrays and objects.
Paragraph (version A):
During the iteration process each array element or object member is
visited and its value -- accessible via symbol "@" -- or one of its
descendants -- uniquely defined by a relative path -- is tested
against a boolean expression "boolean-expr".
Paragraph (version A):
The current item is selected if and only if the boolean expression
yields true.
Paragraph (version B):
The filter selector has the form "?<expr>".  It iterates over
structured values, i.e., arrays and objects.
Paragraph (version B):
During the iteration process the node of each array element or object
member being visited is known as the current node.  A boolean
expression, usually involving the current node, is evaluated and the
current node is selected if and only if the expression yields true.
Paragraph (version B):
The current node is accessible via the current node identifier "@".
Paragraph (version A):
A relative path, beginning with "@", refers to the current array
element or member value as the filter selector iterates over the
array or object.
Draft: draft-ietf-jsonpath-base

Commentary: Fixes 
 I left that in deliberately . We have removed the colliding term and we are now free to use current node ( ) throughout . I will follow up with a PR which does just that . I objected to the term " function " in this context previously . I 'll follow up with a PR to delete it , which will leave it free for function extensions . 
 The term " current node " is traditionally used with iterating over children of structured nodes in filter selectors . Now it also appears in 3.3 Semantics chapter in a different context : To avoid confusion of readers , we might use a different term there . A good alternative would be " context node " , which is also used by XPath in a similar context . 
 Perhaps a simple solution would be to avoid the use of the term in 3.3 as this term does n't appear to be used elsewhere . 
 Please see the simplification in 
 Note that there is still an instance of " current node identifier " in table 1 . I also note that then English usage of " function " now collides with the term we coin in the function extensions . But the basic change here is right , so I approve .
Paragraph (version A):
A segment performs its function on each of the nodes in its input
nodelist.  During such a function execution, each such node is
referred to as the "current node".  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 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.
Draft: draft-ietf-jsonpath-base

Commentary: This is an attempt to make two sentences in the abstract and introduction less clunky while not jettisoning their precision . 
 Thanks I see you managed to approve a draft PR - interesting . 
 Works for me , although one would need to understand that  values are nested to understand the abstract . ( But we ca n't start from the creation of the universe . )
Paragraph (version A):
JSONPath defines a string syntax for selecting and extracting values
within a JSON (RFC 8259) value.
Paragraph (version A):
JSON RFC8259 is a popular representation format for structured data
values.  JSONPath defines a string syntax for identifying values
within a JSON value.
Paragraph (version B):
JSONPath defines a string syntax for selecting and extracting JSON
(RFC 8259) values from a JSON value.
Paragraph (version B):
JSON RFC8259 is a popular representation format for structured data
values.  JSONPath defines a string syntax for selecting and
extracting JSON values from a JSON value.
Draft: draft-ietf-jsonpath-base

Commentary: This is a stab at addressing one review comments in PR . 
 If you do n't think this PR is going in the right direction , please close it and we 'll circle back to the matter later . 
 The term " current node " is traditionally used with iterating over children of structured nodes in filter selectors . Now it also appears in 3.3 Semantics chapter in a different context : To avoid confusion of readers , we might use a different term there . A good alternative would be " context node " , which is also used by XPath in a similar context . 
 Perhaps a simple solution would be to avoid the use of the term in 3.3 as this term does n't appear to be used elsewhere . 
 Please see the simplification in
Paragraph (version A):
of the argument, i.e., to the argument as a whole.
Paragraph (version B):
A JSONPath expression consists of an identifier followed by a series
of zero or more segments each of which contains one or more
selectors.
Paragraph (version B):
of the argument, i.e., to the argument as a whole.  Every JSONPath
expression begins with the root node identifier.
Paragraph (version B):
in the context of the evaluation of a filter expression (described
later).
Paragraph (version A):
to build paths that are input to a JSONPath implementation.  A single
path may use a combination of bracket and dot notations.
Paragraph (version B):
A JSONPath expression may use a combination of bracket and dot
notations.
Paragraph (version B):
This document treats the bracket notations as canonical and defines
various shorthands in terms of bracket notation.  Examples and
descriptions use shorthands where convenient.
Paragraph (version A):
This document treats the bracket notations as canonical and defines
the above shorthands in terms of the canonical bracket notation.
Draft: draft-ietf-jsonpath-base

Commentary: The deleted text referred , erroneously , to an example obtaining the number of elements in an array . It also used the term " expression mechanism " instead of " filter expression " . On the whole , it seemed better to slim the text down to the bare minimum .
Paragraph (version A):
The examples in tbl-example use the expression mechanism to obtain
the number of elements in an array, to test for the presence of a
member in an object, and to perform numeric comparisons of member
values with a constant.
Paragraph (version B):
tbl-example shows some JSONPath queries that might be applied to this
example and their intended results.
Draft: draft-ietf-jsonpath-base

Commentary: The one to one correspondence sentence gives us most of the desired properties . The fact that for distinct Normalized Paths there will always be at least one JSON value which can distinguish the paths is interesting but not crucial . If it 's confusing to some people , then it 's probably a distraction . 
 yes ... this is a good minimalistic solution ... thanks
Paragraph (version A):
The syntax of Normalized Paths is restricted so that there is one and
only one way of identifying a given node.  Putting this another way,
two distinct Normalized Paths are never equivalent to each other:
there will always be at least one JSON value that yields distinct
results when those paths are applied to it.
Draft: draft-ietf-jsonpath-base

Commentary: There were picked up by Improve table 1 Improve comparison examples Link to Boolean laws Make some examples shorter More list selector examples Compress two examples into one Clarify description of Normalized Paths 
 The section concerning you needs more work , but I 'm going to merge this PR with what we have and start a new one to improve that section . 
 This should do it :
Paragraph (version B):
The logical AND, OR, and NOT operators have the normal semantics of
Boolean algebra and obey its laws (see, for example, BOOLEAN-LAWS).
Paragraph (version A):
The syntax of Normalized Paths is restricted so that there is one and
only one way of representing any given Normalized Path.  Putting this
another way, for any two distinct Normalized Paths, a JSON value
exists that will yield distinct results when the Normalized Paths are
applied to it.
Paragraph (version B):
The syntax of Normalized Paths is restricted so that there is one and
only one way of identifying a given node.  Putting this another way,
two distinct Normalized Paths are never equivalent to each other:
there will always be at least one JSON value that yields distinct
results when those paths are applied to it.
Draft: draft-ietf-jsonpath-base

Commentary: Fix some nits pointed out by Improve definition of children Unicode Scalar Values are integers Typo fix Ordering of non - integer numbers
Paragraph (version A):
for each member of the second object with name "n" and value
"v", there is a member of the first object with name "n" and
value "w" where "v" and "w" yield true when comparsed using
"==".
Paragraph (version B):
for each member of the second object with name "n" and value
"v", there is a member of the first object with name "n" and
value "w" where "v" and "w" yield true when compared using
"==".
Draft: draft-ietf-jsonpath-base

Commentary: The inspiration of the example does n't add much value .
Paragraph (version A):
This section provides some more examples for JSONPath expressions.
The examples are based on the simple JSON value shown in fig-example-
value, which was patterned after a typical XML example representing a
bookstore (that also has bicycles).
Paragraph (version B):
This section provides some more examples for JSONPath expressions.
The examples are based on the simple JSON value shown in fig-example-
value, representing a bookstore (that also has bicycles).
Draft: draft-ietf-jsonpath-base

Commentary: Fixes 
 : 
 It depends . For example , the APIs of some JSONPath implementations take a rich type which represents a valid JSON value . In that case , handling invalid JSON happens before the API is called and is not a concern of the API . But other implementations could have an API which takes a string , which may or may not represent valid JSON . So , to be clear , we probably need some words in the spec which says the spec does not prescribe how invalid JSON is handled . This is better than silence . Or we could require that invalid JSON can not result in a non - empty nodelist from a JSONPath query . 
 But " brokenness " would apply to JSON texts , would n't it ? As noted in ( ) , " JSON text is a sequence of characters , an unparsed piece of JSON for interchange , with newlines and backslashes and all that . JSONPath never looks at JSON texts . JSON value is the RFC 8259 term for what  looks at . " The parser would care about " broken " JSON texts , but  should never see them . 
 Agree with last two points . The spec describes the application of a JSONPath expression to parsed  , so JSON texts are out - of - scope . As says , we should make that explicit . 
   simply that it operates on the  data model . This section covers a range of issues that we 've found in our history , including handling whitespace differences , duplicate keys , etc . I think this is a great approach . 
 Thanks !
Paragraph (version A):
A JSONPath query is a string which selects zero or more nodes of a
piece of JSON.
Paragraph (version B):
A JSONPath query is a string which selects zero or more nodes of a
JSON value.
Paragraph (version B):
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.
Draft: draft-ietf-jsonpath-base

Commentary: LGTM , thanks .
Paragraph (version A):
The examples in tbl-example use the expression mechanism to obtain
the number of elements in an array, to test for the presence of a
member in a object, and to perform numeric comparisons of member
values with a constant.
Paragraph (version B):
The examples in tbl-example use the expression mechanism to obtain
the number of elements in an array, to test for the presence of a
member in an object, and to perform numeric comparisons of member
values with a constant.
Paragraph (version A):
Array slicing is inspired by the behaviour of the
"Array.prototype.slice" method of the JavaScript language as defined
by the ECMA-262 standard ECMA-262, with the addition of the "step"
parameter, which is inspired by the Python slice expression.
Paragraph (version B):
Array slicing is inspired by the behavior of the
"Array.prototype.slice" method of the JavaScript language as defined
by the ECMA-262 standard ECMA-262, with the addition of the "step"
parameter, which is inspired by the Python slice expression.
Paragraph (version A):
The following section specifies the behaviour fully, without
depending on JavaScript or Python behaviour.
Paragraph (version B):
The following section specifies the behavior fully, without depending
on JavaScript or Python behavior.
Paragraph (version A):
During iteration process each array element or object member is
visited and its value -- accessible via symbol "@" -- or one of its
descendants -- uniquely defined by a relative path -- is tested
against a boolean expression "boolean-expr".
Paragraph (version B):
During the iteration process each array element or object member is
visited and its value -- accessible via symbol "@" -- or one of its
descendants -- uniquely defined by a relative path -- is tested
against a boolean expression "boolean-expr".
Paragraph (version A):
Unexpected or unpredictable behaviour can arise from an argument with
certain constructs described as unpredictable by RFC8259.
Predictable behavior can be expected, except in relation to the
ordering of objects, for any argument conforming with RFC7493.
Paragraph (version B):
Unexpected or unpredictable behavior can arise from an argument with
certain constructs described as unpredictable by RFC8259.
Predictable behavior can be expected, except in relation to the
ordering of objects, for any argument conforming with RFC7493.
Draft: draft-ietf-jsonpath-base

Commentary: because it is no longer needed because the expansion is misleading 
 Why is the expansion misleading ? 
 I would have thought it was because the notation is not just for objects . 
 Using the expanded version of the acronym gives the impression that this specification is in some way entangled with JavaScript . ( The fact that Glyn reads " JavaScript Object " as a reference to the string - keyed maps JavaScript started out with is another example for the confusion . ) 
 I feel like anyone who knows about  had likely come across our asked about its relationship with its namesake . I do n't really think this is something that is needed . I mean , do it if it makes you feel better , but it 's not really necessary . 
 In the RFC series , the expansion is no longer needed , which is a good thing , because the expansion is misleading . This PR adapts the JSONPath specification to this fact . I 'm not sure what " this " and " it " are in your message . This PR is not about making anyone of us feel better , it is about improving the document to be less misleading . 
 I think we are all agreed that merging is fine . 
 LGTM , thanks .
Paragraph (version A):
JSONPath defines a string syntax for selecting and extracting values
within a JavaScript Object Notation (JSON, RFC 8259) value.
Paragraph (version A):
JavaScript Object Notation (JSON, RFC8259) is a popular
representation format for structured data values.  JSONPath defines a
string syntax for identifying values within a JSON value.
Paragraph (version B):
JSONPath defines a string syntax for selecting and extracting values
within a JSON (RFC 8259) value.
Paragraph (version B):
JSON RFC8259 is a popular representation format for structured data
values.  JSONPath defines a string syntax for identifying values
within a JSON value.
Draft: draft-ietf-jsonpath-base

Commentary: General statement about duplicate nodes List selector editorial changes
Paragraph (version A):
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 the "current node".  Each of these function executions produces
a nodelist, which are then concatenated into the result of the
selector.
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 the "current node".  Each of these function executions produces
a nodelist, which are then concatenated to produce the result of the
selector.  A node may be selected more than once and appear that
number of times in the nodelist.  Duplicate nodes are not removed.
Paragraph (version A):
The list selector allows combining member names, array indices, and
slices in a single selector.
Paragraph (version B):
The list selector allows combining member names, array indices,
slices, and filters in a single selector.
Paragraph (version A):
The list selector is syntactically related to the "index-selector"
and the "slice-selector".  It contains two or more entries, separated
by commas.
Paragraph (version B):
The list selector is syntactically related to the "dot-selector",
"index-selector", "slice-selector", and the "filter-selector".  It
contains two or more entries, separated by commas.
Draft: draft-ietf-jsonpath-base

Commentary: This is probably a bit too wordy , but is a starting point for a sharper definition of the nodelist orders which can be produced by the descendant selector . Ref : 
 I 'm not sure of the context . Please could you point out particular lines . ( The usual way to do this is to enter your review by clicking a " + " which appears when you hover the mouse pointer just to the left of a line in the " Files changed " tab of the PR . You can comment on a block of lines by clicking on the line number of the first line of the block and then shift - clicking on the line number of the last line of the block . ) Meta comment : thanks for your review . I 'm afraid it 's non - binding . See on the mailing list . 
 I created local comments as requested per Well , let us keep that discussion in that list maybe ?
Paragraph (version A):
Note that there is no "bald" descendant selector "..".
Paragraph (version B):
Note that there is no "bald" descendant selector (".." on its own).
Paragraph (version A):
nodes of an array are visited in array order.
Paragraph (version A):
Children of an object may be visited in any order, since JSON objects
are unordered.
Paragraph (version A):
Implementations may visit descendants in any way providing the
resultant nodelist could have been produced by visiting descendants
as above.
Paragraph (version B):
nodes of any array appear in array order,
Paragraph (version B):
nodes appear immediately before all their descendants.
Paragraph (version B):
This definition does not stipulate the order in which the children of
an object appear, since JSON objects are unordered.
Paragraph (version B):
The resultant nodelist of a "descendant-selector" applied to a node
must be a sub-sequence of an array-sequenced preorder of the
descendants of the node.
Draft: draft-ietf-jsonpath-base

Commentary: The index selector ( but not the index wildcard selector ) selects no elements from non - arrays . See for background . 
 This seems implicit since  objects can not be numerically accessed . 
 Yes , but making it explicit is clearer . 
 This looks okay , and it aligns the text with the previous paragraph .
Paragraph (version A):
Array indexing via "element-index" is a way of selecting a particular
array element using a zero-based index.  For example, selector "[0]"
selects the first and selector "[4]" the fifth element of a
sufficiently long array.
Paragraph (version B):
The "index-selector" applied with an "element-index" to an array
selects an array element using a zero-based index.  For example,
selector "[0]" selects the first and selector "[4]" 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):
A list selector selects the nodes that are selected by at least one
of the selector entries in the list and yields the concatenation of
the lists (in the order of the selector entries) of nodes selected by
the selector entries.  Note that any node selected in more than one
of the selector entries is kept as many times in the node list.
Paragraph (version B):
A list selector selects the nodes that are selected by at least one
of the selector entries in the list and yields the concatenation of
the lists (in the order of the selector entries) of nodes selected by
the selector entries.  Note that any node selected in more than one
of the selector entries is kept as many times in the nodelist.
Draft: draft-ietf-jsonpath-base

Commentary: Fixes 
 In a previous issue , I suggested the idea of adding a processing model description to the specification . So was . However , in re - reading the current document , I found that the process is repeated ( albeit with less detail ) in . I think that the language in 3.4 may be sufficient to explain how the path is expected to operate , making the processing model ( or at least one of them ) somewhat redundant . Can we combine these sections in some way instead of repeating ourselves ? 
 I agree that we could combine these sections and avoid some repetition . I 'm inclined to keep the Semantics section and do away with the Processing Model section since I think the term " Processing Model " is a little obscure compared to " Semantics " . 
 Regardless of my question I like the change .
Paragraph (version A):
Let's walk through an example in detail.  With the argument
"{"a":[{"b":0},{"b":1},{"c":2}]}", the query "$.a[*].b" selects the
following list of nodes: "0", "1" (denoted here by their value).
Paragraph (version B):
Consider this example.  With the argument
"{"a":[{"b":0},{"b":1},{"c":2}]}", the query "$.a[*].b" selects the
following list of nodes: "0", "1" (denoted here by their value).
Draft: draft-ietf-jsonpath-base

Commentary: contains a bulleted list of the selector types . Each of the items in the list ends with a period . While it may ( or may not ) be grammatically correct , it leads to some confusing text , specifically when a selector contains , or completely comprises of , periods . For example : Because we only have plain text , it 's really difficult to see what 's going on here . Formatted , it would look like which is much clearer . If the spec is to continue being issued in a plain text format , I suggest we remove the ending periods from these lines .
Paragraph (version A):
Dot selector ".<name>", used with object member names exclusively.
Paragraph (version A):
Dot wildcard selector ".*".
Paragraph (version A):
Index selector "[<index>]", where "<index>" is either a (possibly
negative, see index-semantics) array index or an object member
name.
Paragraph (version A):
Index wildcard selector "[*]".
Paragraph (version A):
Array slice selector "[<start>:<end>:<step>]", where the optional
values "<start>", "<end>", and "<step>" are integer literals.
Paragraph (version A):
Descendants selector "..".
Paragraph (version A):
List selector "[<sel1>,<sel2>,...,<selN>]", holding a comma
separated list of index and slice selectors.