From df0d201795d827d7875e902446464536534af235 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Fri, 5 Apr 2024 09:47:14 +0100 Subject: [PATCH] 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**