From 31c90e7216d49b3f0bbf697c9630edc21369bb53 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Wed, 30 Apr 2025 11:46:08 +0100 Subject: [PATCH 01/15] Detail onError request parameter --- spec/Section 6 -- Execution.md | 104 ++++++++++++++++++++++++++------- 1 file changed, 83 insertions(+), 21 deletions(-) diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index f3e080705..743da0061 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -4,6 +4,8 @@ A GraphQL service generates a response from a request via execution. :: A _request_ for execution consists of a few pieces of information: + + - {schema}: The schema to use, typically solely provided by the GraphQL service. - {document}: A {Document} which must contain GraphQL {OperationDefinition} and may contain {FragmentDefinition}. @@ -15,6 +17,10 @@ A GraphQL service generates a response from a request via execution. being executed. Conceptually, an initial value represents the "universe" of data available via a GraphQL Service. It is common for a GraphQL Service to always use the same initial value for every request. +- {onError} (optional): The _error behavior_ to apply to the request; see + [Handling Execution Errors](#sec-Handling-Execution-Errors). If {onError} is + provided and its value is not one of {"PROPAGATE"}, {"NO_PROPAGATE"}, or + {"ABORT"}, then a _request error_ must be raised. - {extensions} (optional): A map reserved for implementation-specific additional information. @@ -22,6 +28,12 @@ Given this information, the result of {ExecuteRequest(schema, document, operationName, variableValues, initialValue)} produces the response, to be formatted according to the Response section below. +Note: Previous versions of this specification did not define the {onError} +request attribute. Clients can detect support for {onError} by checking for the +presence of the `defaultErrorBehavior` field on the `__Schema` introspection +type. If this field is absent, clients should not include {onError} in the +request and must assume the _error behavior_ is {"PROPAGATE"}. + Implementations should not add additional properties to a _request_, which may conflict with future editions of the GraphQL specification. Instead, {extensions} provides a reserved location for implementation-specific additional @@ -392,13 +404,24 @@ is explained in greater detail in the Field Collection section below. If during {ExecuteSelectionSet()} a _response position_ with a non-null type -raises an _execution error_ then that error must propagate to the parent -response position (the entire selection set in the case of a field, or the -entire list in the case of a list position), either resolving to {null} if -allowed or being further propagated to a parent response position. - -If this occurs, any sibling response positions which have not yet executed or -have not yet yielded a value may be cancelled to avoid unnecessary work. +raises an _execution error_, the error must be added to the {"errors"} list in +the _response_ and then handled according to the _error behavior_ of the +request: + + + +- {"NO\_PROPAGATE"}: The _response position_ must be set to {null}. (The client + is responsible for interpreting this {null} in conjunction with the {"errors"} + list to distinguish error results from intentional {null} values.) +- {"PROPAGATE"}: The _execution error_ must propagate to the parent _response + position_ (the entire selection set in the case of a field, or the entire list + in the case of a list position). The parent position resolves to {null} if + allowed, or else the error is further propagated to a parent response + position. Any sibling response positions that have not yet executed or have + not yet yielded a value may be cancelled to avoid unnecessary work. +- {"ABORT"}: The entire _request_ must be aborted. The {"data"} entry in the + _response_ must be {null}. Any _response position_ that has not yet executed + or has not yet yielded a value may be cancelled to avoid unnecessary work. Note: See [Handling Execution Errors](#sec-Handling-Execution-Errors) for more about this behavior. @@ -823,28 +846,61 @@ MergeSelectionSets(fields): An _execution error_ is an error raised during field execution, value resolution -or coercion, at a specific _response position_. While these errors must be -reported in the response, they are "handled" by producing partial {"data"} in -the _response_. +or coercion, at a specific _response position_. These errors must be added to +the {"errors"} list in the _response_, and are "handled" according to the _error +behavior_ of the request. + +Note: An _execution error_ is distinct from a _request error_ which results in a +response with no {"data"}. + +If a _response position_ resolves to {null} because of an execution error which +has already been added to the {"errors"} list in the response, the {"errors"} +list must not be further affected. That is, only one error should be added to +the errors list per _response position_. + +:: The _error behavior_ of a request indicates how an _execution error_ is +handled. It may be specified using the optional {onError} attribute of the +_request_. If omitted, the _default error behavior_ of the schema applies. Valid +values for _error behavior_ are {"PROPAGATE"}, {"NO_PROPAGATE"} and {"ABORT"}. + +:: The _default error behavior_ of a schema is implementation-defined. For +compatibility with existing clients, schemas should default to {"PROPAGATE"} +which reflects prior behavior. For new schemas, {"NO_PROPAGATE"} is recommended. +The default error behavior is indicated via the `defaultErrorBehavior` field of +the `__Schema` introspection type, or via the `@behavior` schema directive. + +Note: {"ABORT"} is not recommended as the _default error behavior_ because it +prevents generating partial responses which may still contain useful data. + +Regardless of error behavior, if a _response position_ with a non-null type +results in {null} due to the result of {ResolveFieldValue()} then an execution +error must be raised at that position as specified in {CompleteValue()}. -Note: This is distinct from a _request error_ which results in a response with -no data. +The _error behavior_ of a request applies to every _execution error_ raised +during execution. The following sections describe the behavior of each valid +value: -If an execution error is raised while resolving a field (either directly or -nested inside any lists), it is handled as though the _response position_ at -which the error occurred resolved to {null}, and the error must be added to the -{"errors"} list in the response. +**{"NO_PROPAGATE"}** + + + +With {"NO\_PROPAGATE"}, a `Non-Null` _response position_ will have the value +{null} if and only if an error occurred at that position. + +Note: Clients must inspect the {"errors"} list and use the {"path"} of each +error result to distinguish between intentional {null} values and those +resulting from an _execution error_. + +**{"PROPAGATE"}** + +With {"PROPAGATE"}, a `Non-Null` _response position_ must not contain {null} in +the _response_. If the result of resolving a _response position_ is {null} (either due to the result of {ResolveFieldValue()} or because an execution error was raised), and that position is of a `Non-Null` type, then an execution error is raised at that position. The error must be added to the {"errors"} list in the response. -If a _response position_ resolves to {null} because of an execution error which -has already been added to the {"errors"} list in the response, the {"errors"} -list must not be further affected. That is, only one error should be added to -the errors list per _response position_. - Since `Non-Null` response positions cannot be {null}, execution errors are propagated to be handled by the parent _response position_. If the parent response position may be {null} then it resolves to {null}, otherwise if it is a @@ -859,3 +915,9 @@ position_ must resolve to {null}. If the `List` type is also wrapped in a If every _response position_ from the root of the request to the source of the execution error has a `Non-Null` type, then the {"data"} entry in the response should be {null}. + +**{"ABORT"}** + +With {"ABORT"}, execution must cease immediately when the first _execution +error_ is raised. That error must be added to the {"errors"} list, and {"data"} +must be {null}. From f4fab967d1040b8ea28e583f428cd280f7197047 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Wed, 30 Apr 2025 11:59:12 +0100 Subject: [PATCH 02/15] Detail introspection changes --- spec/Section 4 -- Introspection.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index b260559cb..a60184ba6 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -131,6 +131,7 @@ type __Schema { mutationType: __Type subscriptionType: __Type directives: [__Directive!]! + defaultErrorBehavior: __ErrorBehavior! } type __Type { @@ -164,6 +165,12 @@ enum __TypeKind { NON_NULL } +enum __ErrorBehavior { + NO_PROPAGATE + PROPAGATE + ABORT +} + type __Field { name: String! description: String @@ -238,6 +245,11 @@ Fields\: must be included in this set. - `directives` must return the set of all directives available within this schema including all built-in directives. +- `defaultErrorBehavior` must return the _default error behavior_ of the schema + using one of the values of the `__ErrorBehavior` enum: + - {"NO_PROPAGATE"} + - {"PROPAGATE"} + - {"ABORT"} ### The \_\_Type Type From 692d811fa7895108af0c959d473e056b327ebab5 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Wed, 30 Apr 2025 12:19:47 +0100 Subject: [PATCH 03/15] Define the directive --- spec/Section 3 -- Type System.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 47d3efb3d..81d377cf3 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2167,3 +2167,27 @@ to the relevant IETF specification. ```graphql example scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") ``` + +### @behavior + +```graphql +directive @behavior(onError: __ErrorBehavior! = PROPAGATE) on SCHEMA +``` + +The `@behavior` _built-in directive_ is used within the type system definition +language to indicate the _default error behavior_ of a GraphQL schema. It may be +omitted only if the _default error behavior_ is {"PROPAGATE"}. + +Note: See [Handling Execution Errors](#sec-Handling-Execution-Errors) for more +information on _error behavior_. + + + +In this example, the schema indicates it is using the {"NO\_PROPAGATE"} _default +error behavior_: + +```graphql example +schema @behavior(onError: NO_PROPAGATE) { + query: Query +} +``` From 94446abd36edde953c33e388d06a00d43a3f03d5 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 15 May 2025 13:27:55 +0100 Subject: [PATCH 04/15] ABORT -> HALT GraphQLConf requires speakers to be familiar with "inclusive naming", and the inclusive naming guides encourage the avoidance of the word "abort" where possible: https://inclusivenaming.org/word-lists/tier-1/abort/ --- spec/Section 4 -- Introspection.md | 4 ++-- spec/Section 6 -- Execution.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index a60184ba6..18aabae95 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -168,7 +168,7 @@ enum __TypeKind { enum __ErrorBehavior { NO_PROPAGATE PROPAGATE - ABORT + HALT } type __Field { @@ -249,7 +249,7 @@ Fields\: using one of the values of the `__ErrorBehavior` enum: - {"NO_PROPAGATE"} - {"PROPAGATE"} - - {"ABORT"} + - {"HALT"} ### The \_\_Type Type diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 743da0061..ae0c0a47a 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -20,7 +20,7 @@ A GraphQL service generates a response from a request via execution. - {onError} (optional): The _error behavior_ to apply to the request; see [Handling Execution Errors](#sec-Handling-Execution-Errors). If {onError} is provided and its value is not one of {"PROPAGATE"}, {"NO_PROPAGATE"}, or - {"ABORT"}, then a _request error_ must be raised. + {"HALT"}, then a _request error_ must be raised. - {extensions} (optional): A map reserved for implementation-specific additional information. @@ -419,7 +419,7 @@ request: allowed, or else the error is further propagated to a parent response position. Any sibling response positions that have not yet executed or have not yet yielded a value may be cancelled to avoid unnecessary work. -- {"ABORT"}: The entire _request_ must be aborted. The {"data"} entry in the +- {"HALT"}: The entire _request_ must be cancelled. The {"data"} entry in the _response_ must be {null}. Any _response position_ that has not yet executed or has not yet yielded a value may be cancelled to avoid unnecessary work. @@ -861,7 +861,7 @@ the errors list per _response position_. :: The _error behavior_ of a request indicates how an _execution error_ is handled. It may be specified using the optional {onError} attribute of the _request_. If omitted, the _default error behavior_ of the schema applies. Valid -values for _error behavior_ are {"PROPAGATE"}, {"NO_PROPAGATE"} and {"ABORT"}. +values for _error behavior_ are {"PROPAGATE"}, {"NO_PROPAGATE"} and {"HALT"}. :: The _default error behavior_ of a schema is implementation-defined. For compatibility with existing clients, schemas should default to {"PROPAGATE"} @@ -869,7 +869,7 @@ which reflects prior behavior. For new schemas, {"NO_PROPAGATE"} is recommended. The default error behavior is indicated via the `defaultErrorBehavior` field of the `__Schema` introspection type, or via the `@behavior` schema directive. -Note: {"ABORT"} is not recommended as the _default error behavior_ because it +Note: {"HALT"} is not recommended as the _default error behavior_ because it prevents generating partial responses which may still contain useful data. Regardless of error behavior, if a _response position_ with a non-null type @@ -916,8 +916,8 @@ If every _response position_ from the root of the request to the source of the execution error has a `Non-Null` type, then the {"data"} entry in the response should be {null}. -**{"ABORT"}** +**{"HALT"}** -With {"ABORT"}, execution must cease immediately when the first _execution -error_ is raised. That error must be added to the {"errors"} list, and {"data"} -must be {null}. +With {"HALT"}, execution must cease immediately when the first _execution error_ +is raised. That error must be added to the {"errors"} list, and {"data"} must be +{null}. From 3c633556b4d60e7b61a6945a3438d2f043878ef9 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 15 May 2025 15:22:34 +0100 Subject: [PATCH 05/15] Start speccing out the capabilities system --- spec/Section 4 -- Introspection.md | 89 +++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 3 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 18aabae95..bd495570e 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -85,11 +85,12 @@ operation. ## Schema Introspection -The schema introspection system is accessible from the meta-fields `__schema` -and `__type` which are accessible from the type of the root of a query -operation. +The schema introspection system is accessible from the meta-fields `__service`, +`__schema` and `__type` which are accessible from the type of the root of a +query operation. ```graphql +__service: __Service! __schema: __Schema! __type(name: String!): __Type ``` @@ -124,6 +125,10 @@ are the full set of type system definitions providing schema introspection, which are fully defined in the sections below. ```graphql +type __Service { + capabilities: [String!]! +} + type __Schema { description: String types: [__Type!]! @@ -227,6 +232,84 @@ enum __DirectiveLocation { } ``` +### The \_\_Service Type + +The `__Service` type is returned from the `__service` meta-field and provides +information about the GraphQL service, most notably about its capabilities. This +type was added after the original release of GraphQL, so older schemas may not +support it. + +Fields\: + +- `capabilities` returns a list of strings indicating the capabilities supported + by the service. + +**Capabilities** + +As GraphQL becomes more feature rich, clients need to understand the features +that a service supports so that they only send compatible requests; the +`__Service.capabilities` field reveals these capabilities. + +Note: Prior to the introduction of the capabilities system, a client would +either require out-of-band communication to discover the capabilities of a +schema, or would need to perform multiple introspection phases determining the +fields available in introspection in order to perform feature discovery. + +Capabilities may be supplied by the GraphQL implementation, by the service, or +both. + +A individual capability is described by a string, {CapabilityString}, inspired +by reverse domain name notation to ensure globally unique and +collision-resistant identifiers. A capability string must be composed of two or +more {CompatibilitySegment}, separated by a period (`.`). A {CapabilitySegment} +is a non-empty string composed only from ASCII letter (`[a-zA-Z]`), digits +(`[0-9]`), or hyphens (`-`); it must start with an ASCII letter and must not +terminate with a hyphen. + +CapabilityString :: + +- CapabilityString . CapabilitySegment +- CapabilitySegment . CapabilitySegment + +CapabilitySegment :: + +- CapabilitySegmentStart +- CapabilitySegmentStart CapabilitySegmentContinue\* CapabilitySegmentEnd + +CapabilitySegmentStart :: Letter + +CapabilitySegmentContinue :: + +- Letter +- Digit +- `-` + +CapabilitySegmentEnd :: + +- Letter +- Digit + +Identifiers beginning with the prefix `org.graphql.` are reserved and must not +be used outside of official GraphQL Foundation specifications. Further, +identifiers beginning with the prefix `org.graphql.http.` are reserved for use +by the GraphQL-over-HTTP specification, and identifiers beginning with the +prefix `org.graphql.rfc.` are reserved for RFC proposals. + +Identifiers defined by specific projects, vendors, or implementations should +begin with a prefix derived from a DNS name they control (e.g., `com.example.`) + +Clients should use string equality to check for known identifiers, and should +ignore unknown identifiers. + +Implementers should not change the meaning of capability identifiers, instead a +new capability identifier should be used when the meaning changes. Implementers +should ensure that capability strings remain stable and version-agnostic where +possible; capability versioning, if needed, can be indicated using dot suffixes +(e.g. `org.example.capability.v2`). + +This system enables incremental feature adoption and richer tooling +interoperability, while avoiding tight coupling to specific implementations. + ### The \_\_Schema Type The `__Schema` type is returned from the `__schema` meta-field and provides all From 7056690be839020447178f1969e6bf9682109be2 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 15 May 2025 17:28:31 +0100 Subject: [PATCH 06/15] Add a number of basic capabilities --- spec/Section 4 -- Introspection.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index bd495570e..53746e421 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -310,6 +310,31 @@ possible; capability versioning, if needed, can be indicated using dot suffixes This system enables incremental feature adoption and richer tooling interoperability, while avoiding tight coupling to specific implementations. +Implementers of earlier versions of this specification may choose to implement +the capabilities system, but when doing so they must not include capabilities +that they do not support. + +Implementers of this version of this specification must include the following +capabilities: + +- `org.graphql.scalar.specifiedBy` - indicates the ability to request the + _scalar specification URL_ of a scalar via the `__Type.specifiedBy` + introspection field +- `org.graphql.directive.repeatable` - indicates support for repeatable + directive and the related `__Directive.isRepeatable` introspection field +- `org.graphql.schema.description` - indicates the ability to request a + description of the schema via the `__Schema.description` introspection field +- `org.graphql.deprecation.inputValues` - indicates support for deprecating + input values along with the related introspection schema coordinates: + `__Directive.args(includeDeprecated:)`, `__Field.args(includeDeprecated:)`, + `__Type.inputFields(includeDeprecated:)`, `__InputValue.isDeprecated` and + `__InputValue.deprecationReason` +- `org.graphql.inputObject.oneOf` - indicates support for OneOf Input Objects + and the related introspection field `__Type.isOneOf` + +If the schema, implementation, and service support the subscription operation, +the `org.graphql.subscription` capability should be included. + ### The \_\_Schema Type The `__Schema` type is returned from the `__schema` meta-field and provides all From 0fa7a33f3e004730a98d2924b9f67a49ca9e8b46 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 15 May 2025 18:17:21 +0100 Subject: [PATCH 07/15] Move default error behavior to the service --- spec/Section 3 -- Type System.md | 24 ------------- spec/Section 4 -- Introspection.md | 54 ++++++++++++++++++------------ spec/Section 6 -- Execution.md | 24 +++++++------ 3 files changed, 45 insertions(+), 57 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 81d377cf3..47d3efb3d 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2167,27 +2167,3 @@ to the relevant IETF specification. ```graphql example scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") ``` - -### @behavior - -```graphql -directive @behavior(onError: __ErrorBehavior! = PROPAGATE) on SCHEMA -``` - -The `@behavior` _built-in directive_ is used within the type system definition -language to indicate the _default error behavior_ of a GraphQL schema. It may be -omitted only if the _default error behavior_ is {"PROPAGATE"}. - -Note: See [Handling Execution Errors](#sec-Handling-Execution-Errors) for more -information on _error behavior_. - - - -In this example, the schema indicates it is using the {"NO\_PROPAGATE"} _default -error behavior_: - -```graphql example -schema @behavior(onError: NO_PROPAGATE) { - query: Query -} -``` diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 53746e421..7ded25024 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -127,6 +127,7 @@ which are fully defined in the sections below. ```graphql type __Service { capabilities: [String!]! + defaultErrorBehavior: __ErrorBehavior! } type __Schema { @@ -136,7 +137,6 @@ type __Schema { mutationType: __Type subscriptionType: __Type directives: [__Directive!]! - defaultErrorBehavior: __ErrorBehavior! } type __Type { @@ -241,8 +241,13 @@ support it. Fields\: -- `capabilities` returns a list of strings indicating the capabilities supported - by the service. +- `capabilities` must return a list of strings indicating the capabilities + supported by the service. +- `defaultErrorBehavior` must return the _default error behavior_ of the service + using one of the values of the `__ErrorBehavior` enum: + - {"NO_PROPAGATE"} + - {"PROPAGATE"} + - {"HALT"} **Capabilities** @@ -289,14 +294,15 @@ CapabilitySegmentEnd :: - Letter - Digit -Identifiers beginning with the prefix `org.graphql.` are reserved and must not +Identifiers beginning with the prefix {"org.graphql."} are reserved and must not be used outside of official GraphQL Foundation specifications. Further, -identifiers beginning with the prefix `org.graphql.http.` are reserved for use +identifiers beginning with the prefix {"org.graphql.http."} are reserved for use by the GraphQL-over-HTTP specification, and identifiers beginning with the -prefix `org.graphql.rfc.` are reserved for RFC proposals. +prefix {"org.graphql.rfc."} are reserved for RFC proposals. Identifiers defined by specific projects, vendors, or implementations should -begin with a prefix derived from a DNS name they control (e.g., `com.example.`) +begin with a prefix derived from a DNS name they control (e.g., +{"com.example."}) Clients should use string equality to check for known identifiers, and should ignore unknown identifiers. @@ -305,7 +311,7 @@ Implementers should not change the meaning of capability identifiers, instead a new capability identifier should be used when the meaning changes. Implementers should ensure that capability strings remain stable and version-agnostic where possible; capability versioning, if needed, can be indicated using dot suffixes -(e.g. `org.example.capability.v2`). +(e.g.{ "org.example.capability.v2"}). This system enables incremental feature adoption and richer tooling interoperability, while avoiding tight coupling to specific implementations. @@ -317,23 +323,32 @@ that they do not support. Implementers of this version of this specification must include the following capabilities: -- `org.graphql.scalar.specifiedBy` - indicates the ability to request the +- {"org.graphql.scalar.specifiedBy"} - indicates the ability to request the _scalar specification URL_ of a scalar via the `__Type.specifiedBy` introspection field -- `org.graphql.directive.repeatable` - indicates support for repeatable +- {"org.graphql.directive.repeatable"} - indicates support for repeatable directive and the related `__Directive.isRepeatable` introspection field -- `org.graphql.schema.description` - indicates the ability to request a +- {"org.graphql.schema.description"} - indicates the ability to request a description of the schema via the `__Schema.description` introspection field -- `org.graphql.deprecation.inputValues` - indicates support for deprecating +- {"org.graphql.deprecation.inputValues"} - indicates support for deprecating input values along with the related introspection schema coordinates: - `__Directive.args(includeDeprecated:)`, `__Field.args(includeDeprecated:)`, - `__Type.inputFields(includeDeprecated:)`, `__InputValue.isDeprecated` and - `__InputValue.deprecationReason` -- `org.graphql.inputObject.oneOf` - indicates support for OneOf Input Objects + - `__Directive.args(includeDeprecated:)`, + - `__Field.args(includeDeprecated:)`, + - `__Type.inputFields(includeDeprecated:)`, + - `__InputValue.isDeprecated`, and + - `__InputValue.deprecationReason`. +- {"org.graphql.inputObject.oneOf"} - indicates support for OneOf Input Objects and the related introspection field `__Type.isOneOf` +- {"org.graphql.errorBehavior"} - indicates that the + `__Service.defaultErrorBehavior` field exists, which indicates the the + _default error behavior_ of the service If the schema, implementation, and service support the subscription operation, -the `org.graphql.subscription` capability should be included. +the {"org.graphql.subscription"} capability should be included. + +If the service accepts the {onError} request parameter, the +{"org.graphql.onError"} capability should be included. If it is not included, +clients should infer the default will be used for all requests. ### The \_\_Schema Type @@ -353,11 +368,6 @@ Fields\: must be included in this set. - `directives` must return the set of all directives available within this schema including all built-in directives. -- `defaultErrorBehavior` must return the _default error behavior_ of the schema - using one of the values of the `__ErrorBehavior` enum: - - {"NO_PROPAGATE"} - - {"PROPAGATE"} - - {"HALT"} ### The \_\_Type Type diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index ae0c0a47a..8419eb789 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -30,9 +30,10 @@ formatted according to the Response section below. Note: Previous versions of this specification did not define the {onError} request attribute. Clients can detect support for {onError} by checking for the -presence of the `defaultErrorBehavior` field on the `__Schema` introspection -type. If this field is absent, clients should not include {onError} in the -request and must assume the _error behavior_ is {"PROPAGATE"}. +{"org.graphql.onError"} capability. If this capability is not present, or if +capabilities themselves are not supported by introspection, then clients should +not include {onError} in the request and must assume the _error behavior_ is +{"PROPAGATE"}. Implementations should not add additional properties to a _request_, which may conflict with future editions of the GraphQL specification. Instead, @@ -860,14 +861,15 @@ the errors list per _response position_. :: The _error behavior_ of a request indicates how an _execution error_ is handled. It may be specified using the optional {onError} attribute of the -_request_. If omitted, the _default error behavior_ of the schema applies. Valid -values for _error behavior_ are {"PROPAGATE"}, {"NO_PROPAGATE"} and {"HALT"}. - -:: The _default error behavior_ of a schema is implementation-defined. For -compatibility with existing clients, schemas should default to {"PROPAGATE"} -which reflects prior behavior. For new schemas, {"NO_PROPAGATE"} is recommended. -The default error behavior is indicated via the `defaultErrorBehavior` field of -the `__Schema` introspection type, or via the `@behavior` schema directive. +_request_. If omitted, the _default error behavior_ of the service applies. +Valid values for _error behavior_ are {"PROPAGATE"}, {"NO_PROPAGATE"} and +{"HALT"}. + +:: The _default error behavior_ of a service is implementation-defined. For +compatibility with existing clients, services should default to {"PROPAGATE"} +which reflects prior behavior. For new services, {"NO_PROPAGATE"} is +recommended. The default error behavior is indicated via the +`defaultErrorBehavior` field of the `__Service` introspection type. Note: {"HALT"} is not recommended as the _default error behavior_ because it prevents generating partial responses which may still contain useful data. From 1f975e465405c0c6b638847eb9c83d51da945499 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 22 May 2025 19:41:00 +0100 Subject: [PATCH 08/15] Rework capabilities --- spec/Section 4 -- Introspection.md | 212 ++++++++++++----------------- 1 file changed, 84 insertions(+), 128 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 7ded25024..a2f39bd0e 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -125,11 +125,6 @@ are the full set of type system definitions providing schema introspection, which are fully defined in the sections below. ```graphql -type __Service { - capabilities: [String!]! - defaultErrorBehavior: __ErrorBehavior! -} - type __Schema { description: String types: [__Type!]! @@ -170,12 +165,6 @@ enum __TypeKind { NON_NULL } -enum __ErrorBehavior { - NO_PROPAGATE - PROPAGATE - HALT -} - type __Field { name: String! description: String @@ -230,125 +219,16 @@ enum __DirectiveLocation { INPUT_OBJECT INPUT_FIELD_DEFINITION } -``` - -### The \_\_Service Type - -The `__Service` type is returned from the `__service` meta-field and provides -information about the GraphQL service, most notably about its capabilities. This -type was added after the original release of GraphQL, so older schemas may not -support it. - -Fields\: - -- `capabilities` must return a list of strings indicating the capabilities - supported by the service. -- `defaultErrorBehavior` must return the _default error behavior_ of the service - using one of the values of the `__ErrorBehavior` enum: - - {"NO_PROPAGATE"} - - {"PROPAGATE"} - - {"HALT"} - -**Capabilities** - -As GraphQL becomes more feature rich, clients need to understand the features -that a service supports so that they only send compatible requests; the -`__Service.capabilities` field reveals these capabilities. - -Note: Prior to the introduction of the capabilities system, a client would -either require out-of-band communication to discover the capabilities of a -schema, or would need to perform multiple introspection phases determining the -fields available in introspection in order to perform feature discovery. - -Capabilities may be supplied by the GraphQL implementation, by the service, or -both. - -A individual capability is described by a string, {CapabilityString}, inspired -by reverse domain name notation to ensure globally unique and -collision-resistant identifiers. A capability string must be composed of two or -more {CompatibilitySegment}, separated by a period (`.`). A {CapabilitySegment} -is a non-empty string composed only from ASCII letter (`[a-zA-Z]`), digits -(`[0-9]`), or hyphens (`-`); it must start with an ASCII letter and must not -terminate with a hyphen. - -CapabilityString :: - -- CapabilityString . CapabilitySegment -- CapabilitySegment . CapabilitySegment - -CapabilitySegment :: - -- CapabilitySegmentStart -- CapabilitySegmentStart CapabilitySegmentContinue\* CapabilitySegmentEnd - -CapabilitySegmentStart :: Letter - -CapabilitySegmentContinue :: - -- Letter -- Digit -- `-` - -CapabilitySegmentEnd :: - -- Letter -- Digit - -Identifiers beginning with the prefix {"org.graphql."} are reserved and must not -be used outside of official GraphQL Foundation specifications. Further, -identifiers beginning with the prefix {"org.graphql.http."} are reserved for use -by the GraphQL-over-HTTP specification, and identifiers beginning with the -prefix {"org.graphql.rfc."} are reserved for RFC proposals. - -Identifiers defined by specific projects, vendors, or implementations should -begin with a prefix derived from a DNS name they control (e.g., -{"com.example."}) - -Clients should use string equality to check for known identifiers, and should -ignore unknown identifiers. - -Implementers should not change the meaning of capability identifiers, instead a -new capability identifier should be used when the meaning changes. Implementers -should ensure that capability strings remain stable and version-agnostic where -possible; capability versioning, if needed, can be indicated using dot suffixes -(e.g.{ "org.example.capability.v2"}). -This system enables incremental feature adoption and richer tooling -interoperability, while avoiding tight coupling to specific implementations. +type __Service { + capabilities: [__Capability!]! +} -Implementers of earlier versions of this specification may choose to implement -the capabilities system, but when doing so they must not include capabilities -that they do not support. - -Implementers of this version of this specification must include the following -capabilities: - -- {"org.graphql.scalar.specifiedBy"} - indicates the ability to request the - _scalar specification URL_ of a scalar via the `__Type.specifiedBy` - introspection field -- {"org.graphql.directive.repeatable"} - indicates support for repeatable - directive and the related `__Directive.isRepeatable` introspection field -- {"org.graphql.schema.description"} - indicates the ability to request a - description of the schema via the `__Schema.description` introspection field -- {"org.graphql.deprecation.inputValues"} - indicates support for deprecating - input values along with the related introspection schema coordinates: - - `__Directive.args(includeDeprecated:)`, - - `__Field.args(includeDeprecated:)`, - - `__Type.inputFields(includeDeprecated:)`, - - `__InputValue.isDeprecated`, and - - `__InputValue.deprecationReason`. -- {"org.graphql.inputObject.oneOf"} - indicates support for OneOf Input Objects - and the related introspection field `__Type.isOneOf` -- {"org.graphql.errorBehavior"} - indicates that the - `__Service.defaultErrorBehavior` field exists, which indicates the the - _default error behavior_ of the service - -If the schema, implementation, and service support the subscription operation, -the {"org.graphql.subscription"} capability should be included. - -If the service accepts the {onError} request parameter, the -{"org.graphql.onError"} capability should be included. If it is not included, -clients should infer the default will be used for all requests. +type __Capability { + identifier: String! + value: String +} +``` ### The \_\_Schema Type @@ -630,3 +510,79 @@ Fields\: {true}, deprecated arguments are also returned. - `isRepeatable` must return a Boolean that indicates if the directive may be used repeatedly at a single location. + +### The \_\_Service Type + +The `__Service` type is returned from the `__service` meta-field and provides +information about the GraphQL service, most notably about its capabilities. This +type was added after the original release of GraphQL, so older schemas may not +support it. + +Fields\: + +- `capabilities` must return a list of `__Capability` indicating the + capabilities supported by the service. + +### The \_\_Capability Type + +The `__Service.capabilities` field exposes a list of capabilities that describe +features supported by the GraphQL service but not directly expressible in the +type system. These may include experimental GraphQL features (such as fragment +arguments, operation descriptions, custom error behaviors), protocol support +(such as subscriptions over WebSocket), or additional operational metadata (such +as release identifiers). + +Capabilities may be supplied by the GraphQL implementation, by the service, or +both. An individual entry in the capabilities list will have a capability +identifier and may optionally provide a string value. + +**Capability identifier** + +Capability identifiers are inspired by reverse domain name notation in order to +help them be globally unique and collision-resistant. They are a string value +composed of two or more segments separated by a period (`.`). Each segment must +begin with a letter and must contain only alphanumeric characters and hyphens +(`[a-zA-Z][a-zA-Z0-9-]*`). Unlike the domain name system, capability identifiers +are case sensitive. Identifiers beginning with the prefix {"org.graphql."} are +reserved and must not be used outside of official GraphQL Foundation +specifications. Further, identifiers beginning with the prefix +{"org.graphql.http."} are reserved for use by the GraphQL-over-HTTP +specification, and identifiers beginning with the prefix {"org.graphql.rfc."} +are reserved for RFC proposals. + +Identifiers defined by specific projects, vendors, or implementations should +begin with a prefix derived from a DNS name they control (e.g., +{"com.example."}). + +Clients should use string equality to check for known identifiers, and should +ignore unknown identifiers. + +Implementers should not change the meaning of capability identifiers, instead a +new capability identifier should be used when the meaning changes. Implementers +should ensure that capability strings remain stable and version-agnostic where +possible; capability versioning, if needed, can be indicated using dot suffixes +(e.g.{ "org.example.capability.v2"}). + +This system enables incremental feature adoption and richer tooling +interoperability, while avoiding tight coupling to specific implementations. + +**Capability value** + +The value assigned to a given capability may either be {null} to indicate that +the capability is supported and requires no additional information, or a string +to provide additional information. For example +{"org.graphql.rfc.fragmentArguments"} does not require additional information +and thus would have value {null}, whereas {"org.graphql.websockets"} might +indicate support for websockets whilst using the value to indicate the endpoint +to use. + +**Specified capabilities** + +This version of the specification defines the following capabilities: + +- {"org.graphql.defaultErrorBehavior"} - indicates the _default error behavior_ + of the service via the {value}. If not present, must be assumed to be + {"PROPAGATE"}. +- {"org.graphql.onError"} - indicates that the service allows the client to + specify {onError} in a request to indicate the _error behavior_ the service + should use for the request. {value} is {null}. From 8c4008671a324e8769083e596c97d997782ea743 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 22 May 2025 19:46:06 +0100 Subject: [PATCH 09/15] Use a definition --- spec/Section 4 -- Introspection.md | 19 +++++++++---------- spec/Section 6 -- Execution.md | 8 +++++--- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index a2f39bd0e..03e89866d 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -525,16 +525,15 @@ Fields\: ### The \_\_Capability Type -The `__Service.capabilities` field exposes a list of capabilities that describe -features supported by the GraphQL service but not directly expressible in the -type system. These may include experimental GraphQL features (such as fragment -arguments, operation descriptions, custom error behaviors), protocol support -(such as subscriptions over WebSocket), or additional operational metadata (such -as release identifiers). - -Capabilities may be supplied by the GraphQL implementation, by the service, or -both. An individual entry in the capabilities list will have a capability -identifier and may optionally provide a string value. +:: A _capability_ describes a feature supported by the GraphQL service but not +directly expressible in the type system. This may include experimental GraphQL +features (such as new syntax or behavior), protocol support (such as GraphQL +over WebSockets), or additional operational metadata (such as release +identifiers). Capabilities may be supplied by the GraphQL implementation, by the +service, or both. + +The `__Service.capabilities` field exposes a _capability_ list. A _capability_ +comprises of a capability identifier and optionally a string value. **Capability identifier** diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 8419eb789..9ee1e213a 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -865,11 +865,13 @@ _request_. If omitted, the _default error behavior_ of the service applies. Valid values for _error behavior_ are {"PROPAGATE"}, {"NO_PROPAGATE"} and {"HALT"}. + + :: The _default error behavior_ of a service is implementation-defined. For compatibility with existing clients, services should default to {"PROPAGATE"} -which reflects prior behavior. For new services, {"NO_PROPAGATE"} is -recommended. The default error behavior is indicated via the -`defaultErrorBehavior` field of the `__Service` introspection type. +which reflects prior behavior. The default error behavior is indicated via the +`org.graphql.defaultErrorBehavior` _capability_. Note: {"HALT"} is not recommended as the _default error behavior_ because it prevents generating partial responses which may still contain useful data. From 641a786a3eb154a36d54687c2cb39bb7c6158e2d Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 22 May 2025 19:51:23 +0100 Subject: [PATCH 10/15] Reorder --- spec/Section 4 -- Introspection.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 03e89866d..39dcf3e3a 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -85,14 +85,14 @@ operation. ## Schema Introspection -The schema introspection system is accessible from the meta-fields `__service`, -`__schema` and `__type` which are accessible from the type of the root of a +The schema introspection system is accessible from the meta-fields `__schema`, +`__type` and `__service` which are accessible from the type of the root of a query operation. ```graphql -__service: __Service! __schema: __Schema! __type(name: String!): __Type +__service: __Service! ``` Like all meta-fields, these are implicit and do not appear in the fields list in From 026982b3188118c57faede2cfa723b2471e88090 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 22 May 2025 20:24:45 +0100 Subject: [PATCH 11/15] Reword --- spec/Section 4 -- Introspection.md | 16 ++++++++-------- spec/Section 6 -- Execution.md | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 39dcf3e3a..fbfa1f66a 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -537,14 +537,14 @@ comprises of a capability identifier and optionally a string value. **Capability identifier** -Capability identifiers are inspired by reverse domain name notation in order to -help them be globally unique and collision-resistant. They are a string value -composed of two or more segments separated by a period (`.`). Each segment must -begin with a letter and must contain only alphanumeric characters and hyphens -(`[a-zA-Z][a-zA-Z0-9-]*`). Unlike the domain name system, capability identifiers -are case sensitive. Identifiers beginning with the prefix {"org.graphql."} are -reserved and must not be used outside of official GraphQL Foundation -specifications. Further, identifiers beginning with the prefix +A capability identifier is a string value composed of two or more segments +separated by a period (`.`). Each segment must begin with a letter and must +contain only alphanumeric characters and hyphens (`[a-zA-Z][a-zA-Z0-9-]*`). +These constraints are inspired by reverse domain name notation to encourage +global uniqueness and collision-resistance. Unlike the domain name system, +capability identifiers are case sensitive. Identifiers beginning with the prefix +{"org.graphql."} are reserved and must not be used outside of official GraphQL +Foundation specifications. Further, identifiers beginning with the prefix {"org.graphql.http."} are reserved for use by the GraphQL-over-HTTP specification, and identifiers beginning with the prefix {"org.graphql.rfc."} are reserved for RFC proposals. diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 9ee1e213a..7936eefca 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -871,7 +871,7 @@ Valid values for _error behavior_ are {"PROPAGATE"}, {"NO_PROPAGATE"} and compatibility with existing clients, services should default to {"PROPAGATE"} which reflects prior behavior. The default error behavior is indicated via the -`org.graphql.defaultErrorBehavior` _capability_. +{"org.graphql.defaultErrorBehavior"} _capability_. Note: {"HALT"} is not recommended as the _default error behavior_ because it prevents generating partial responses which may still contain useful data. From a7c6ad5454c4476df980cfe884ab8771699732c6 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 22 May 2025 20:42:48 +0100 Subject: [PATCH 12/15] Editorial --- spec/Section 4 -- Introspection.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index fbfa1f66a..f1be9867b 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -533,7 +533,7 @@ identifiers). Capabilities may be supplied by the GraphQL implementation, by the service, or both. The `__Service.capabilities` field exposes a _capability_ list. A _capability_ -comprises of a capability identifier and optionally a string value. +consists of a capability identifier and optionally a string value. **Capability identifier** @@ -558,9 +558,9 @@ ignore unknown identifiers. Implementers should not change the meaning of capability identifiers, instead a new capability identifier should be used when the meaning changes. Implementers -should ensure that capability strings remain stable and version-agnostic where -possible; capability versioning, if needed, can be indicated using dot suffixes -(e.g.{ "org.example.capability.v2"}). +should ensure that capability identifiers remain stable and version-agnostic +where possible; capability versioning, if needed, can be indicated using dot +suffixes (e.g.{ "org.example.capability.v2"}). This system enables incremental feature adoption and richer tooling interoperability, while avoiding tight coupling to specific implementations. @@ -569,11 +569,10 @@ interoperability, while avoiding tight coupling to specific implementations. The value assigned to a given capability may either be {null} to indicate that the capability is supported and requires no additional information, or a string -to provide additional information. For example -{"org.graphql.rfc.fragmentArguments"} does not require additional information -and thus would have value {null}, whereas {"org.graphql.websockets"} might -indicate support for websockets whilst using the value to indicate the endpoint -to use. +to provide additional information. For example {"org.graphql.onError"} does not +require additional information and thus uses the value {null}, whereas +{"org.graphql.defaultErrorBehavior"} needs the {value} to indicate which _error +behavior_ is the default. **Specified capabilities** From fe559ea23fd02d0f2ab08bf127fa14673d2061c9 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 22 May 2025 20:50:51 +0100 Subject: [PATCH 13/15] More editorial --- spec/Section 4 -- Introspection.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index f1be9867b..52af023da 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -529,7 +529,7 @@ Fields\: directly expressible in the type system. This may include experimental GraphQL features (such as new syntax or behavior), protocol support (such as GraphQL over WebSockets), or additional operational metadata (such as release -identifiers). Capabilities may be supplied by the GraphQL implementation, by the +identifiers). Capabilities may be supplied by the GraphQL implementation, the service, or both. The `__Service.capabilities` field exposes a _capability_ list. A _capability_ @@ -538,13 +538,13 @@ consists of a capability identifier and optionally a string value. **Capability identifier** A capability identifier is a string value composed of two or more segments -separated by a period (`.`). Each segment must begin with a letter and must -contain only alphanumeric characters and hyphens (`[a-zA-Z][a-zA-Z0-9-]*`). -These constraints are inspired by reverse domain name notation to encourage -global uniqueness and collision-resistance. Unlike the domain name system, -capability identifiers are case sensitive. Identifiers beginning with the prefix -{"org.graphql."} are reserved and must not be used outside of official GraphQL -Foundation specifications. Further, identifiers beginning with the prefix +separated by a period (`.`). Each segment must begin with an ASCII letter, and +must contain only ASCII letters, digits and hyphens. These constraints are +inspired by reverse domain name notation to encourage global uniqueness and +collision-resistance. Unlike the domain name system, capability identifiers are +case sensitive. Identifiers beginning with the prefix {"org.graphql."} are +reserved and must not be used outside of official GraphQL Foundation +specifications. Further, identifiers beginning with the prefix {"org.graphql.http."} are reserved for use by the GraphQL-over-HTTP specification, and identifiers beginning with the prefix {"org.graphql.rfc."} are reserved for RFC proposals. @@ -567,12 +567,11 @@ interoperability, while avoiding tight coupling to specific implementations. **Capability value** -The value assigned to a given capability may either be {null} to indicate that -the capability is supported and requires no additional information, or a string -to provide additional information. For example {"org.graphql.onError"} does not -require additional information and thus uses the value {null}, whereas -{"org.graphql.defaultErrorBehavior"} needs the {value} to indicate which _error -behavior_ is the default. +The value assigned to a given capability may either be {null} to simply indicate +the capability is supported, or a string to provide additional information. For +example {"org.graphql.onError"} does not require additional information and thus +uses the value {null}, whereas {"org.graphql.defaultErrorBehavior"} needs the +{value} to indicate which _error behavior_ is the default. **Specified capabilities** From b5f64ae9ec60288d993913eb422dee46be4b5826 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Thu, 22 May 2025 20:56:14 +0100 Subject: [PATCH 14/15] More editorial --- spec/Section 4 -- Introspection.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 52af023da..a9587a031 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -553,10 +553,10 @@ Identifiers defined by specific projects, vendors, or implementations should begin with a prefix derived from a DNS name they control (e.g., {"com.example."}). -Clients should use string equality to check for known identifiers, and should -ignore unknown identifiers. +Clients should compare identifiers using exact string equality and should ignore +unknown identifiers. -Implementers should not change the meaning of capability identifiers, instead a +Implementers should not change the meaning of capability identifiers; instead, a new capability identifier should be used when the meaning changes. Implementers should ensure that capability identifiers remain stable and version-agnostic where possible; capability versioning, if needed, can be indicated using dot From 1c3f0cd2b1ed6a97996dd750818eb88ce3139856 Mon Sep 17 00:00:00 2001 From: Benjie Date: Wed, 28 May 2025 20:49:46 +0100 Subject: [PATCH 15/15] Update spec/Section 4 -- Introspection.md --- spec/Section 4 -- Introspection.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index a9587a031..01378ac5c 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -544,10 +544,8 @@ inspired by reverse domain name notation to encourage global uniqueness and collision-resistance. Unlike the domain name system, capability identifiers are case sensitive. Identifiers beginning with the prefix {"org.graphql."} are reserved and must not be used outside of official GraphQL Foundation -specifications. Further, identifiers beginning with the prefix -{"org.graphql.http."} are reserved for use by the GraphQL-over-HTTP -specification, and identifiers beginning with the prefix {"org.graphql.rfc."} -are reserved for RFC proposals. +specifications. Identifiers beginning with the prefix {"org.graphql.rfc."} are +reserved for RFC proposals. Identifiers defined by specific projects, vendors, or implementations should begin with a prefix derived from a DNS name they control (e.g.,