Merge branch 'main' into subscription-single-root-field

Author: benjie

.github/algorithm-format-check.mjs

@@ -2,6 +2,9 @@ import { readFile, readdir } from "node:fs/promises";
 
 const SPEC_DIR = new URL("../spec", import.meta.url).pathname;
 
+/** @see {@link https://spec-md.com/#sec-Value-Literals} */
+const valueLiteralsRegexp = /\{((?:[^{}]|(?:\{[^{}]*\}))+)\}/g;
+
 process.exitCode = 0;
 const filenames = await readdir(SPEC_DIR);
 for (const filename of filenames) {
@@ -72,6 +75,33 @@ for (const filename of filenames) {
             console.log();
             process.exitCode = 1;
           }
+
+          const stepWithoutValueLiterals = step.replace(
+            valueLiteralsRegexp,
+            ""
+          );
+          if (stepWithoutValueLiterals.match(/\b[A-Z][A-Za-z0-9]+\(/)) {
+            console.log(
+              `Bad formatting of '${algorithmName}' step (algorithm call should be wrapped in braces: \`{MyAlgorithm(a, b, c)}\`) in '${filename}':`
+            );
+            console.dir(step);
+            console.log();
+            process.exitCode = 1;
+          }
+
+          const valueLiterals = step.matchAll(valueLiteralsRegexp, "");
+          for (const lit of valueLiterals) {
+            const inner = lit[1];
+            if (inner.includes("{")) {
+              console.log(
+                `Bad formatting of '${algorithmName}' step (algorithm call should not contain braces: \`${lit}\`) in '${filename}':`
+              );
+              console.dir(step);
+              console.log();
+              process.exitCode = 1;
+            }
+          }
+
           const trimmedInnerLine = step.replace(/\s+/g, " ");
           if (
             trimmedInnerLine.match(

CONTRIBUTING.md

@@ -6,8 +6,9 @@ contributions.
 
 Contributions that do not change the interpretation of the spec but instead
 improve legibility, fix editorial errors, clear up ambiguity and improve
-examples are encouraged and are often merged by a spec editor with little
-process.
+examples are encouraged. These "editorial changes" will normally be given the
+["✏ Editorial" label](https://github.com/graphql/graphql-spec/issues?q=sort%3Aupdated-desc+is%3Aopen+label%3A%22%E2%9C%8F%EF%B8%8F+Editorial%22)
+and are often merged by a spec editor with little process.
 
 However, contributions that _do_ meaningfully change the interpretation of the
 spec must follow an RFC (Request For Comments) process led by a _champion_

README.md

@@ -1,4 +1,4 @@
-[![GraphQLConf 2024 Banner: September 10-12, San Francisco. Hosted by the GraphQL Foundation](https://github.com/user-attachments/assets/0203f10b-ae1e-4fe1-9222-6547fa2bbd5d)](https://graphql.org/conf/2024/?utm_source=github&utm_medium=graphql_spec&utm_campaign=readme)
+[![GraphQLConf 2025 Banner: September 08-10, Amsterdam. Hosted by the GraphQL Foundation](./assets/graphql.org_conf_2025_.png)](https://graphql.org/conf/2025/?utm_source=github&utm_medium=graphql_js&utm_campaign=readme)
 
 # GraphQL
 

STYLE_GUIDE.md

@@ -82,3 +82,25 @@ MyAlgorithm(argOne, argTwo):
     - Let {something} be {true}.
 - Return {something}.
 ```
+
+## Definitions
+
+For important terms, use
+[Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph).
+
+Definition paragraphs start with `::` and add the matching italicized term to
+the [specification index](https://spec.graphql.org/draft/#index), making it easy
+to reference them.
+
+## Tone of voice
+
+The GraphQL specification is a reference document and should use neutral and
+descriptive tone of voice.
+
+**Favor the present tense**
+
+The present tense is usually clearer and shorter:
+
+✅ Present: The client then sends a request to the server.
+
+❌ Future: The client will then send a request to the server.

assets/graphql.org_conf_2025_.png

@@ -466,8 +466,9 @@ These two operations are semantically identical:
 
 Alias : Name :
 
-By default a field's response key in the response object will use that field's
-name. However, you can define a different response key by specifying an alias.
+:: A _response name_ is the key in the response object which correlates with a
+field's result. By default the response name will use the field's name; however,
+you can define a different response name by specifying an alias.
 
 In this example, we can fetch two profile pictures of different sizes and ensure
 the resulting response object will not have duplicate keys:
@@ -1253,7 +1254,7 @@ Type : Name
 
 - Let {name} be the string value of {Name}.
 - Let {type} be the type defined in the Schema named {name}.
-- {type} must not be {null}.
+- {type} must exist.
 - Return {type}.
 
 Type : [ Type ]

spec/Section 2 -- Language.md

@@ -329,8 +329,8 @@ A GraphQL schema may describe that a field represents a list of another type;
 the `List` type is provided for this reason, and wraps another type.
 
 Similarly, the `Non-Null` type wraps another type, and denotes that the
-resulting value will never be {null} (and that a _field error_ cannot result in
-a {null} value).
+resulting value will never be {null} (and that an _execution error_ cannot
+result in a {null} value).
 
 These two types are referred to as "wrapping types"; non-wrapping types are
 referred to as "named types". A wrapping type has an underlying named type,
@@ -351,7 +351,7 @@ IsInputType(type):
 
 - If {type} is a List type or Non-Null type:
   - Let {unwrappedType} be the unwrapped type of {type}.
-  - Return IsInputType({unwrappedType}).
+  - Return {IsInputType(unwrappedType)}.
 - If {type} is a Scalar, Enum, or Input Object type:
   - Return {true}.
 - Return {false}.
@@ -360,7 +360,7 @@ IsOutputType(type):
 
 - If {type} is a List type or Non-Null type:
   - Let {unwrappedType} be the unwrapped type of {type}.
-  - Return IsOutputType({unwrappedType}).
+  - Return {IsOutputType(unwrappedType)}.
 - If {type} is a Scalar, Object, Interface, Union, or Enum type:
   - Return {true}.
 - Return {false}.
@@ -461,14 +461,14 @@ more guidance.
 
 A GraphQL service, when preparing a field of a given scalar type, must uphold
 the contract the scalar type describes, either by coercing the value or
-producing a _field error_ if a value cannot be coerced or if coercion may result
-in data loss.
+producing an _execution error_ if a value cannot be coerced or if coercion may
+result in data loss.
 
 A GraphQL service may decide to allow coercing different internal types to the
 expected return type. For example when coercing a field of type {Int} a boolean
 {true} value may produce {1} or a string value {"123"} may be parsed as base-10
 {123}. However if internal type coercion cannot be reasonably performed without
-losing information, then it must raise a _field error_.
+losing information, then it must raise an _execution error_.
 
 Since this coercion behavior is not observable to clients of the GraphQL
 service, the precise rules of coercion are left to the implementation. The only
@@ -513,15 +513,15 @@ Fields returning the type {Int} expect to encounter 32-bit integer internal
 values.
 
 GraphQL services may coerce non-integer internal values to integers when
-reasonable without losing information, otherwise they must raise a _field
+reasonable without losing information, otherwise they must raise an _execution
 error_. Examples of this may include returning `1` for the floating-point number
 `1.0`, or returning `123` for the string `"123"`. In scenarios where coercion
-may lose data, raising a field error is more appropriate. For example, a
-floating-point number `1.2` should raise a field error instead of being
+may lose data, raising an execution error is more appropriate. For example, a
+floating-point number `1.2` should raise an execution error instead of being
 truncated to `1`.
 
 If the integer internal value represents a value less than -2<sup>31</sup> or
-greater than or equal to 2<sup>31</sup>, a _field error_ should be raised.
+greater than or equal to 2<sup>31</sup>, an _execution error_ should be raised.
 
 **Input Coercion**
 
@@ -548,12 +548,12 @@ Fields returning the type {Float} expect to encounter double-precision
 floating-point internal values.
 
 GraphQL services may coerce non-floating-point internal values to {Float} when
-reasonable without losing information, otherwise they must raise a _field
+reasonable without losing information, otherwise they must raise an _execution
 error_. Examples of this may include returning `1.0` for the integer number `1`,
 or `123.0` for the string `"123"`.
 
 Non-finite floating-point internal values ({NaN} and {Infinity}) cannot be
-coerced to {Float} and must raise a _field error_.
+coerced to {Float} and must raise an _execution error_.
 
 **Input Coercion**
 
@@ -579,9 +579,9 @@ that representation must be used to serialize this type.
 Fields returning the type {String} expect to encounter Unicode string values.
 
 GraphQL services may coerce non-string raw values to {String} when reasonable
-without losing information, otherwise they must raise a _field error_. Examples
-of this may include returning the string `"true"` for a boolean true value, or
-the string `"1"` for the integer `1`.
+without losing information, otherwise they must raise an _execution error_.
+Examples of this may include returning the string `"true"` for a boolean true
+value, or the string `"1"` for the integer `1`.
 
 **Input Coercion**
 
@@ -600,8 +600,8 @@ representation of the integers `1` and `0`.
 Fields returning the type {Boolean} expect to encounter boolean internal values.
 
 GraphQL services may coerce non-boolean raw values to {Boolean} when reasonable
-without losing information, otherwise they must raise a _field error_. Examples
-of this may include returning `true` for non-zero numbers.
+without losing information, otherwise they must raise an _execution error_.
+Examples of this may include returning `true` for non-zero numbers.
 
 **Input Coercion**
 
@@ -623,7 +623,7 @@ large 128-bit random numbers, to base64 encoded values, or string values of a
 format like [GUID](https://en.wikipedia.org/wiki/Globally_unique_identifier).
 
 GraphQL services should coerce as appropriate given the ID formats they expect.
-When coercion is not possible they must raise a _field error_.
+When coercion is not possible they must raise an _execution error_.
 
 **Input Coercion**
 
@@ -947,6 +947,7 @@ IsValidImplementation(type, implementedType):
        2. Let {implementedFieldType} be the return type of {implementedField}.
        3. {IsValidImplementationFieldType(fieldType, implementedFieldType)} must
           be {true}.
+    6. If {field} is deprecated then {implementedField} must also be deprecated.
 
 IsValidImplementationFieldType(fieldType, implementedFieldType):
 
@@ -1492,7 +1493,7 @@ enum Direction {
 **Result Coercion**
 
 GraphQL services must return one of the defined set of possible values. If a
-reasonable coercion is not possible they must raise a _field error_.
+reasonable coercion is not possible they must raise an _execution error_.
 
 **Input Coercion**
 
@@ -1548,8 +1549,9 @@ Fields may accept arguments to configure their behavior. These inputs are often
 scalars or enums, but they sometimes need to represent more complex values.
 
 A GraphQL Input Object defines a set of input fields; the input fields are
-either scalars, enums, or other input objects. This allows arguments to accept
-arbitrarily complex structs.
+scalars, enums, other input objects, or any wrapping type whose underlying base
+type is one of those three. This allows arguments to accept arbitrarily complex
+structs.
 
 In this example, an Input Object called `Point2D` describes `x` and `y` inputs:
 
@@ -1654,10 +1656,10 @@ is constructed with the following rules:
 
 - If a variable is provided for an input object field, the runtime value of that
   variable must be used. If the runtime value is {null} and the field type is
-  non-null, a _field error_ must be raised. If no runtime value is provided, the
-  variable definition's default value should be used. If the variable definition
-  does not provide a default value, the input object field definition's default
-  value should be used.
+  non-null, an _execution error_ must be raised. If no runtime value is
+  provided, the variable definition's default value should be used. If the
+  variable definition does not provide a default value, the input object field
+  definition's default value should be used.
 
 Following are examples of input coercion for an input object type with a
 `String` field `a` and a required (non-null) `Int!` field `b`:
@@ -1742,19 +1744,19 @@ brackets like this: `pets: [Pet]`. Nesting lists is allowed: `matrix: [[Int]]`.
 
 GraphQL services must return an ordered list as the result of a list type. Each
 item in the list must be the result of a result coercion of the item type. If a
-reasonable coercion is not possible it must raise a _field error_. In
+reasonable coercion is not possible it must raise an _execution error_. In
 particular, if a non-list is returned, the coercion should fail, as this
 indicates a mismatch in expectations between the type system and the
 implementation.
 
 If a list's item type is nullable, then errors occurring during preparation or
 coercion of an individual item in the list must result in a the value {null} at
-that position in the list along with a _field error_ added to the response. If a
-list's item type is non-null, a field error occurring at an individual item in
-the list must result in a field error for the entire list.
+that position in the list along with an _execution error_ added to the response.
+If a list's item type is non-null, an execution error occurring at an individual
+item in the list must result in an execution error for the entire list.
 
-Note: See [Handling Field Errors](#sec-Handling-Field-Errors) for more about
-this behavior.
+Note: See [Handling Execution Errors](#sec-Handling-Execution-Errors) for more
+about this behavior.
 
 **Input Coercion**
 
@@ -1812,12 +1814,13 @@ always optional and non-null types are always required.
 In all of the above result coercions, {null} was considered a valid value. To
 coerce the result of a Non-Null type, the coercion of the wrapped type should be
 performed. If that result was not {null}, then the result of coercing the
-Non-Null type is that result. If that result was {null}, then a _field error_
-must be raised.
+Non-Null type is that result. If that result was {null}, then an _execution
+error_ must be raised.
 
-Note: When a _field error_ is raised on a non-null value, the error propagates
-to the parent field. For more information on this process, see
-[Errors and Non-Null Fields](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields)
+Note: When an _execution error_ is raised on a non-null _response position_, the
+error propagates to the parent _response position_. For more information on this
+process, see
+[Errors and Non-Null Types](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Types)
 within the Execution section.
 
 **Input Coercion**
@@ -2035,19 +2038,20 @@ directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION
 Note: The order in which directives appear may be significant, including
 repeatable directives.
 
-**Validation**
+**Type Validation**
 
-1. A directive definition must not contain the use of a directive which
+1. A Directive definition must include at least one DirectiveLocation.
+2. A Directive definition must not contain the use of a Directive which
    references itself directly.
-2. A directive definition must not contain the use of a directive which
+3. A Directive definition must not contain the use of a Directive which
    references itself indirectly by referencing a Type or Directive which
-   transitively includes a reference to this directive.
-3. The directive must not have a name which begins with the characters {"\_\_"}
+   transitively includes a reference to this Directive.
+4. The Directive must not have a name which begins with the characters {"\_\_"}
    (two underscores).
-4. For each argument of the directive:
+5. For each argument of the Directive:
    1. The argument must not have a name which begins with the characters
       {"\_\_"} (two underscores).
-   2. The argument must have a unique name within that directive; no two
+   2. The argument must have a unique name within that Directive; no two
       arguments may share the same name.
    3. The argument must accept a type where {IsInputType(argumentType)} returns
       {true}.

spec/Section 3 -- Type System.md

@@ -138,15 +138,15 @@ type __Type {
   name: String
   description: String
   # must be non-null for OBJECT and INTERFACE, otherwise null.
-  fields(includeDeprecated: Boolean = false): [__Field!]
+  fields(includeDeprecated: Boolean! = false): [__Field!]
   # must be non-null for OBJECT and INTERFACE, otherwise null.
   interfaces: [__Type!]
   # must be non-null for INTERFACE and UNION, otherwise null.
   possibleTypes: [__Type!]
   # must be non-null for ENUM, otherwise null.
-  enumValues(includeDeprecated: Boolean = false): [__EnumValue!]
+  enumValues(includeDeprecated: Boolean! = false): [__EnumValue!]
   # must be non-null for INPUT_OBJECT, otherwise null.
-  inputFields(includeDeprecated: Boolean = false): [__InputValue!]
+  inputFields(includeDeprecated: Boolean! = false): [__InputValue!]
   # must be non-null for NON_NULL and LIST, otherwise null.
   ofType: __Type
   # may be non-null for custom SCALAR, otherwise null.
@@ -167,7 +167,7 @@ enum __TypeKind {
 type __Field {
   name: String!
   description: String
-  args(includeDeprecated: Boolean = false): [__InputValue!]!
+  args(includeDeprecated: Boolean! = false): [__InputValue!]!
   type: __Type!
   isDeprecated: Boolean!
   deprecationReason: String
@@ -193,7 +193,7 @@ type __Directive {
   name: String!
   description: String
   locations: [__DirectiveLocation!]!
-  args(includeDeprecated: Boolean = false): [__InputValue!]!
+  args(includeDeprecated: Boolean! = false): [__InputValue!]!
   isRepeatable: Boolean!
 }