From df0d201795d827d7875e902446464536534af235 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Fri, 5 Apr 2024 09:47:14 +0100 Subject: [PATCH 1/3] Define Data Collections used in the spec --- spec/Appendix A -- Notation Conventions.md | 31 ++++++++++++++++++++++ spec/GraphQL.md | 8 ++++-- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/spec/Appendix A -- Notation Conventions.md b/spec/Appendix A -- Notation Conventions.md index 2375f3d67..d24387e93 100644 --- a/spec/Appendix A -- Notation Conventions.md +++ b/spec/Appendix A -- Notation Conventions.md @@ -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 +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. diff --git a/spec/GraphQL.md b/spec/GraphQL.md index fad6bcdbe..e39be12fe 100644 --- a/spec/GraphQL.md +++ b/spec/GraphQL.md @@ -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** From 4a241b23dd06eb8d065fc3f81b177c949079b3e3 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Tue, 1 Apr 2025 18:13:26 +0100 Subject: [PATCH 2/3] Define what a collection is and integrate feedback --- spec/Appendix A -- Notation Conventions.md | 40 ++++++++++++---------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/spec/Appendix A -- Notation Conventions.md b/spec/Appendix A -- Notation Conventions.md index d24387e93..da0a720ae 100644 --- a/spec/Appendix A -- Notation Conventions.md +++ b/spec/Appendix A -- Notation Conventions.md @@ -219,31 +219,35 @@ 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. +A data collection is a finite, iterable aggregation of elements whose iteration +order is not necessarily stable. 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 -clarity the term "ordered list" may be used when an order is semantically +:: The term _list_ describes a sequence of zero or more values, which may +contain duplicates. Currently, all lists in this specification are ordered, but +for 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. +:: The term _set_ describes a collection of zero or more values, which may not +contain duplicates. Each value is considered a "member" of the 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. +:: The term _map_ describes a collection where each element is a pair (called an +"entry") consisting of a key and a value. Keys are unique: no two entries with +the same key may exist in the same map, but values 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. From 68bc42abe47b74d1242f126ee46ec27c75e9e934 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 30 Jun 2025 20:47:52 -0700 Subject: [PATCH 3/3] Lee editorial updates --- spec/Appendix A -- Notation Conventions.md | 46 ++++++++++------------ spec/GraphQL.md | 17 ++++---- 2 files changed, 28 insertions(+), 35 deletions(-) diff --git a/spec/Appendix A -- Notation Conventions.md b/spec/Appendix A -- Notation Conventions.md index da0a720ae..04eaec96d 100644 --- a/spec/Appendix A -- Notation Conventions.md +++ b/spec/Appendix A -- Notation Conventions.md @@ -214,40 +214,36 @@ Fibonacci(number): - Return {Fibonacci(previousNumber)} + {Fibonacci(previousPreviousNumber)}. Note: Algorithms described in this document are written to be easy to -understand. Implementers are encouraged to include equivalent but optimized -implementations. +understand. Implementers are encouraged to include observably equivalent but +optimized implementations. ## Data Collections -A data collection is a finite, iterable aggregation of elements whose iteration -order is not necessarily stable. 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. +Algorithms within this specification refer to abstract data collection types to +express normative structural, uniqueness, and ordering requirements. Temporary +data collections internal to an algorithm use these types to best describe +expected behavior, but implementers are encouraged to provide observably +equivalent but optimized implementations. Implementations may use any data +structure as long as the expected requirements are met. **List** -:: The term _list_ describes a sequence of zero or more values, which may -contain duplicates. Currently, all lists in this specification are ordered, but -for clarity the term "ordered list" may be used when an order is semantically -important. +:: A _list_ is an ordered collection of values which may contain duplicates. A +value added to a list is ordered after existing values. **Set** -:: The term _set_ describes a collection of zero or more values, which may not -contain duplicates. Each value is considered a "member" of the 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. +:: A _set_ is a collection of values which must not contain duplicates. + +:: An _ordered set_ is a set which has a defined order. A value added to an +ordered set, which does not already contain that value, is ordered after +existing values. **Map** -:: The term _map_ describes a collection where each element is a pair (called an -"entry") consisting of a key and a value. Keys are unique: no two entries with -the same key may exist in the same map, but values 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. +:: A _map_ is a collection of entries, each of which has a key and value. Each +entry has a unique key, and can be directly referenced by that key. + +:: An _ordered map_ is a map which has a defined order. An entry added to an +ordered map, which does not have an entry with that key, is ordered after +existing entries. diff --git a/spec/GraphQL.md b/spec/GraphQL.md index e39be12fe..aee494ea7 100644 --- a/spec/GraphQL.md +++ b/spec/GraphQL.md @@ -88,18 +88,15 @@ algorithm step (e.g. "Let completedResult be the result of calling CompleteValue()") is to be interpreted as having at least the same level of requirement as the algorithm containing that step. -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. 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. +Conformance requirements expressed as algorithms and data collections 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. See [Appendix A](#sec-Appendix-Notation-Conventions) for more details about the -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. +definition of algorithms, data collections, and other notational conventions +used in this document. **Non-Normative Portions**