Merge branch 'main' into oneof-v2

benjie · benjie · commit dddd4b81e221 · 2025-07-04T15:19:47.000+01:00
diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md
@@ -247,6 +247,11 @@ GraphQL descriptions are provided as Markdown (as specified by
 [CommonMark](https://commonmark.org/)). Description strings (often
 {BlockString}) occur immediately before the definition they describe.
 
+Descriptions in GraphQL executable documents are purely for documentation
+purposes. They MUST NOT affect the execution, validation, or response of a
+GraphQL document. It is safe to remove all descriptions and comments from
+executable documents without changing their behavior or results.
+
 This is an example of a well-described operation:
 
 ```graphql example
@@ -279,11 +284,6 @@ fragment TimeMachineDetails on TimeMachine {
 }
 ```
 
-Descriptions in GraphQL executable documents are purely for documentation
-purposes. They MUST NOT affect the execution, validation, or response of a
-GraphQL document. It is safe to remove all descriptions and comments from
-executable documents without changing their behavior or results.
-
 ## Document
 
 Document : Definition+
diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md
@@ -58,7 +58,7 @@ via introspection.
 
 [Descriptions](#sec-Descriptions) allow GraphQL service designers to easily
 provide documentation which remains consistent with the capabilities of a
-GraphQL service. Descriptions provided as Markdown (as specified by
+GraphQL service. Descriptions should be provided as Markdown (as specified by
 [CommonMark](https://commonmark.org/)) for every definition in a type system.
 
 GraphQL schema and all other definitions (e.g. types, fields, arguments, etc.)
@@ -775,8 +775,8 @@ type Person {
 }
 ```
 
-Valid operations must supply a _selection set_ for every field of an object
-type, so this operation is not valid:
+Valid operations must supply a _selection set_ for every field whose return type
+is an object type, so this operation is not valid:
 
 ```graphql counter-example
 {
@@ -938,6 +938,8 @@ of rules must be adhered to by every Object type in a GraphQL schema.
          returns {true}.
       4. If argument type is Non-Null and a default value is not defined:
          1. The `@deprecated` directive must not be applied to this argument.
+      5. If the argument has a default value it must be compatible with
+         {argumentType} as per the coercion rules for that type.
 3. An object type may declare that it implements one or more unique interfaces.
 4. An object type must be a super-set of all interfaces it implements:
    1. Let this object type be {objectType}.
@@ -1680,7 +1682,8 @@ defined by the input object type and for which a value exists. The resulting map
 is constructed with the following rules:
 
 - If no value is provided for a defined input object field and that field
-  definition provides a default value, the default value should be used. If no
+  definition provides a default value, the result of coercing the default value
+  according to the coercion rules of the input field type should be used. If no
   default value is provided and the input object field's type is non-null, an
   error should be raised. Otherwise, if the field is not required, then no entry
   is added to the coerced unordered map.
@@ -1803,6 +1806,44 @@ input ExampleOneOfInputObject @oneOf {
 3. If an Input Object references itself either directly or through referenced
    Input Objects, at least one of the fields in the chain of references must be
    either a nullable or a List type.
+4. {InputObjectDefaultValueHasCycle(inputObject)} must be {false}.
+
+InputObjectDefaultValueHasCycle(inputObject, defaultValue, visitedFields):
+
+- If {defaultValue} is not provided, initialize it to an empty unordered map.
+- If {visitedFields} is not provided, initialize it to the empty set.
+- If {defaultValue} is a list:
+  - For each {itemValue} in {defaultValue}:
+    - If {InputObjectDefaultValueHasCycle(inputObject, itemValue,
+      visitedFields)}, return {true}.
+- Otherwise, if {defaultValue} is an unordered map:
+  - For each field {field} in {inputObject}:
+    - If {InputFieldDefaultValueHasCycle(field, defaultValue, visitedFields)},
+      return {true}.
+- Return {false}.
+
+InputFieldDefaultValueHasCycle(field, defaultValue, visitedFields):
+
+- Assert: {defaultValue} is an unordered map.
+- Let {fieldType} be the type of {field}.
+- Let {namedFieldType} be the underlying named type of {fieldType}.
+- If {namedFieldType} is not an input object type:
+  - Return {false}.
+- Let {fieldName} be the name of {field}.
+- Let {fieldDefaultValue} be the value for {fieldName} in {defaultValue}.
+- If {fieldDefaultValue} exists:
+  - Return {InputObjectDefaultValueHasCycle(namedFieldType, fieldDefaultValue,
+    visitedFields)}.
+- Otherwise:
+  - Let {fieldDefaultValue} be the default value of {field}.
+  - If {fieldDefaultValue} does not exist:
+    - Return {false}.
+  - If {field} is within {visitedFields}:
+    - Return {true}.
+  - Let {nextVisitedFields} be a new set containing {field} and everything from
+    {visitedFields}.
+  - Return {InputObjectDefaultValueHasCycle(namedFieldType, fieldDefaultValue,
+    nextVisitedFields)}.
 
 ### Input Object Extensions
 
diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md
@@ -356,11 +356,11 @@ CollectSubscriptionFields(objectType, selectionSet, visitedFragments):
     - If {DoesFragmentTypeApply(objectType, fragmentType)} is {false}, continue
       with the next {selection} in {selectionSet}.
     - Let {fragmentSelectionSet} be the top-level selection set of {fragment}.
-    - Let {fragmentCollectedFieldMap} be the result of calling
+    - Let {fragmentCollectedFieldsMap} be the result of calling
       {CollectSubscriptionFields(objectType, fragmentSelectionSet,
       visitedFragments)}.
     - For each {responseName} and {fragmentFields} in
-      {fragmentCollectedFieldMap}:
+      {fragmentCollectedFieldsMap}:
       - Let {fieldsForResponseKey} be the _field set_ value in
         {collectedFieldsMap} for the key {responseName}; otherwise create the
         entry with an empty ordered set.
@@ -371,11 +371,11 @@ CollectSubscriptionFields(objectType, selectionSet, visitedFragments):
       fragmentType)} is {false}, continue with the next {selection} in
       {selectionSet}.
     - Let {fragmentSelectionSet} be the top-level selection set of {selection}.
-    - Let {fragmentCollectedFieldMap} be the result of calling
+    - Let {fragmentCollectedFieldsMap} be the result of calling
       {CollectSubscriptionFields(objectType, fragmentSelectionSet,
       visitedFragments)}.
     - For each {responseName} and {fragmentFields} in
-      {fragmentCollectedFieldMap}:
+      {fragmentCollectedFieldsMap}:
       - Let {fieldsForResponseKey} be the _field set_ value in
         {collectedFieldsMap} for the key {responseName}; otherwise create the
         entry with an empty ordered set.
@@ -606,7 +606,7 @@ should be unambiguous. Therefore any two field selections which might both be
 encountered for the same object are only valid if they are equivalent.
 
 During execution, the simultaneous execution of fields with the same response
-name is accomplished by {CollectSubfields()} before execution.
+name is accomplished by performing {CollectSubfields()} before their execution.
 
 For simple hand-written GraphQL, this rule is obviously a clear developer error,
 however nested fragments can make this difficult to detect manually.
diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md
@@ -110,8 +110,10 @@ CoerceVariableValues(schema, operation, variableValues):
   - Let {value} be the value provided in {variableValues} for the name
     {variableName}.
   - If {hasValue} is not {true} and {defaultValue} exists (including {null}):
+    - Let {coercedDefaultValue} be the result of coercing {defaultValue}
+      according to the input coercion rules of {variableType}.
     - Add an entry to {coercedValues} named {variableName} with the value
-      {defaultValue}.
+      {coercedDefaultValue}.
   - Otherwise if {variableType} is a Non-Nullable type, and either {hasValue} is
     not {true} or {value} is {null}, raise a _request error_.
   - Otherwise if {hasValue} is {true}:
@@ -367,9 +369,9 @@ continues until there are no more subfields to collect and execute.
 operation. A root selection set always selects from a _root operation type_.
 
 To execute the root selection set, the initial value being evaluated and the
-root type must be known, as well as whether each field must be executed
-serially, or normally by executing all fields in parallel (see
-[Normal and Serial Execution](#sec-Normal-and-Serial-Execution).
+root type must be known, as well as whether the fields must be executed in a
+series, or normally by executing all fields in parallel (see
+[Normal and Serial Execution](#sec-Normal-and-Serial-Execution)).
 
 Executing the root selection set works similarly for queries (parallel),
 mutations (serial), and subscriptions (where it is executed for each event in
@@ -394,10 +396,9 @@ executionMode):
 ### Field Collection
 
 Before execution, each _selection set_ is converted to a _collected fields map_
-by calling {CollectFields()} by collecting all fields with the same response
-name, including those in referenced fragments, into an individual _field set_.
-This ensures that multiple references to fields with the same response name will
-only be executed once.
+by collecting all fields with the same response name, including those in
+referenced fragments, into an individual _field set_. This ensures that multiple
+references to fields with the same response name will only be executed once.
 
 :: A _collected fields map_ is an ordered map where each entry is a _response
 name_ and its associated _field set_. A _collected fields map_ may be produced
@@ -434,8 +435,8 @@ fragment ExampleFragment on Query {
 }
 ```
 
-The depth-first-search order of the _field set_ produced by {CollectFields()} is
-maintained through execution, ensuring that fields appear in the executed
+The depth-first-search order of each _field set_ produced by {CollectFields()}
+is maintained through execution, ensuring that fields appear in the executed
 response in a stable and predictable order.
 
 CollectFields(objectType, selectionSet, variableValues, visitedFragments):
@@ -473,11 +474,11 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
     - If {DoesFragmentTypeApply(objectType, fragmentType)} is {false}, continue
       with the next {selection} in {selectionSet}.
     - Let {fragmentSelectionSet} be the top-level selection set of {fragment}.
-    - Let {fragmentCollectedFieldMap} be the result of calling
+    - Let {fragmentCollectedFieldsMap} be the result of calling
       {CollectFields(objectType, fragmentSelectionSet, variableValues,
       visitedFragments)}.
     - For each {responseName} and {fragmentFields} in
-      {fragmentCollectedFieldMap}:
+      {fragmentCollectedFieldsMap}:
       - Let {fieldsForResponseName} be the _field set_ value in
         {collectedFieldsMap} for the key {responseName}; otherwise create the
         entry with an empty ordered set.
@@ -488,11 +489,11 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
       fragmentType)} is {false}, continue with the next {selection} in
       {selectionSet}.
     - Let {fragmentSelectionSet} be the top-level selection set of {selection}.
-    - Let {fragmentCollectedFieldMap} be the result of calling
+    - Let {fragmentCollectedFieldsMap} be the result of calling
       {CollectFields(objectType, fragmentSelectionSet, variableValues,
       visitedFragments)}.
     - For each {responseName} and {fragmentFields} in
-      {fragmentCollectedFieldMap}:
+      {fragmentCollectedFieldsMap}:
       - Let {fieldsForResponseName} be the _field set_ value in
         {collectedFieldsMap} for the key {responseName}; otherwise create the
         entry with an empty ordered set.
@@ -516,8 +517,8 @@ directives may be applied in either order since they apply commutatively.
 
 **Merging Selection Sets**
 
-In order to execute the sub-selections of a object typed field, all _selection
-sets_ of each field with the same response name of the parent _field set_ are
+In order to execute the sub-selections of an object typed field, all _selection
+sets_ of each field with the same response name in the parent _field set_ are
 merged together into a single _collected fields map_ representing the subfields
 to be executed next.
 
@@ -552,9 +553,9 @@ CollectSubfields(objectType, fields, variableValues):
 - For each {field} in {fields}:
   - Let {fieldSelectionSet} be the selection set of {field}.
   - If {fieldSelectionSet} is null or empty, continue to the next field.
-  - Let {fieldCollectedFieldMap} be the result of {CollectFields(objectType,
+  - Let {fieldCollectedFieldsMap} be the result of {CollectFields(objectType,
     fieldSelectionSet, variableValues)}.
-  - For each {responseName} and {subfields} in {fieldCollectedFieldMap}:
+  - For each {responseName} and {subfields} in {fieldCollectedFieldsMap}:
     - Let {fieldsForResponseName} be the _field set_ value in
       {collectedFieldsMap} for the key {responseName}; otherwise create the
       entry with an empty ordered set.
@@ -749,20 +750,22 @@ CoerceArgumentValues(objectType, field, variableValues):
   - Let {argumentName} be the name of {argumentDefinition}.
   - Let {argumentType} be the expected type of {argumentDefinition}.
   - Let {defaultValue} be the default value for {argumentDefinition}.
-  - Let {hasValue} be {true} if {argumentValues} provides a value for the name
-    {argumentName}.
   - Let {argumentValue} be the value provided in {argumentValues} for the name
     {argumentName}.
   - If {argumentValue} is a {Variable}:
     - Let {variableName} be the name of {argumentValue}.
-    - Let {hasValue} be {true} if {variableValues} provides a value for the name
-      {variableName}.
-    - Let {value} be the value provided in {variableValues} for the name
-      {variableName}.
-  - Otherwise, let {value} be {argumentValue}.
+    - If {variableValues} provides a value for the name {variableName}:
+      - Let {hasValue} be {true}.
+      - Let {value} be the value provided in {variableValues} for the name
+        {variableName}.
+  - Otherwise if {argumentValues} provides a value for the name {argumentName}.
+    - Let {hasValue} be {true}.
+    - Let {value} be {argumentValue}.
   - If {hasValue} is not {true} and {defaultValue} exists (including {null}):
+    - Let {coercedDefaultValue} be the result of coercing {defaultValue}
+      according to the input coercion rules of {argumentType}.
     - Add an entry to {coercedValues} named {argumentName} with the value
-      {defaultValue}.
+      {coercedDefaultValue}.
   - Otherwise if {argumentType} is a Non-Nullable type, and either {hasValue} is
     not {true} or {value} is {null}, raise an _execution error_.
   - Otherwise if {hasValue} is {true}:
@@ -788,6 +791,9 @@ Note: Variable values are not coerced because they are expected to be coerced
 before executing the operation in {CoerceVariableValues()}, and valid operations
 must only allow usage of variables of appropriate types.
 
+Note: Implementations are encouraged to optimize the coercion of an argument's
+default value by doing so only once and caching the resulting coerced value.
+
 ### Value Resolution
 
 While nearly all of GraphQL execution can be described generically, ultimately
