diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index c3c4c42fb..ca68e0d16 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -126,3 +126,13 @@ meaning. ✅ “A query must contain a single root operation type.” ❌ “A query MUST contain a single root operation type.” + +**Avoid unnecessary hyphenation** + +Only use hypenated compound words when either commonly used elsewhere in english +or technical writing. Otherwise prefer separate words or a non-hyphenated +compound word, whichever is most commonly accepted. + +✅ User defined shorthand words are separated by whitespace + +❌ User-defined short-hand words are separated by white-space diff --git a/spec/Appendix A -- Conformance.md b/spec/Appendix A -- Conformance.md index f954c2206..d975b024f 100644 --- a/spec/Appendix A -- Conformance.md +++ b/spec/Appendix A -- Conformance.md @@ -12,7 +12,7 @@ in lowercase and still retain their meaning unless explicitly declared as non-normative. A conforming implementation of GraphQL may provide additional functionality, but -must not where explicitly disallowed or would otherwise result in +must not do so where explicitly disallowed or where it would otherwise result in non-conformance. **Conforming Algorithms** @@ -42,19 +42,19 @@ as non-normative. Examples in this document are non-normative, and are presented to aid understanding of introduced concepts and the behavior of normative portions of the specification. Examples are either introduced explicitly in prose (e.g. "for -example") or are set apart in example or counter-example blocks, like this: +example") or are set apart in example or counterexample blocks, like this: ```example This is an example of a non-normative example. ``` ```counter-example -This is an example of a non-normative counter-example. +This is an example of a non-normative counterexample. ``` Notes in this document are non-normative, and are presented to clarify intent, -draw attention to potential edge-cases and pit-falls, and answer common -questions that arise during implementation. Notes are either introduced -explicitly in prose (e.g. "Note: ") or are set apart in a note block, like this: +draw attention to potential edge cases and pitfalls, and answer common questions +that arise during implementation. Notes are either introduced explicitly in +prose (e.g. "Note: ") or are set apart in a note block, like this: Note: This is an example of a non-normative note. diff --git a/spec/Appendix B -- Notation Conventions.md b/spec/Appendix B -- Notation Conventions.md index c318b9715..60a716dbc 100644 --- a/spec/Appendix B -- Notation Conventions.md +++ b/spec/Appendix B -- Notation Conventions.md @@ -11,7 +11,7 @@ ambiguity. A context-free grammar consists of a number of productions. Each production has an abstract symbol called a "non-terminal" as its left-hand side, and zero or -more possible sequences of non-terminal symbols and or terminal characters as +more possible sequences of non-terminal symbols and/or terminal characters as its right-hand side. Starting from a single goal non-terminal symbol, a context-free grammar @@ -21,8 +21,8 @@ of the sequences it is defined by, until all non-terminal symbols have been replaced by terminal characters. Terminals are represented in this document in a monospace font in two forms: a -specific Unicode character or sequence of Unicode characters (ie. {`=`} or -{`terminal`}), and prose typically describing a specific Unicode code-point +specific Unicode character or sequence of Unicode characters (i.e. {`=`} or +{`terminal`}), and prose typically describing a specific Unicode code point {"Space (U+0020)"}. Sequences of Unicode characters only appear in syntactic grammars and represent a {Name} token of that specific sequence. @@ -46,14 +46,14 @@ ListOfLetterA : - ListOfLetterA `a` - `a` -## Lexical and Syntactical Grammar +## Lexical and Syntactic Grammar The GraphQL language is defined in a syntactic grammar where terminal symbols are tokens. Tokens are defined in a lexical grammar which matches patterns of source characters. The result of parsing a source text sequence of Unicode characters first produces a sequence of lexical tokens according to the lexical grammar which then produces abstract syntax tree (AST) according to the -syntactical grammar. +syntactic grammar. A lexical grammar production describes non-terminal "tokens" by patterns of terminal Unicode characters. No "whitespace" or other ignored characters may @@ -63,10 +63,10 @@ definition. Word :: Letter+ -A Syntactical grammar production describes non-terminal "rules" by patterns of -terminal Tokens. {WhiteSpace} and other {Ignored} sequences may appear before or -after any terminal {Token}. A syntactical grammar production is distinguished by -a one colon `:` definition. +A Syntactic grammar production describes non-terminal "rules" by patterns of +terminal Tokens. {Whitespace} and other {Ignored} sequences may appear before or +after any terminal {Token}. A syntactic grammar production is distinguished by a +one colon `:` definition. Sentence : Word+ `.` @@ -74,7 +74,7 @@ Sentence : Word+ `.` This specification uses some additional notation to describe common patterns, such as optional or repeated patterns, or parameterized alterations of the -definition of a non-terminal. This section explains these short-hand notations +definition of a non-terminal. This section explains these shorthand notations and their expanded definitions in the context-free grammar. **Constraints** diff --git a/spec/Appendix C -- Grammar Summary.md b/spec/Appendix C -- Grammar Summary.md index cc5f75419..cc464a4a6 100644 --- a/spec/Appendix C -- Grammar Summary.md +++ b/spec/Appendix C -- Grammar Summary.md @@ -9,14 +9,14 @@ SourceCharacter :: "Any Unicode scalar value" Ignored :: - UnicodeBOM -- WhiteSpace +- Whitespace - LineTerminator - Comment - Comma UnicodeBOM :: "Byte Order Mark (U+FEFF)" -WhiteSpace :: +Whitespace :: - "Horizontal Tab (U+0009)" - "Space (U+0020)" diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 678e36da6..94b99f20d 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -23,11 +23,11 @@ throughout this document. **Lexical Analysis & Syntactic Parse** The source text of a GraphQL document is first converted into a sequence of -lexical tokens, {Token}, and ignored tokens, {Ignored}. The source text is -scanned from left to right, repeatedly taking the next possible sequence of -code-points allowed by the lexical grammar productions as the next token. This -sequence of lexical tokens are then scanned from left to right to produce an -abstract syntax tree (AST) according to the {Document} syntactical grammar. +lexical tokens ({Token}) and ignored tokens ({Ignored}). The source text is +scanned from left to right, repeatedly taking the next possible sequence of code +points allowed by the lexical grammar productions as the next token. This +sequence of lexical tokens is then scanned from left to right to produce an +abstract syntax tree (AST) according to the {Document} syntactic grammar. Lexical grammar productions in this document use _lookahead restrictions_ to remove ambiguity and ensure a single valid lexical analysis. A lexical token is @@ -36,7 +36,7 @@ only valid if not followed by a character in its lookahead restriction. For example, an {IntValue} has the restriction {[lookahead != Digit]}, so cannot be followed by a {Digit}. Because of this, the sequence {`123`} cannot represent the tokens ({`12`}, {`3`}) since {`12`} is followed by the {Digit} {`3`} and so -must only represent a single token. Use {WhiteSpace} or other {Ignored} between +must only represent a single token. Use {Whitespace} or other {Ignored} between characters to represent multiple tokens. Note: This typically has the same behavior as a @@ -64,19 +64,19 @@ however an unpaired _surrogate code point_ is not a valid source character. ### White Space -WhiteSpace :: +Whitespace :: - "Horizontal Tab (U+0009)" - "Space (U+0020)" -White space is used to improve legibility of source text and act as separation -between tokens, and any amount of white space may appear before or after any -token. White space between tokens is not significant to the semantic meaning of -a GraphQL Document, however white space characters may appear within a {String} -or {Comment} token. +Whitespace is used to improve legibility of source text and separates other +tokens. Any amount of whitespace may appear before or after any token. +Whitespace between tokens is not significant to the semantic meaning of a +GraphQL document, however whitespace characters may appear within a {String} or +{Comment} token. Note: GraphQL intentionally does not consider Unicode "Zs" category characters -as white-space, avoiding misinterpretation by text editors and source control +as whitespace, avoiding misinterpretation by text editors and source control tools. ### Line Terminators @@ -87,7 +87,7 @@ LineTerminator :: - "Carriage Return (U+000D)" [lookahead != "New Line (U+000A)"] - "Carriage Return (U+000D)" "New Line (U+000A)" -Like white space, line terminators are used to improve the legibility of source +Like whitespace, 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. @@ -109,21 +109,21 @@ A comment may contain any {SourceCharacter} except {LineTerminator} so a comment always consists of all {SourceCharacter} starting with the {`#`} character up to but not including the {LineTerminator} (or end of the source). -Comments are {Ignored} like white space and may appear after any token, or -before a {LineTerminator}, and have no significance to the semantic meaning of a -GraphQL Document. +Comments are {Ignored} like whitespace and may appear after any token, or before +a {LineTerminator}, and have no significance to the semantic meaning of a +GraphQL document. ### Insignificant Commas Comma :: , -Similar to white space and line terminators, commas ({`,`}) are used to improve +Similar to whitespace and line terminators, commas ({`,`}) are used to improve the legibility of source text and separate lexical tokens but are otherwise -syntactically and semantically insignificant within GraphQL Documents. +syntactically and semantically insignificant within GraphQL documents. Non-significant comma characters ensure that the absence or presence of a comma does not meaningfully alter the interpreted syntax of the document, as this can -be a common user-error in other languages. It also allows for the stylistic use +be a common user error in other languages. It also allows for the stylistic use of either trailing commas or line terminators as list delimiters which are both often desired for legibility and maintainability of source code. @@ -137,7 +137,7 @@ Token :: - FloatValue - StringValue -A GraphQL document is comprised of several kinds of indivisible lexical tokens +A GraphQL document is composed of several kinds of indivisible lexical tokens defined here in a lexical grammar by patterns of source Unicode characters. Lexical tokens may be separated by {Ignored} tokens. @@ -148,21 +148,21 @@ Tokens are later used as terminal symbols in GraphQL syntactic grammar rules. Ignored :: - UnicodeBOM -- WhiteSpace +- Whitespace - LineTerminator - Comment - Comma {Ignored} tokens are used to improve readability and provide separation between -lexical tokens, but are otherwise insignificant and not referenced in -syntactical grammar productions. +lexical tokens, but are otherwise insignificant and not referenced in syntactic +grammar productions. Any amount of {Ignored} may appear before and after every lexical token. No ignored regions of a source document are significant, however {SourceCharacter} which appear in {Ignored} may also appear within a lexical {Token} in a -significant way, for example a {StringValue} may contain white space characters. -No {Ignored} may appear _within_ a {Token}, for example no white space -characters are permitted between the characters defining a {FloatValue}. +significant way, for example a {StringValue} may contain whitespace characters. +No {Ignored} may appear _within_ a {Token}, for example no whitespace characters +are permitted between the characters defining a {FloatValue}. **Byte Order Mark** @@ -179,7 +179,7 @@ and is {Ignored}. Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | } GraphQL documents include punctuation in order to describe structure. GraphQL is -a data description language and not a programming language, therefore GraphQL +a data description language and not a programming language; therefore, GraphQL lacks the punctuation often used to describe mathematical expressions. ### Names @@ -210,7 +210,7 @@ Digit :: one of - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9` -GraphQL Documents are full of named things: operations, fields, arguments, +GraphQL documents are full of named things: operations, fields, arguments, types, directives, fragments, and variables. All names must follow the same grammatical form. @@ -300,7 +300,7 @@ ExecutableDefinition : - OperationDefinition - FragmentDefinition -A GraphQL Document describes a complete file or request string operated on by a +A GraphQL document describes a complete file or request string operated on by a GraphQL service or client. A document contains multiple definitions, either executable or representative of a GraphQL type system. @@ -321,7 +321,7 @@ individual files. If a Document contains only one operation, that operation may be unnamed. If that operation is a query without variables or directives then it may also be represented in the shorthand form, omitting both the {`query`} keyword as well -as the operation name. Otherwise, if a GraphQL Document contains multiple +as the operation name. Otherwise, if a GraphQL document contains multiple operations, each operation must be named. When submitting a Document with multiple operations to a GraphQL service, the name of the desired operation to be executed must also be provided. @@ -366,7 +366,7 @@ mutation { 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 -be represented in a short-hand form which omits the {`query`} keyword and +be represented in a shorthand form which omits the {`query`} keyword and operation name. For example, this unnamed query operation is written via query shorthand. @@ -379,7 +379,7 @@ For example, this unnamed query operation is written via query shorthand. Descriptions are not permitted on query shorthand. -Note: many examples below will use the query short-hand syntax. +Note: many examples below will use the query shorthand syntax. ## Selection Sets @@ -809,7 +809,7 @@ NegativeSign :: - NonZeroDigit :: Digit but not `0` An {IntValue} is specified without a decimal point or exponent but may be -negative (ex. {-123}). It must not have any leading {0}. +negative (e.g. {-123}). It must not have any leading {0}. An {IntValue} must not be followed by a {Digit}. In other words, an {IntValue} token is always the longest possible valid sequence. The source characters {12} @@ -838,8 +838,8 @@ ExponentIndicator :: one of `e` `E` Sign :: one of + - -A {FloatValue} includes either a decimal point (ex. {1.0}) or an exponent (ex. -{1e50}) or both (ex. {6.0221413e23}) and may be negative. Like {IntValue}, it +A {FloatValue} includes either a decimal point (e.g. {1.0}) or an exponent (e.g. +{1e50}) or both (e.g. {6.0221413e23}) and may be negative. Like {IntValue}, it also must not have any leading {0}. A {FloatValue} must not be followed by a {Digit}. In other words, a {FloatValue} @@ -899,7 +899,7 @@ BlockStringCharacter :: A {StringValue} is evaluated to a _Unicode text_ value, a sequence of _Unicode scalar value_, by interpreting all escape sequences using the static semantics -defined below. White space and other characters ignored between lexical tokens +defined below. Whitespace and other characters ignored between lexical tokens are significant within a string value. The empty string {`""`} must not be followed by another {`"`} otherwise it would @@ -952,7 +952,7 @@ sequence. **Block Strings** Block strings are sequences of characters wrapped in triple-quotes (`"""`). -White space, line terminators, quote, and backslash characters may all be used +Whitespace, line terminators, quote, and backslash characters may all be used unescaped to enable verbatim text. Characters must all be valid {SourceCharacter}. @@ -1097,7 +1097,7 @@ BlockStringValue(rawValue): - For each {line} in {lines}: - If {line} is the first item in {lines}, continue to the next {line}. - Let {length} be the number of characters in {line}. - - Let {indent} be the number of leading consecutive {WhiteSpace} characters in + - Let {indent} be the number of leading consecutive {Whitespace} characters in {line}. - If {indent} is less than {length}: - If {commonIndent} is {null} or {indent} is less than {commonIndent}: @@ -1106,9 +1106,9 @@ BlockStringValue(rawValue): - For each {line} in {lines}: - If {line} is the first item in {lines}, continue to the next line. - Remove {commonIndent} characters from the beginning of {line}. -- While the first item {line} in {lines} contains only {WhiteSpace}: +- While the first item {line} in {lines} contains only {Whitespace}: - Remove the first item from {lines}. -- While the last item {line} in {lines} contains only {WhiteSpace}: +- While the last item {line} in {lines} contains only {Whitespace}: - Remove the last item from {lines}. - Let {formatted} be the empty character sequence. - For each {line} in {lines}: @@ -1153,9 +1153,9 @@ variable value at all. EnumValue : Name but not `true`, `false` or `null` -Enum values are represented as unquoted names (ex. `MOBILE_WEB`). It is +Enum values are represented as unquoted names (e.g. `MOBILE_WEB`). It is recommended that Enum values be "all caps". Enum values are only used in -contexts where the precise enumeration type is known. Therefore it's not +contexts where the precise enumeration type is known. Therefore it is not necessary to supply an enumeration type name in the literal. ### List Value @@ -1165,8 +1165,9 @@ ListValue[Const] : - [ ] - [ Value[?Const]+ ] -Lists are ordered sequences of values wrapped in square-brackets `[ ]`. The -values of a List literal may be any value literal or variable (ex. `[1, 2, 3]`). +Lists are ordered sequences of values wrapped in square brackets `[ ]`. The +values of a List literal may be any value literal or variable (e.g. +`[1, 2, 3]`). Commas are optional throughout GraphQL so trailing commas are allowed and repeated commas do not represent missing values. @@ -1195,8 +1196,8 @@ ObjectValue[Const] : ObjectField[Const] : Name : Value[?Const] Input object literal values are unordered lists of keyed input values wrapped in -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 +curly braces `{ }`. The values of an object literal may be any input value +literal or variable (e.g. `{ name: "Hello world", score: 1.0 }`). We refer to literal representation of input objects as "object literals." **Input Object Fields Are Unordered** diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 219afb3d0..44760852c 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -16,7 +16,7 @@ TypeSystemDefinition : The GraphQL language includes an [IDL](https://en.wikipedia.org/wiki/Interface_description_language) used to describe a GraphQL service's type system. Tools may use this definition language -to provide utilities such as client code generation or service boot-strapping. +to provide utilities such as client code generation or service bootstrapping. GraphQL tools or services which only seek to execute GraphQL requests and not construct a new GraphQL schema may choose not to allow {TypeSystemDefinition}. @@ -434,7 +434,7 @@ GraphQL services may use custom scalar types in addition to the built-in scalars. For example, a GraphQL service could define a scalar called `UUID` which, while serialized as a string, conforms to [RFC 4122](https://tools.ietf.org/html/rfc4122). When querying a field of type -`UUID`, you can then rely on the ability to parse the result with a RFC 4122 +`UUID`, you can then rely on the ability to parse the result with an RFC 4122 compliant parser. Another example of a potentially useful custom scalar is `URL`, which serializes as a string, but is guaranteed by the service to be a valid URL. @@ -511,9 +511,9 @@ GraphQL has different constant literals to represent integer and floating-point input values, and coercion rules may apply differently depending on which type of input value is encountered. GraphQL may be parameterized by variables, the values of which are often serialized when sent over a transport like HTTP. Since -some common serializations (ex. JSON) do not discriminate between integer and +some common serializations (e.g. JSON) do not discriminate between integer and floating-point values, they are interpreted as an integer input value if they -have an empty fractional part (ex. `1.0`) and otherwise as floating-point input +have an empty fractional part (e.g. `1.0`) and otherwise as floating-point input value. For all types below, with the exception of Non-Null, if the explicit value @@ -692,11 +692,11 @@ GraphQL operations are hierarchical and composed, describing a tree of information. While Scalar types describe the leaf values of these hierarchical operations, Objects describe the intermediate levels. -GraphQL Objects represent a list of named fields, each of which yield a value of -a specific type. Object values should be serialized as ordered maps, where the -selected field names (or aliases) are the keys and the result of evaluating the -field is the value, ordered by the order in which they appear in the _selection -set_. +GraphQL Objects represent a list of named fields, each of which yields a value +of a specific type. Object values should be serialized as ordered maps, where +the selected field names (or aliases) are the keys and the result of evaluating +the field is the value, ordered by the order in which they appear in the +_selection set_. All fields defined within an Object type must not have a name which begins with {"\_\_"} (two underscores), as this is used exclusively by GraphQL's @@ -1115,8 +1115,8 @@ InterfaceTypeDefinition : [lookahead != `{`] GraphQL interfaces represent a list of named fields and their arguments. GraphQL -objects and interfaces can then implement these interfaces which requires that -the implementing type will define all fields defined by those interfaces. +objects and interfaces can then implement these interfaces which requires the +implementing type to define all fields defined by those interfaces. Fields on a GraphQL interface have the same rules as fields on a GraphQL object; their type can be Scalar, Object, Enum, Interface, or Union, or any wrapping @@ -1800,9 +1800,8 @@ _request error_ must be raised. that entry must not be {null} or the {null} literal, otherwise a _request error_ must be raised. -- All _Input Object_ - [input coercion rules](#sec-Input-Objects.Input-Coercion) - must also apply to an _OneOf Input Object_. +- All _Input Object_ [input coercion rules](#sec-Input-Objects.Input-Coercion) + must also apply to a _OneOf Input Object_. - The resulting coerced map must contain exactly one entry and the value for that entry must not be {null}, otherwise an _execution error_ must be raised. @@ -1884,7 +1883,7 @@ indicates a mismatch in expectations between the type system and the implementation. If a list's item type is nullable, then errors occurring during preparation or -coercion of an individual item in the list must result in a the value {null} at +coercion of an individual item in the list must result in the value {null} at that position in the list along with an _execution error_ added to the response. If a list's item type is non-null, an execution error occurring at an individual item in the list must result in an execution error for the entire list. diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 42aa4c6ca..8963a3e9c 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -59,8 +59,8 @@ would produce the result: **Reserved Names** Types and fields required by the GraphQL introspection system that are used in -the same context as user-defined types and fields are prefixed with {"\_\_"} two -underscores. This in order to avoid naming collisions with user-defined GraphQL +the same context as user defined types and fields are prefixed with {"\_\_"} +(two underscores), in order to avoid naming collisions with user defined GraphQL types. Otherwise, any {Name} within a GraphQL type system must not start with two @@ -251,13 +251,13 @@ Fields\: ### The \_\_Type Type -`__Type` is at the core of the type introspection system, it represents all +`__Type` is at the core of the type introspection system. It represents all types in the system: both named types (e.g. Scalars and Object types) and type modifiers (e.g. List and Non-Null types). Type modifiers are used to modify the type presented in the field `ofType`. This -modified type may recursively be a modified type, representing lists, -non-nullables, and combinations thereof, ultimately modifying a named type. +modified type may recursively be a modified type, representing a list or +non-null type, and combinations thereof, ultimately modifying a named type. There are several different kinds of type. In each kind, different fields are actually valid. All possible kinds are listed in the `__TypeKind` enum. @@ -294,7 +294,7 @@ Fields\: **Object** Object types represent concrete instantiations of sets of fields. The -introspection types (e.g. `__Type`, `__Field`, etc) are examples of objects. +introspection types (e.g. `__Type`, `__Field`, etc.) are examples of objects. Fields\: @@ -311,8 +311,8 @@ Fields\: **Union** Unions are an abstract type where no common fields are declared. The possible -types of a union are explicitly listed out in `possibleTypes`. Types can be made -parts of unions without modification of that type. +types of a union are explicitly listed out in `possibleTypes`. An object type +can be a member of a union without modification to that type. Fields\: diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 488881f88..c48a6ba4a 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -284,8 +284,8 @@ mutation dogOperation { **Explanatory Text** -GraphQL allows a short-hand form for defining query operations when only that -one operation exists in the document. +GraphQL allows a shorthand form for defining query operations when only that one +operation exists in the document. For example the following document is valid: diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index d0de0ed2d..5bde7a6c1 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -92,9 +92,9 @@ result to avoid validating the same request again in the future. ### Coercing Variable Values If the operation has defined any variables, then the values for those variables -need to be coerced using the input coercion rules of variable's declared type. -If a _request error_ is encountered during input coercion of variable values, -then the operation fails without execution. +need to be coerced using the input coercion rules of the variable's declared +type. If a _request error_ is encountered during input coercion of variable +values, then the operation fails without execution. CoerceVariableValues(schema, operation, variableValues): diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index f79100cd2..4ece8639d 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -19,7 +19,7 @@ a query or mutation and the request included execution. Additionally, for each event in a subscription's _source stream_, the _response stream_ will emit an _execution result_. -An _execution result_ must be map. +An _execution result_ must be a map. The _execution result_ must contain an entry with key {"data"}. The value of this entry is described in the "Data" section. @@ -30,7 +30,7 @@ _execution error_ raised during execution. Each error must be a map as described in the "Errors" section below. If the request completed without raising any errors, this entry must not be present. -Note: When {"errors"} is present in a _execution result_, it may be helpful for +Note: When {"errors"} is present in an _execution result_, it may be helpful for it to appear first when serialized to make it more apparent that errors are present.