Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define descendant list semantics #233

Merged
merged 3 commits into from
Aug 23, 2022
Merged

Define descendant list semantics #233

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9c30b7f
Improve wording of list selector semantics
glyn Aug 8, 2022
d3b0fa6
Define descendant/list selector semantics
glyn Aug 22, 2022
32d279e
Avoid sequential language
glyn Aug 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 20 additions & 11 deletions draft-ietf-jsonpath-base.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1334,7 +1334,7 @@ list-entry = ( quoted-member-name /
#### Semantics
{: unnumbered}

A list selector selects the nodes that are selected by at least one of
A list selector selects the nodes that are selected by
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major semantics change here?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That wasn't my intention. The "at least one of" wording was vestigial and related to when we were considering removing duplicates. Now that duplicate nodes and values are retained, the wording is no longer needed.

Or am I missing something?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a change fixing vestigial text

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.
Expand Down Expand Up @@ -1391,22 +1391,31 @@ Note that `..` on its own is not a valid selector.
#### Semantics
{: unnumbered}

A `descendant-selector` selects certain descendants of a node:
A descendant selector selects zero or more descendants of a node.

* the `..<name>` form (and the `..[<index>]` form where `<index>` is a `quoted-member-name`) selects those descendants that are member values of an object with the given member name.
* the `..[<index>]` form, where `<index>` is an `element-index`, selects those descendants that are array elements with the given index.
* the `..[<slice-index>]` form selects those descendants that are array elements selected by the given slice.
* the `..[<filter>]` form selects those descendants that are array elements or object values selected by the given filter.
* the `..[*]` and `..*` forms select all the descendants.

An _array-sequenced preorder_ of the descendants of a node is a sequence of all the descendants in which:
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR removes the need for the term "array-sequenced preorder" by talking instead about a nodelist of the descendants with the same properties. I think this is easier to read and gives the same ordering properties.

A nodelist enumerating the descendants is known as a _descendant nodelist_ when:

* nodes of any array appear in array order,
* nodes appear immediately before all their descendants.

This definition does not stipulate the order in which the children of an object appear, since JSON objects are unordered.
This definition does not stipulate the order in which the children of an object appear, since
JSON objects are unordered.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Slightly more correct I think: The order of the members in a JSON object is not information-bearing.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence "The order of the members in a JSON object is not information-bearing." is a bit tricky because it refers to "The order of the members in a JSON object" as if that was somehow well defined. Also, I'm not sure how many people would understand the sentence because the term "information-bearing" is a little unusual. I think I'll stick with the informal language for now.



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.
The resultant nodelist of a descendant selector is the result of applying a selector
(or no selector), depending on the variant of the descendant selector, to a
descendant nodelist, as shown below:

| Variant | Selector to apply | Comment |
| :---: | :---: | ------- |
| `..<name>` | `.<name>`| [Dot selector](#dot-selector) |
| `..*` | _none_ | All descendants |
| `..[<name>]` | `[<name>]`| [Index selector](#index-selector) |
| `..[*]` | _none_ | All descendants |
| `..[<slice-index>]` | `[<slice-index>]` | [Array slice selector](#slice) |
| `..[<filter>]` | `[<filter>]` | [Filter selector](#filter-selector) |
| `..[<list-entry>,...]` | `[<list-entry>,...]` | [List selector](#list-selector) |
{: title="Descendant selector variant semantics"}

#### Examples
{: unnumbered}
Expand Down