From 413b1fb6a6c9cfefe1d7d26857f029530e2d0a7d Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 10:44:12 -0700 Subject: [PATCH 01/23] Update Section 2 -- Language.md --- spec/Section 2 -- Language.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 5be83f4d1..c8731fbb2 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -90,7 +90,7 @@ LineTerminator :: Like white space, line terminators are used to improve the legibility of source text and separate lexical tokens, any amount may appear before or after any other token and have no significance to the semantic meaning of a GraphQL -Document. Line terminators are not found within any other token. +Document. Note: Any error reporting which provides the line number in the source of the offending syntax should use the preceding amount of {LineTerminator} to produce @@ -358,8 +358,8 @@ piece of information available to request within a selection set. Some fields describe complex data or relationships to other data. In order to further explore this data, a field may itself contain a selection set, allowing for deeply nested requests. All GraphQL operations must specify their selections -down to fields which return scalar values to ensure an unambiguously shaped -response. +down to fields which return scalar or enum values (or lists of those types) +to ensure an unambiguously shaped response. For example, this operation selects fields of complex data and relationships down to scalar values. @@ -668,7 +668,7 @@ be present and `likers` will not. Conversely when the result is a `Page`, InlineFragment : ... TypeCondition? Directives? SelectionSet Fragments can be defined inline within a selection set. This is done to -conditionally include fields based on their runtime type. This feature of +conditionally include fields based on parent object's runtime type. This feature of standard fragment inclusion was demonstrated in the `query FragmentTyping` example. We could accomplish the same thing using inline fragments. @@ -1171,8 +1171,8 @@ VariableDefinition : Variable : Type DefaultValue? Directives[Const]? DefaultValue : = Value[Const] -A GraphQL operation can be parameterized with variables, maximizing reuse, and -avoiding costly string building in clients at runtime. +A GraphQL operation can be parameterized with variables +maximizing reuse of parsed queries by the GraphQL service. If not defined as constant (for example, in {DefaultValue}), a {Variable} can be supplied for an input value. From 97c6b3c7da6ebbd640bb5e1eaad044f084e3bcbb Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 11:09:36 -0700 Subject: [PATCH 02/23] Update Section 3 -- Type System.md --- spec/Section 3 -- Type System.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 0d44913a6..7c86c2da8 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -216,10 +216,6 @@ system definition language can omit the schema definition when the {`query`}, {`mutation`}, and {`subscription`} root types are named {"Query"}, {"Mutation"}, and {"Subscription"} respectively. -Likewise, when representing a GraphQL schema using the type system definition -language, a schema definition should be omitted if it only uses the default root -operation type names. - This example describes a valid complete GraphQL schema, despite not explicitly including a {`schema`} definition. The {"Query"} type is presumed to be the {`query`} root operation type of the schema. @@ -854,8 +850,9 @@ Produces the ordered result: **Result Coercion** -Determining the result of coercing an object is the heart of the GraphQL -executor, so this is covered in that section of the spec. +Determining the result of coercing an object is a part of the GraphQL request execution, +so this is covered in the [Coercing Results](#sec-Value-Completion.Coercing-Results) +section within the Execution section. **Input Coercion** @@ -1768,8 +1765,9 @@ Non-Null type is that result. If that result was {null}, then a field 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-Nullability" within the Execution section. +the parent field. For more information on this process, see +[Errors and Non-Null Fields](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields) +within the Execution section. **Input Coercion** From e9f4c8203a7b2132fcf775bdde946cd44788c67a Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 13:05:44 -0700 Subject: [PATCH 03/23] Update Section 4 -- Introspection.md --- spec/Section 4 -- Introspection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 63a5981b9..3aa4e40e0 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -328,8 +328,8 @@ Fields\: - `fields` must return the set of fields required by this interface. - Accepts the argument `includeDeprecated` which defaults to {false}. If {true}, deprecated fields are also returned. -- `interfaces` must return the set of interfaces that an object implements (if - none, `interfaces` must return the empty set). +- `interfaces` must return the set of interfaces that an interface implements + (if none, `interfaces` must return the empty set). - `possibleTypes` returns the list of types that implement this interface. They must be object types. - All other fields must return {null}. From 1e67a0dc58c0361257a4a711146e3d064bb63fbb Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 13:10:38 -0700 Subject: [PATCH 04/23] Update Section 5 -- Validation.md --- spec/Section 5 -- Validation.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 1938922bf..cd44c0014 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -1,6 +1,6 @@ # Validation -GraphQL does not just verify if a request is syntactically correct, but also +GraphQL service does not just verify if a request is syntactically correct, but also ensures that it is unambiguous and mistake-free in the context of a given GraphQL schema. @@ -13,9 +13,8 @@ Typically validation is performed in the context of a request immediately before execution, however a GraphQL service may execute a request without explicitly validating it if that exact same request is known to have been validated before. For example: the request may be validated during development, provided it does -not later change, or a service may validate a request once and memoize the -result to avoid validating the same request again in the future. Any client-side -or development-time tool should report validation errors and not allow the +not later change. Any client-side or development-time +tool should report validation errors and not allow the formulation or execution of requests known to be invalid at that given point in time. From 4578e77c69698f5adcae999ab5b4acf669477bdd Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 13:13:22 -0700 Subject: [PATCH 05/23] Update Section 6 -- Execution.md --- spec/Section 6 -- Execution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index d3ac7847b..d9951126e 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -236,7 +236,7 @@ connectivity. **Delivery Agnostic** GraphQL subscriptions do not require any specific serialization format or -transport mechanism. Subscriptions specifies algorithms for the creation of a +transport mechanism. Subscriptions specify parameters for the creation of a stream, the content of each payload on that stream, and the closing of that stream. There are intentionally no specifications for message acknowledgement, buffering, resend requests, or any other quality of service (QoS) details. From 57949e71521e47734be28b9b92794f445ff818af Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 13:19:38 -0700 Subject: [PATCH 06/23] Update Section 5 -- Validation.md --- spec/Section 5 -- Validation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index cd44c0014..87d68cf98 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -555,7 +555,7 @@ fragment safeDifferingArgs on Pet { ``` However, the field responses must be shapes which can be merged. For example, -scalar values must not differ. In this example, `someValue` might be a `String` +scalar types must not differ. In this example, `someValue` might be a `String` or an `Int`: ```graphql counter-example @@ -575,9 +575,9 @@ fragment conflictingDifferingResponses on Pet { - For each {selection} in the document: - Let {selectionType} be the result type of {selection}. - - If {selectionType} is a scalar or enum: + - If {selectionType} is a scalar or enum or list of these types: - The subselection set of that selection must be empty. - - If {selectionType} is an interface, union, or object: + - If {selectionType} is an interface, union, or object or list of these types: - The subselection set of that selection must NOT BE empty. **Explanatory Text** From f9584afc8ee294be4edebdf46cf9b4802b12f71a Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 13:24:38 -0700 Subject: [PATCH 07/23] Update Section 5 -- Validation.md --- spec/Section 5 -- Validation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 87d68cf98..85c1fdbf7 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -575,14 +575,14 @@ fragment conflictingDifferingResponses on Pet { - For each {selection} in the document: - Let {selectionType} be the result type of {selection}. - - If {selectionType} is a scalar or enum or list of these types: + - If {selectionType} is a scalar, enum or list of those types: - The subselection set of that selection must be empty. - - If {selectionType} is an interface, union, or object or list of these types: + - If {selectionType} is an interface, union, object or list of those types: - The subselection set of that selection must NOT BE empty. **Explanatory Text** -Field selections on scalars or enums are never allowed, because they are the +Field selections on scalars, enums or list of those types are never allowed, because they are the leaf nodes of any GraphQL operation. The following is valid. @@ -604,8 +604,8 @@ fragment scalarSelectionsNotAllowedOnInt on Dog { ``` Conversely the leaf field selections of GraphQL operations must be of type -scalar or enum. Leaf selections on objects, interfaces, and unions without -subfields are disallowed. +scalar, enum, or list of those types. Leaf selections on objects, interfaces, unions +or list of those types without subfields are disallowed. Let's assume the following additions to the query root operation type of the schema: From 5cb7011bc992014e576752cc1247bf72a198eea2 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 13:40:02 -0700 Subject: [PATCH 08/23] Update Section 6 -- Execution.md --- spec/Section 6 -- Execution.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index d9951126e..15aa909e7 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -1,6 +1,6 @@ # Execution -GraphQL generates a response from a request via execution. +GraphQL service generates a response from a request via execution. :: A _request_ for execution consists of a few pieces of information: @@ -144,8 +144,7 @@ executing the operation’s top level selection set on the mutation root object type. This selection set should be executed serially. It is expected that the top level fields in a mutation operation perform -side-effects on the underlying data system. Serial execution of the provided -mutations ensures against race conditions during these side-effects. +side-effects on the underlying data system. ExecuteMutation(mutation, schema, variableValues, initialValue): @@ -174,7 +173,7 @@ Subscribe(subscription, schema, variableValues, initialValue): {MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues)} - Return {responseStream}. -Note: In large scale subscription systems, the {Subscribe()} and +Note: In a large-scale subscription system, the {Subscribe()} and {ExecuteSubscriptionEvent()} algorithms may be run on separate services to maintain predictable scaling properties. See the section below on Supporting Subscriptions at Scale. @@ -222,7 +221,7 @@ must receive no more events from that event stream. **Supporting Subscriptions at Scale** -Supporting subscriptions is a significant change for any GraphQL service. Query +Supporting subscriptions is a significant challenge for a GraphQL service. Query and mutation operations are stateless, allowing scaling via cloning of GraphQL service instances. Subscriptions, by contrast, are stateful and require maintaining the GraphQL document, variables, and other context over the lifetime @@ -396,7 +395,7 @@ completion before it continues on to the next item in the grouped field set: For example, given the following selection set to be executed serially: ```graphql example -{ +mutation { changeBirthday(birthday: $newBirthday) { month } @@ -418,7 +417,7 @@ As an illustrative example, let's assume we have a mutation field we execute the following selection set serially: ```graphql example -{ +mutation { first: changeTheNumber(newNumber: 1) { theNumber } From 4ccd1c4c852f477efa7a0bdde81a7a896b129d9c Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 13:48:53 -0700 Subject: [PATCH 09/23] Update Section 7 -- Response.md --- spec/Section 7 -- Response.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 2e58276ab..e66c05196 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -61,13 +61,12 @@ contains should indicate why no data was able to be returned. If the `data` entry in the response is present (including if it is the value {null}), the `errors` entry in the response may contain any field errors that -were raised during execution. If field errors were raised during execution, it -should contain those errors. +were raised during execution. **Request errors** Request errors are raised before execution begins. This may occur due to a parse -grammar or validation error in the requested document, an inability to determine +grammar or validation error in the request document, an inability to determine which operation to execute, or invalid input values for variables. Request errors are typically the fault of the requesting client. From 5d56a1560ebf6240a643778ac0d800771a1b46d8 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 13:52:53 -0700 Subject: [PATCH 10/23] Update Section 2 -- Language.md --- spec/Section 2 -- Language.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index c8731fbb2..c7bf1f14c 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -306,7 +306,7 @@ mutation { } ``` -**Query shorthand** +**Query Shorthand** If a document contains only one operation and that operation is a query which defines no variables and has no directives applied to it then that operation may @@ -439,7 +439,7 @@ Many arguments can exist for a given field: } ``` -**Arguments are unordered** +**Arguments are Unordered** Arguments may be provided in any syntactic order and maintain identical semantic meaning. @@ -1127,7 +1127,7 @@ curly-braces `{ }`. The values of an object literal may be any input value literal or variable (ex. `{ name: "Hello world", score: 1.0 }`). We refer to literal representation of input objects as "object literals." -**Input object fields are unordered** +**Input Object Fields are Unordered** Input object fields may be provided in any syntactic order and maintain identical semantic meaning. @@ -1204,7 +1204,7 @@ size `60`: } ``` -**Variable use within Fragments** +**Variable Use within Fragments** Variables can be used within fragments. Variables have global scope with a given operation, so a variable used within a fragment must be declared in any @@ -1279,7 +1279,7 @@ As future versions of GraphQL adopt new configurable execution capabilities, they may be exposed via directives. GraphQL services and tools may also provide any additional _custom directive_ beyond those described here. -**Directive order is significant** +**Directive Order is Significant** Directives may be provided in a specific syntactic order which may have semantic interpretation. From 9c625846e14495f81596ceac4b0a99ca976eef53 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 14:00:16 -0700 Subject: [PATCH 11/23] Update Section 5 -- Validation.md --- spec/Section 5 -- Validation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 85c1fdbf7..a4f2f44f0 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -18,7 +18,7 @@ tool should report validation errors and not allow the formulation or execution of requests known to be invalid at that given point in time. -**Type system evolution** +**Type System Evolution** As GraphQL type system schema evolves over time by adding new types and new fields, it is possible that a request which was previously valid could later @@ -1082,7 +1082,7 @@ fragment ownerFragment on Human { } ``` -#### Fragment spread is possible +#### Fragment Spread is Possible **Formal Specification** @@ -1107,7 +1107,7 @@ type matches the type condition. They also are spread within the context of a parent type. A fragment spread is only valid if its type condition could ever apply within the parent type. -##### Object Spreads In Object Scope +##### Object Spreads in Object Scope In the scope of an object type, the only valid object type fragment spread is one that applies to the same type that is in scope. @@ -1170,7 +1170,7 @@ that if one inspected the contents of the {CatOrDogNameFragment} you could note that no valid results would ever be returned. However we do not specify this as invalid because we only consider the fragment declaration, not its body. -##### Object Spreads In Abstract Scope +##### Object Spreads in Abstract Scope Union or interface spreads can be used within the context of an object type fragment, but only if the object type is one of the possible types of that @@ -1960,7 +1960,7 @@ query listToNonNullList($booleanList: [Boolean]) { This would fail validation because a `[T]` cannot be passed to a `[T]!`. Similarly a `[T]` cannot be passed to a `[T!]`. -**Allowing optional variables when default values exist** +**Allowing Optional Variables when Default Values Exist** A notable exception to typical variable type compatibility is allowing a variable definition with a nullable type to be provided to a non-null location From bd30fe1a7de3225dae3fb38cdfb829e2f3496508 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 14:02:35 -0700 Subject: [PATCH 12/23] Update Section 7 -- Response.md --- spec/Section 7 -- Response.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index e66c05196..d417ed963 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -63,7 +63,7 @@ If the `data` entry in the response is present (including if it is the value {null}), the `errors` entry in the response may contain any field errors that were raised during execution. -**Request errors** +**Request Errors** Request errors are raised before execution begins. This may occur due to a parse grammar or validation error in the request document, an inability to determine @@ -74,7 +74,7 @@ Request errors are typically the fault of the requesting client. If a request error is raised, execution does not begin and the `data` entry in the response must not be present. The `errors` entry must include the error. -**Field errors** +**Field Errors** Field errors are raised during execution from a particular field. This may occur due to an internal error during value resolution or failure to coerce the @@ -87,7 +87,7 @@ is produced (see [Handling Field Errors](#sec-Handling-Field-Errors)). The `data` entry in the response must be present. The `errors` entry should include all raised field errors. -**Error result format** +**Error Result Format** Every error must contain an entry with the key `message` with a string description of the error intended for the developer as a guide to understand and From e5c0dc54b6501b7a481fd1624c1b89b07c4246aa Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Tue, 7 Jun 2022 22:07:58 -0700 Subject: [PATCH 13/23] Update spec/Section 2 -- Language.md Co-authored-by: Benjie Gillam --- spec/Section 2 -- Language.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index c7bf1f14c..af8105540 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -358,8 +358,8 @@ piece of information available to request within a selection set. Some fields describe complex data or relationships to other data. In order to further explore this data, a field may itself contain a selection set, allowing for deeply nested requests. All GraphQL operations must specify their selections -down to fields which return scalar or enum values (or lists of those types) -to ensure an unambiguously shaped response. +down to leaf fields (fields whose unwrapped type is a scalar or enum) to ensure +an unambiguously shaped response. For example, this operation selects fields of complex data and relationships down to scalar values. From 40cf144acfe1de72bd6bfb17c2690474d3caa5e1 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Tue, 7 Jun 2022 22:10:57 -0700 Subject: [PATCH 14/23] Update spec/Section 2 -- Language.md Co-authored-by: Benjie Gillam --- spec/Section 2 -- Language.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index af8105540..4f06b9f05 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -668,9 +668,10 @@ be present and `likers` will not. Conversely when the result is a `Page`, InlineFragment : ... TypeCondition? Directives? SelectionSet Fragments can be defined inline within a selection set. This is done to -conditionally include fields based on parent object's runtime type. This feature of -standard fragment inclusion was demonstrated in the `query FragmentTyping` -example. We could accomplish the same thing using inline fragments. +conditionally include fields based on the concrete type of the object at +runtime. This feature of standard fragment inclusion was demonstrated in the +`query FragmentTyping` example. We could accomplish the same thing using inline +fragments. ```graphql example query inlineFragmentTyping { From a6a8e9188ffbd083c6b1114a5a539bde06d85bf1 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Thu, 9 Jun 2022 08:59:43 -0700 Subject: [PATCH 15/23] fixes based on Benji's feedback - reversed several fixes to discuss them separately --- spec/Section 2 -- Language.md | 4 ++-- spec/Section 3 -- Type System.md | 13 ++++++++++--- spec/Section 5 -- Validation.md | 14 +++++++------- spec/Section 6 -- Execution.md | 18 +++++++++--------- spec/Section 7 -- Response.md | 3 ++- 5 files changed, 30 insertions(+), 22 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 4f06b9f05..3059644eb 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -1172,8 +1172,8 @@ VariableDefinition : Variable : Type DefaultValue? Directives[Const]? DefaultValue : = Value[Const] -A GraphQL operation can be parameterized with variables -maximizing reuse of parsed queries by the GraphQL service. +A GraphQL operation can be parameterized with variables, maximizing reuse, and +avoiding costly string building in clients at runtime. If not defined as constant (for example, in {DefaultValue}), a {Variable} can be supplied for an input value. diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 7c86c2da8..d98493091 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -216,6 +216,14 @@ system definition language can omit the schema definition when the {`query`}, {`mutation`}, and {`subscription`} root types are named {"Query"}, {"Mutation"}, and {"Subscription"} respectively. +Likewise, when representing a GraphQL schema using the type system definition +language, a schema definition should be omitted if it only uses the default root +operation type names. + +Likewise, when representing a GraphQL schema using the type system definition +language, a schema definition should be omitted if it only uses the default root +operation type names. + This example describes a valid complete GraphQL schema, despite not explicitly including a {`schema`} definition. The {"Query"} type is presumed to be the {`query`} root operation type of the schema. @@ -850,9 +858,8 @@ Produces the ordered result: **Result Coercion** -Determining the result of coercing an object is a part of the GraphQL request execution, -so this is covered in the [Coercing Results](#sec-Value-Completion.Coercing-Results) -section within the Execution section. +Determining the result of coercing an object is the heart of the GraphQL +executor, so this is covered in that section of the spec. **Input Coercion** diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index a4f2f44f0..0aec6b5b4 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -574,16 +574,16 @@ fragment conflictingDifferingResponses on Pet { **Formal Specification** - For each {selection} in the document: - - Let {selectionType} be the result type of {selection}. - - If {selectionType} is a scalar, enum or list of those types: + - Let {selectionType} be the unwrapped result type of {selection}. + - If {selectionType} is a scalar or enum: - The subselection set of that selection must be empty. - If {selectionType} is an interface, union, object or list of those types: - The subselection set of that selection must NOT BE empty. **Explanatory Text** -Field selections on scalars, enums or list of those types are never allowed, because they are the -leaf nodes of any GraphQL operation. +Scalars and enums are the underlying type of leaf nodes of any GraphQL +operation. Field selections are never allowed on leaf nodes. The following is valid. @@ -603,9 +603,9 @@ fragment scalarSelectionsNotAllowedOnInt on Dog { } ``` -Conversely the leaf field selections of GraphQL operations must be of type -scalar, enum, or list of those types. Leaf selections on objects, interfaces, unions -or list of those types without subfields are disallowed. +Conversely the underlying type of leaf field selections of GraphQL operations +must be scalar or enum. Leaf selections without subfields on fields whose +underlying type is object, interface, or union are disallowed. Let's assume the following additions to the query root operation type of the schema: diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 15aa909e7..9ace52e50 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -221,7 +221,7 @@ must receive no more events from that event stream. **Supporting Subscriptions at Scale** -Supporting subscriptions is a significant challenge for a GraphQL service. Query +Supporting subscriptions is a significant change for any GraphQL service. Query and mutation operations are stateless, allowing scaling via cloning of GraphQL service instances. Subscriptions, by contrast, are stateful and require maintaining the GraphQL document, variables, and other context over the lifetime @@ -235,12 +235,12 @@ connectivity. **Delivery Agnostic** GraphQL subscriptions do not require any specific serialization format or -transport mechanism. Subscriptions specify parameters for the creation of a -stream, the content of each payload on that stream, and the closing of that -stream. There are intentionally no specifications for message acknowledgement, -buffering, resend requests, or any other quality of service (QoS) details. -Message serialization, transport mechanisms, and quality of service details -should be chosen by the implementing service. +transport mechanism. GraphQL specifies algorithms for the creation of a +subscription stream, the content of each payload on that stream, and the closing +of that stream. There are intentionally no specifications for message +acknowledgement, buffering, resend requests, or any other quality of service +(QoS) details. Message serialization, transport mechanisms, and quality of +service details should be chosen by the implementing service. #### Source Stream @@ -395,7 +395,7 @@ completion before it continues on to the next item in the grouped field set: For example, given the following selection set to be executed serially: ```graphql example -mutation { +{ changeBirthday(birthday: $newBirthday) { month } @@ -417,7 +417,7 @@ As an illustrative example, let's assume we have a mutation field we execute the following selection set serially: ```graphql example -mutation { +{ first: changeTheNumber(newNumber: 1) { theNumber } diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index d417ed963..627e08c73 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -61,7 +61,8 @@ contains should indicate why no data was able to be returned. If the `data` entry in the response is present (including if it is the value {null}), the `errors` entry in the response may contain any field errors that -were raised during execution. +were raised during execution. If field errors were raised during execution, it +should contain those errors. **Request Errors** From f062daf46cc46fa773e8da63bb2fc8650c1ef1c8 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 10 Jun 2022 07:52:13 -0700 Subject: [PATCH 16/23] updates following PR feedback --- spec/Section 3 -- Type System.md | 4 ---- spec/Section 5 -- Validation.md | 9 +++++---- spec/Section 6 -- Execution.md | 5 +++-- 3 files changed, 8 insertions(+), 10 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index d98493091..4f00cd848 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -220,10 +220,6 @@ Likewise, when representing a GraphQL schema using the type system definition language, a schema definition should be omitted if it only uses the default root operation type names. -Likewise, when representing a GraphQL schema using the type system definition -language, a schema definition should be omitted if it only uses the default root -operation type names. - This example describes a valid complete GraphQL schema, despite not explicitly including a {`schema`} definition. The {"Query"} type is presumed to be the {`query`} root operation type of the schema. diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 0aec6b5b4..a80a3ed6b 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -1,6 +1,6 @@ # Validation -GraphQL service does not just verify if a request is syntactically correct, but also +A GraphQL service does not just verify if a request is syntactically correct, but also ensures that it is unambiguous and mistake-free in the context of a given GraphQL schema. @@ -13,8 +13,9 @@ Typically validation is performed in the context of a request immediately before execution, however a GraphQL service may execute a request without explicitly validating it if that exact same request is known to have been validated before. For example: the request may be validated during development, provided it does -not later change. Any client-side or development-time -tool should report validation errors and not allow the +not later change, or a service may validate a request once and memoize the +result to avoid validating the same request again in the future. Any client-side +or development-time tool should report validation errors and not allow the formulation or execution of requests known to be invalid at that given point in time. @@ -577,7 +578,7 @@ fragment conflictingDifferingResponses on Pet { - Let {selectionType} be the unwrapped result type of {selection}. - If {selectionType} is a scalar or enum: - The subselection set of that selection must be empty. - - If {selectionType} is an interface, union, object or list of those types: + - If {selectionType} is an interface, union, or object: - The subselection set of that selection must NOT BE empty. **Explanatory Text** diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 9ace52e50..e2d1f75da 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -1,6 +1,6 @@ # Execution -GraphQL service generates a response from a request via execution. +A GraphQL service generates a response from a request via execution. :: A _request_ for execution consists of a few pieces of information: @@ -144,7 +144,8 @@ executing the operation’s top level selection set on the mutation root object type. This selection set should be executed serially. It is expected that the top level fields in a mutation operation perform -side-effects on the underlying data system. +side-effects on the underlying data system. Serial execution of the provided +mutations ensures against race conditions during these side-effects. ExecuteMutation(mutation, schema, variableValues, initialValue): From c7df3e33080b07dba520524813d21481fd93a706 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 10 Jun 2022 10:53:49 -0700 Subject: [PATCH 17/23] reverted fix for P14, to be fixed by #958 --- spec/Section 5 -- Validation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index a80a3ed6b..115c081c8 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -575,7 +575,7 @@ fragment conflictingDifferingResponses on Pet { **Formal Specification** - For each {selection} in the document: - - Let {selectionType} be the unwrapped result type of {selection}. + - Let {selectionType} be the result type of {selection}. - If {selectionType} is a scalar or enum: - The subselection set of that selection must be empty. - If {selectionType} is an interface, union, or object: @@ -583,8 +583,8 @@ fragment conflictingDifferingResponses on Pet { **Explanatory Text** -Scalars and enums are the underlying type of leaf nodes of any GraphQL -operation. Field selections are never allowed on leaf nodes. +Field selections on scalars or enums are never allowed, because they are the +leaf nodes of any GraphQL operation. The following is valid. @@ -604,9 +604,9 @@ fragment scalarSelectionsNotAllowedOnInt on Dog { } ``` -Conversely the underlying type of leaf field selections of GraphQL operations -must be scalar or enum. Leaf selections without subfields on fields whose -underlying type is object, interface, or union are disallowed. +Conversely the leaf field selections of GraphQL operations must be of type +scalar or enum. Leaf selections on objects, interfaces, and unions without +subfields are disallowed. Let's assume the following additions to the query root operation type of the schema: From f940100ae4fe0c42546bbe6a240cb615708ff3a5 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Fri, 3 Jun 2022 10:44:12 -0700 Subject: [PATCH 18/23] reverted fix for P14, to be fixed by #958 (+16 squashed commit) Squashed commit: [f062daf] updates following PR feedback [a6a8e91] fixes based on Benji's feedback - reversed several fixes to discuss them separately [40cf144] Update spec/Section 2 -- Language.md Co-authored-by: Benjie Gillam [e5c0dc5] Update spec/Section 2 -- Language.md Co-authored-by: Benjie Gillam [bd30fe1] Update Section 7 -- Response.md [9c62584] Update Section 5 -- Validation.md [5d56a15] Update Section 2 -- Language.md [4ccd1c4] Update Section 7 -- Response.md [5cb7011] Update Section 6 -- Execution.md [f9584af] Update Section 5 -- Validation.md [57949e7] Update Section 5 -- Validation.md [4578e77] Update Section 6 -- Execution.md [1e67a0d] Update Section 5 -- Validation.md [e9f4c82] Update Section 4 -- Introspection.md [97c6b3c] Update Section 3 -- Type System.md [413b1fb] Update Section 2 -- Language.md --- spec/Section 2 -- Language.md | 23 ++++++++++++----------- spec/Section 3 -- Type System.md | 5 +++-- spec/Section 4 -- Introspection.md | 4 ++-- spec/Section 5 -- Validation.md | 14 +++++++------- spec/Section 6 -- Execution.md | 16 ++++++++-------- spec/Section 7 -- Response.md | 8 ++++---- 6 files changed, 36 insertions(+), 34 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 5be83f4d1..3059644eb 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -90,7 +90,7 @@ LineTerminator :: Like white space, line terminators are used to improve the legibility of source text and separate lexical tokens, any amount may appear before or after any other token and have no significance to the semantic meaning of a GraphQL -Document. Line terminators are not found within any other token. +Document. Note: Any error reporting which provides the line number in the source of the offending syntax should use the preceding amount of {LineTerminator} to produce @@ -306,7 +306,7 @@ mutation { } ``` -**Query shorthand** +**Query Shorthand** If a document contains only one operation and that operation is a query which defines no variables and has no directives applied to it then that operation may @@ -358,8 +358,8 @@ piece of information available to request within a selection set. Some fields describe complex data or relationships to other data. In order to further explore this data, a field may itself contain a selection set, allowing for deeply nested requests. All GraphQL operations must specify their selections -down to fields which return scalar values to ensure an unambiguously shaped -response. +down to leaf fields (fields whose unwrapped type is a scalar or enum) to ensure +an unambiguously shaped response. For example, this operation selects fields of complex data and relationships down to scalar values. @@ -439,7 +439,7 @@ Many arguments can exist for a given field: } ``` -**Arguments are unordered** +**Arguments are Unordered** Arguments may be provided in any syntactic order and maintain identical semantic meaning. @@ -668,9 +668,10 @@ be present and `likers` will not. Conversely when the result is a `Page`, InlineFragment : ... TypeCondition? Directives? SelectionSet Fragments can be defined inline within a selection set. This is done to -conditionally include fields based on their runtime type. This feature of -standard fragment inclusion was demonstrated in the `query FragmentTyping` -example. We could accomplish the same thing using inline fragments. +conditionally include fields based on the concrete type of the object at +runtime. This feature of standard fragment inclusion was demonstrated in the +`query FragmentTyping` example. We could accomplish the same thing using inline +fragments. ```graphql example query inlineFragmentTyping { @@ -1127,7 +1128,7 @@ curly-braces `{ }`. The values of an object literal may be any input value literal or variable (ex. `{ name: "Hello world", score: 1.0 }`). We refer to literal representation of input objects as "object literals." -**Input object fields are unordered** +**Input Object Fields are Unordered** Input object fields may be provided in any syntactic order and maintain identical semantic meaning. @@ -1204,7 +1205,7 @@ size `60`: } ``` -**Variable use within Fragments** +**Variable Use within Fragments** Variables can be used within fragments. Variables have global scope with a given operation, so a variable used within a fragment must be declared in any @@ -1279,7 +1280,7 @@ As future versions of GraphQL adopt new configurable execution capabilities, they may be exposed via directives. GraphQL services and tools may also provide any additional _custom directive_ beyond those described here. -**Directive order is significant** +**Directive Order is Significant** Directives may be provided in a specific syntactic order which may have semantic interpretation. diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 0d44913a6..4f00cd848 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1768,8 +1768,9 @@ Non-Null type is that result. If that result was {null}, then a field 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-Nullability" within the Execution section. +the parent field. For more information on this process, see +[Errors and Non-Null Fields](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields) +within the Execution section. **Input Coercion** diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 63a5981b9..3aa4e40e0 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -328,8 +328,8 @@ Fields\: - `fields` must return the set of fields required by this interface. - Accepts the argument `includeDeprecated` which defaults to {false}. If {true}, deprecated fields are also returned. -- `interfaces` must return the set of interfaces that an object implements (if - none, `interfaces` must return the empty set). +- `interfaces` must return the set of interfaces that an interface implements + (if none, `interfaces` must return the empty set). - `possibleTypes` returns the list of types that implement this interface. They must be object types. - All other fields must return {null}. diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 1938922bf..115c081c8 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -1,6 +1,6 @@ # Validation -GraphQL does not just verify if a request is syntactically correct, but also +A GraphQL service does not just verify if a request is syntactically correct, but also ensures that it is unambiguous and mistake-free in the context of a given GraphQL schema. @@ -19,7 +19,7 @@ or development-time tool should report validation errors and not allow the formulation or execution of requests known to be invalid at that given point in time. -**Type system evolution** +**Type System Evolution** As GraphQL type system schema evolves over time by adding new types and new fields, it is possible that a request which was previously valid could later @@ -556,7 +556,7 @@ fragment safeDifferingArgs on Pet { ``` However, the field responses must be shapes which can be merged. For example, -scalar values must not differ. In this example, `someValue` might be a `String` +scalar types must not differ. In this example, `someValue` might be a `String` or an `Int`: ```graphql counter-example @@ -1083,7 +1083,7 @@ fragment ownerFragment on Human { } ``` -#### Fragment spread is possible +#### Fragment Spread is Possible **Formal Specification** @@ -1108,7 +1108,7 @@ type matches the type condition. They also are spread within the context of a parent type. A fragment spread is only valid if its type condition could ever apply within the parent type. -##### Object Spreads In Object Scope +##### Object Spreads in Object Scope In the scope of an object type, the only valid object type fragment spread is one that applies to the same type that is in scope. @@ -1171,7 +1171,7 @@ that if one inspected the contents of the {CatOrDogNameFragment} you could note that no valid results would ever be returned. However we do not specify this as invalid because we only consider the fragment declaration, not its body. -##### Object Spreads In Abstract Scope +##### Object Spreads in Abstract Scope Union or interface spreads can be used within the context of an object type fragment, but only if the object type is one of the possible types of that @@ -1961,7 +1961,7 @@ query listToNonNullList($booleanList: [Boolean]) { This would fail validation because a `[T]` cannot be passed to a `[T]!`. Similarly a `[T]` cannot be passed to a `[T!]`. -**Allowing optional variables when default values exist** +**Allowing Optional Variables when Default Values Exist** A notable exception to typical variable type compatibility is allowing a variable definition with a nullable type to be provided to a non-null location diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index d3ac7847b..e2d1f75da 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -1,6 +1,6 @@ # Execution -GraphQL generates a response from a request via execution. +A GraphQL service generates a response from a request via execution. :: A _request_ for execution consists of a few pieces of information: @@ -174,7 +174,7 @@ Subscribe(subscription, schema, variableValues, initialValue): {MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues)} - Return {responseStream}. -Note: In large scale subscription systems, the {Subscribe()} and +Note: In a large-scale subscription system, the {Subscribe()} and {ExecuteSubscriptionEvent()} algorithms may be run on separate services to maintain predictable scaling properties. See the section below on Supporting Subscriptions at Scale. @@ -236,12 +236,12 @@ connectivity. **Delivery Agnostic** GraphQL subscriptions do not require any specific serialization format or -transport mechanism. Subscriptions specifies algorithms for the creation of a -stream, the content of each payload on that stream, and the closing of that -stream. There are intentionally no specifications for message acknowledgement, -buffering, resend requests, or any other quality of service (QoS) details. -Message serialization, transport mechanisms, and quality of service details -should be chosen by the implementing service. +transport mechanism. GraphQL specifies algorithms for the creation of a +subscription stream, the content of each payload on that stream, and the closing +of that stream. There are intentionally no specifications for message +acknowledgement, buffering, resend requests, or any other quality of service +(QoS) details. Message serialization, transport mechanisms, and quality of +service details should be chosen by the implementing service. #### Source Stream diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 2e58276ab..627e08c73 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -64,10 +64,10 @@ If the `data` entry in the response is present (including if it is the value were raised during execution. If field errors were raised during execution, it should contain those errors. -**Request errors** +**Request Errors** Request errors are raised before execution begins. This may occur due to a parse -grammar or validation error in the requested document, an inability to determine +grammar or validation error in the request document, an inability to determine which operation to execute, or invalid input values for variables. Request errors are typically the fault of the requesting client. @@ -75,7 +75,7 @@ Request errors are typically the fault of the requesting client. If a request error is raised, execution does not begin and the `data` entry in the response must not be present. The `errors` entry must include the error. -**Field errors** +**Field Errors** Field errors are raised during execution from a particular field. This may occur due to an internal error during value resolution or failure to coerce the @@ -88,7 +88,7 @@ is produced (see [Handling Field Errors](#sec-Handling-Field-Errors)). The `data` entry in the response must be present. The `errors` entry should include all raised field errors. -**Error result format** +**Error Result Format** Every error must contain an entry with the key `message` with a string description of the error intended for the developer as a guide to understand and From 97b240c7c11dc0f82ca7bd4cc29b8d1e10ddf6ad Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Sat, 11 Jun 2022 13:04:53 +0100 Subject: [PATCH 19/23] Prettier --- spec/Section 2 -- Language.md | 2 +- spec/Section 3 -- Type System.md | 4 ++-- spec/Section 5 -- Validation.md | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 3059644eb..9dc86b1bb 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -90,7 +90,7 @@ LineTerminator :: Like white space, line terminators are used to improve the legibility of source text and separate lexical tokens, any amount may appear before or after any other token and have no significance to the semantic meaning of a GraphQL -Document. +Document. Note: Any error reporting which provides the line number in the source of the offending syntax should use the preceding amount of {LineTerminator} to produce diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 4f00cd848..3d59e540b 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1768,8 +1768,8 @@ Non-Null type is that result. If that result was {null}, then a field 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) +the parent field. For more information on this process, see +[Errors and Non-Null Fields](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields) within the Execution section. **Input Coercion** diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 115c081c8..7326e2543 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -1,8 +1,8 @@ # Validation -A GraphQL service does not just verify if a request is syntactically correct, but also -ensures that it is unambiguous and mistake-free in the context of a given -GraphQL schema. +A GraphQL service does not just verify if a request is syntactically correct, +but also ensures that it is unambiguous and mistake-free in the context of a +given GraphQL schema. An invalid request is still technically executable, and will always produce a stable result as defined by the algorithms in the Execution section, however From d5b317a38d3b75c36dcf5549dcfd2d264ae96bf5 Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Sat, 11 Jun 2022 10:26:17 -0700 Subject: [PATCH 20/23] minor edit, scalar->leaf --- spec/Section 5 -- Validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 7326e2543..c573eba54 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -556,7 +556,7 @@ fragment safeDifferingArgs on Pet { ``` However, the field responses must be shapes which can be merged. For example, -scalar types must not differ. In this example, `someValue` might be a `String` +leaf types must not differ. In this example, `someValue` might be a `String` or an `Int`: ```graphql counter-example From cf30b345ad7492116abe36686fe7f762bbc9045d Mon Sep 17 00:00:00 2001 From: Roman Ivantsov Date: Sat, 11 Jun 2022 10:34:28 -0700 Subject: [PATCH 21/23] minor fix in 'Delivery Agnostic' section, reverted edit --- spec/Section 6 -- Execution.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index e2d1f75da..2d6ee8a38 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -236,12 +236,12 @@ connectivity. **Delivery Agnostic** GraphQL subscriptions do not require any specific serialization format or -transport mechanism. GraphQL specifies algorithms for the creation of a -subscription stream, the content of each payload on that stream, and the closing -of that stream. There are intentionally no specifications for message -acknowledgement, buffering, resend requests, or any other quality of service -(QoS) details. Message serialization, transport mechanisms, and quality of -service details should be chosen by the implementing service. +transport mechanism. Subscription specifies algorithms for the creation of a +stream, the content of each payload on that stream, and the closing of that +stream. There are intentionally no specifications for message acknowledgement, +buffering, resend requests, or any other quality of service (QoS) details. +Message serialization, transport mechanisms, and quality of service details +should be chosen by the implementing service. #### Source Stream From 5eeed0423101650b367fada5a443e3c5c1b01260 Mon Sep 17 00:00:00 2001 From: rivantsov2 Date: Wed, 15 Jun 2022 07:20:17 -0700 Subject: [PATCH 22/23] reverted fix for Subscriptions specifies --- spec/Section 6 -- Execution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 2d6ee8a38..0b158eed0 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -236,7 +236,7 @@ connectivity. **Delivery Agnostic** GraphQL subscriptions do not require any specific serialization format or -transport mechanism. Subscription specifies algorithms for the creation of a +transport mechanism. Subscriptions specifies algorithms for the creation of a stream, the content of each payload on that stream, and the closing of that stream. There are intentionally no specifications for message acknowledgement, buffering, resend requests, or any other quality of service (QoS) details. From d7e4aebb3240aca372f51536c7fdb26783eccd73 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Thu, 16 Jun 2022 10:54:05 -0700 Subject: [PATCH 23/23] Format --- spec/Section 5 -- Validation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index c573eba54..5753a3d77 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -556,8 +556,8 @@ fragment safeDifferingArgs on Pet { ``` However, the field responses must be shapes which can be merged. For example, -leaf types must not differ. In this example, `someValue` might be a `String` -or an `Int`: +leaf types must not differ. In this example, `someValue` might be a `String` or +an `Int`: ```graphql counter-example fragment conflictingDifferingResponses on Pet {