diff --git a/spec/Appendix A -- Notation Conventions.md b/spec/Appendix A -- Notation Conventions.md index d24387e93..4f98c7a20 100644 --- a/spec/Appendix A -- Notation Conventions.md +++ b/spec/Appendix A -- Notation Conventions.md @@ -247,3 +247,11 @@ 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. + +**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 d2ec33b6b..a5f5ad366 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