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

Jump to bottom

Define Data Collections used in the spec #1102

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Define Data Collections used in the spec #1102

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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: 31 additions & 0 deletions spec/Appendix A -- Notation Conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,3 +216,34 @@ Fibonacci(number):
Note: Algorithms described in this document are written to be easy to
understand. Implementers are encouraged to include equivalent but optimized
implementations.

## Data Collections

This specification describes the semantic properties of data collections using
types like "list", "set" and "map". These describe observable data collections
such as the result of applying a grammar and the inputs and outputs of
algorithms. They also describe unobservable data collections such as temporary
data internal to an algorithm. Each data collection type defines the operations
available, and whether values are unique or ordered.

**List**

:: The term _list_ describes a sequence of values which may not be unique. A
list is ordered unless explicitly stated otherwise (as an "unordered list"). For
Copy link
Contributor

Choose a reason for hiding this comment

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

I am not sure "unordered list" makes sense. I mean the ability to iterate over something in well defined way, meaning it can be viewed as a sequence of elements, implies an order in my view.

You could maybe argue that unordered list means the order could change with each iteration, but not sure that is helpful in our context.

Maybe we can get rid of "unordered list"?

Copy link
Member Author

@benjie benjie Sep 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

We don't have any examples of unordered lists being referenced the spec currently, as far as I know. Though the List wrapper type only dictates that the serialized result is an ordered list, it doesn't specifically, as far as I know, require that the underlying list is ordered.

A common example of an unordered list that might be exposed through GraphQL would be the result of select * from my_table; in SQL - this SQL statement has no implicit ordering, and thus may be returned in any order, each time you issue the query you may get a different result even without the underlying data having changed.

I think we should reserve space to reference this concept.

clarity the term "ordered list" may be used when an order is semantically
important.

**Set**

:: The term _set_ describes a unique collection of values, where each value is
considered a "member" of that set. A set is unordered unless explicitly stated
otherwise (as an "ordered set"). For clarity the term "unordered set" may be
used when the lack of an order is semantically important.

**Map**

:: The term _map_ describes a collection of "entry" key and value pairs, where
the set of keys across all entries is unique but the values across all entries
may repeat. A map is unordered unless explicitly stated otherwise (as an
"ordered map"). For clarity the term "unordered map" may be used when the lack
of an order is semantically important.
8 changes: 6 additions & 2 deletions spec/GraphQL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,10 +92,14 @@ Conformance requirements expressed as algorithms can be fulfilled by an
implementation of this specification in any way as long as the perceived result
is equivalent. Algorithms described in this document are written to be easy to
understand. Implementers are encouraged to include equivalent but optimized
implementations.
implementations. Similarly, data collections such as _list_, _set_ and _map_
also introduce conformance requirements. Implementers are free to use
alternative data collections as long as the perceived result remains equivalent.

See [Appendix A](#sec-Appendix-Notation-Conventions) for more details about the
definition of algorithms and other notational conventions used in this document.
definition of algorithms and other notational conventions used in this document,
and [Appendix A: Data Collections](#sec-Data-Collections) for specifics of data
collections and their ordering.

**Non-Normative Portions**

Expand Down
Loading