From b9725d735e954a1710eae62b6ee753e9d4045bcf Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Fri, 5 Apr 2024 09:52:34 +0100 Subject: [PATCH] Add recommendation to preserve order where possible --- spec/Appendix A -- Notation Conventions.md | 8 ++++++++ spec/Section 4 -- Introspection.md | 11 +++++++++++ 2 files changed, 19 insertions(+) diff --git a/spec/Appendix A -- Notation Conventions.md b/spec/Appendix A -- Notation Conventions.md index 04eaec96d..37d3a609d 100644 --- a/spec/Appendix A -- Notation Conventions.md +++ b/spec/Appendix A -- Notation Conventions.md @@ -247,3 +247,11 @@ 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. + +**Preserving order** + +To improve legibility, when possible implementations should preserve observable +order for unordered data collections. For example, if applying a grammar to an +input string produces an unordered set, serializing that set (to a string or +other observable output) should produce the same order found in the original +input string. diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index d7f8e629f..916e6ad42 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -117,6 +117,17 @@ Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer-facing warnings. +**Ordering** + +When possible, implementations should preserve observable order for unordered +data collections. For example, if a schema was produced from a source +{TypeSystemDocument} then introspection of fields, input fields, arguments, enum +values, directives, union members, implemented interfaces and so on should +produce the same order as found in the source. + +Note: This recommendation is to improve legibility and stability of schema +representations. + **Schema Introspection Schema** The schema introspection system is itself represented as a GraphQL schema. Below