Recommend that order of unordered collections is maintained where possible (#1092)

benjie · leebyron · web-flow · commit f70abe24469d · 2025-09-01T01:59:45.000-07:00
* Add recommendation to preserve order where possible

* wordsmithing

* another round of clarification

* explicit data structure in example

* use 'required'

---------

Co-authored-by: Lee Byron &lt;lee@leebyron.com&gt;
diff --git 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
@@ -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
