diff --git a/spec/Appendix B -- Notation Conventions.md b/spec/Appendix B -- Notation Conventions.md index 65b215eeb..c318b9715 100644 --- a/spec/Appendix B -- Notation Conventions.md +++ b/spec/Appendix B -- Notation Conventions.md @@ -247,3 +247,9 @@ 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. + +Note: This specification defines ordered data collection only when strictly +required. When an order is observable, implementations should preserve it to +improve output legibility and stability. For example if applying a grammar to an +input string yields a _set_ of elements, serialization should emit those +elements in the same source order. diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index d7f8e629f..d7f2ed8b5 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -117,6 +117,14 @@ Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer-facing warnings. +**Stable Ordering** + +The observable order of all data collections should be preserved to improve +schema legibility and stability. When a schema is produced from a +{TypeSystemDocument}, introspection should return items in the same source order +for each element list: object fields, input object fields, arguments, enum +values, directives, union member types, and implemented interfaces. + **Schema Introspection Schema** The schema introspection system is itself represented as a GraphQL schema. Below