diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 2283ae86d..068e82279 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -52,6 +52,7 @@ Note: GraphQL intentionally does not consider Unicode "Zs" category characters as white-space, avoiding misinterpretation by text editors and source control tools. + ### Line Terminators LineTerminator :: @@ -186,7 +187,7 @@ multiple operations to a GraphQL service, the name of the desired operation to be executed must also be provided. -### Operations +## Operations OperationDefinition : - OperationType Name? VariableDefinitions? Directives? SelectionSet @@ -231,7 +232,7 @@ For example, this unnamed query operation is written via query shorthand. Note: many examples below will use the query short-hand syntax. -### Selection Sets +## Selection Sets SelectionSet : { Selection+ } @@ -255,7 +256,8 @@ under-fetching data. In this query, the `id`, `firstName`, and `lastName` fields form a selection set. Selection sets may also contain fragment references. -### Fields + +## Fields Field : Alias? Name Arguments? Directives? SelectionSet? @@ -312,7 +314,7 @@ unique identifier. ``` -### Arguments +## Arguments Arguments : ( Argument+ ) @@ -367,7 +369,7 @@ These two queries are semantically identical: ``` -### Field Alias +## Field Alias Alias : Name : @@ -427,7 +429,7 @@ A field's response key is its alias if an alias is provided, and it is otherwise the field's name. -### Fragments +## Fragments FragmentSpread : ... FragmentName Directives? @@ -517,7 +519,8 @@ fragment standardProfilePic on User { The queries `noFragments`, `withFragments`, and `withNestedFragments` all produce the same response object. -#### Type Conditions + +### Type Conditions TypeCondition : on NamedType @@ -576,7 +579,8 @@ will be present and `friends` will not. } ``` -#### Inline Fragments + +### Inline Fragments InlineFragment : ... TypeCondition? Directives? SelectionSet @@ -622,7 +626,7 @@ query inlineFragmentNoType($expandedInfo: Boolean) { ``` -### Input Values +## Input Values Value[Const] : - [~Const] Variable @@ -640,7 +644,8 @@ input values can be scalars, enumeration values, lists, or input objects. If not defined as constant (for example, in {DefaultValue}), input values can be specified as a variable. List and inputs objects may also contain variables (unless defined to be constant). -#### Int Value + +### Int Value IntValue :: IntegerPart @@ -656,7 +661,8 @@ NonZeroDigit :: Digit but not `0` An Int number is specified without a decimal point or exponent (ex. `1`). -#### Float Value + +### Float Value FloatValue :: - IntegerPart FractionalPart @@ -674,13 +680,15 @@ Sign :: one of + - A Float number includes either a decimal point (ex. `1.0`) or an exponent (ex. `1e50`) or both (ex. `6.0221413e23`). -#### Boolean Value + +### Boolean Value BooleanValue : one of `true` `false` The two keywords `true` and `false` represent the two boolean values. -#### String Value + +### String Value StringValue :: - `""` @@ -728,7 +736,7 @@ StringCharacter :: \ EscapedCharacter * Return the character value of {EscapedCharacter}. -#### Enum Value +### Enum Value EnumValue : Name but not `true`, `false` or `null` @@ -740,7 +748,8 @@ necessary to supply an enumeration type name in the literal. An enum value cannot be "null" in order to avoid confusion. GraphQL does not supply a value literal to represent the concept {null}. -#### List Value + +### List Value ListValue[Const] : - [ ] @@ -766,7 +775,8 @@ ListValue : [ Value+ ] * Append {value} to {inputList}. * Return {inputList} -#### Input Object Values + +### Input Object Values ObjectValue[Const] : - { } @@ -814,7 +824,7 @@ ObjectValue : { ObjectField+ } * Return {inputObject} -### Variables +## Variables Variable : $ Name @@ -857,7 +867,7 @@ size `60` width: } ``` -#### Variable use within Fragments +** Variable use within Fragments ** Query variables can be used within fragments. Query variables have global scope with a given operation, so a variable used within a fragment must be declared @@ -866,7 +876,7 @@ a variable is referenced in a fragment and is included by an operation that does not define that variable, the operation cannot be executed. -### Input Types +## Input Types Type : - NamedType @@ -907,7 +917,7 @@ Type : Type ! * Return {type} -### Directives +## Directives Directives : Directive+ diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 247b559ba..09cf3f09b 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -22,6 +22,7 @@ any built in types (including Scalar and Introspection types). All directives within a GraphQL schema must have unique names. A directive and a type may share the same name, since there is no ambiguity between them. + ## Types The fundamental unit of any GraphQL Schema is the type. There are eight kinds @@ -59,6 +60,7 @@ Finally, oftentimes it is useful to provide complex structs as inputs to GraphQL queries; the `Input Object` type allows the schema to define exactly what data is expected from the client in these queries. + ### Scalars As expected by the name, a scalar represents a primitive value in GraphQL. @@ -113,13 +115,14 @@ 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 value. -#### Built-in Scalars +**Built-in Scalars** GraphQL provides a basic set of well-defined Scalar types. A GraphQL server should support all of these types, and a GraphQL server which provide a type by these names must adhere to the behavior described below. -##### Int + +#### Int The Int scalar type represents a signed 32-bit numeric non-fractional values. Response formats that support a 32-bit integer or a number type should use @@ -143,7 +146,8 @@ Note: Numeric integer values larger than 32-bit should either use String or a custom-defined Scalar type, as not all platforms and transports support encoding integer numbers larger than 32-bit. -##### Float + +#### Float The Float scalar type represents signed double-precision fractional values as specified by [IEEE 754](http://en.wikipedia.org/wiki/IEEE_floating_point). @@ -165,7 +169,8 @@ other input values, including strings with numeric content, must raise a query error indicating an incorrect type. If the integer input value represents a value not representable by IEEE 754, a query error should be raised. -##### String + +#### String The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form @@ -185,7 +190,8 @@ When expected as an input type, only valid UTF-8 string input values are accepted. All other input values must raise a query error indicating an incorrect type. -##### Boolean + +#### Boolean The Boolean scalar type represents `true` or `false`. Response formats should use a built-in boolean type if supported; otherwise, they should use their @@ -202,7 +208,8 @@ otherwise they must raise a field error. Examples of this may include returning When expected as an input type, only boolean input values are accepted. All other input values must raise a query error indicating an incorrect type. -##### ID + +#### ID The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type is serialized in the same way as @@ -444,6 +451,7 @@ executor, so this is covered in that section of the spec. Objects are never valid inputs. + #### Object Field Arguments Object fields are conceptually functions which yield values. Occasionally object @@ -484,6 +492,7 @@ May yield the result: The type of an object field argument can be any Input type. + #### Object Field deprecation Fields in an object may be marked as deprecated as deemed necessary by the @@ -491,6 +500,7 @@ application. It is still legal to query for these fields (to ensure existing clients are not broken by the change), but the fields should be appropriately treated in documentation and tooling. + #### Object type validation Object types have the potential to be invalid if incorrectly defined. This set @@ -618,6 +628,7 @@ is the same as the result coercion of the object. Interfaces are never valid inputs. + #### Interface type validation Interface types have the potential to be invalid if incorrectly defined. @@ -699,6 +710,7 @@ same as the result coercion of the object. Unions are never valid inputs. + #### Union type validation Union types have the potential to be invalid if incorrectly defined. @@ -793,6 +805,7 @@ the only item in the list. This is to allow inputs that accept a "var args" to declare their input type as a list; if only one argument is passed (a common case), the client can just pass that value rather than constructing the list. + ### Non-Null By default, all types in GraphQL are nullable; the {null} value is a valid @@ -858,6 +871,7 @@ engine supports. GraphQL implementations should provide the `@skip` and `@include` directives. + ### @skip The `@skip` directive may be provided for fields, fragment spreads, and @@ -873,6 +887,7 @@ query myQuery($someTest: Boolean) { } ``` + ### @include The `@include` directive may be provided for fields, fragment spreads, and @@ -891,7 +906,7 @@ query myQuery($someTest: Boolean) { In the case that both the `@skip` and `@include` directives are provided in the same context, the field or fragment *must* be queried only if the `@skip` condition is false *and* the `@include` condition is true. Stated conversely, the field/fragment must *not* be queried if either the `@skip` condition is true *or* the `@include` condition is false. -## Starting types +## Initial types A GraphQL schema includes types, indicating where query and mutation operations start. This provides the initial entry points into the diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index f6c116c91..337e3948e 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -56,8 +56,10 @@ would return } ``` + ## General Principles + ### Naming conventions Types and fields required by the GraphQL introspection system that are used in @@ -67,6 +69,7 @@ types. Conversely, GraphQL type system authors must not define any types, fields, arguments, or any other type system artifact with two leading underscores. + ### Documentation All types in the introspection system provide a `description` field of type @@ -75,6 +78,7 @@ capabilities. A GraphQL server may return the `description` field using Markdown syntax. Therefore it is recommended that any tool that displays description use a Markdown renderer. + ### Deprecation To support the management of backwards compatibility, GraphQL fields and enum @@ -85,6 +89,7 @@ Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer-facing warnings. + ### Type Name Introspection GraphQL supports type name introspection at any point within a query by the @@ -96,6 +101,7 @@ identify which actual type of the possible types has been returned. This field is implicit and does not appear in the fields list in any defined type. + ## Schema Introspection The schema introspection system is accessible from the meta-fields `__schema` @@ -197,7 +203,7 @@ enum __DirectiveLocation { ``` -### The "__Type" Type +### The __Type Type `__Type` is at the core of the type introspection system. It represents scalars, interfaces, object types, unions, enums in the system. @@ -206,11 +212,13 @@ It represents scalars, interfaces, object types, unions, enums in the system. that it refers to (`ofType: __Type`). This is how we represent lists, non-nullable types, and the combinations thereof. + ### Type Kinds There are several different kinds of type. In each kind, different fields are actually valid. These kinds are listed in the `__TypeKind` enumeration. + #### Scalar Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. @@ -225,6 +233,7 @@ Fields * `description` may return a String or {null}. * All other fields must return {null}. + #### Object Object types represent concrete instantiations of sets of fields. The @@ -241,6 +250,7 @@ Fields * `interfaces`: The set of interfaces that an object implements. * All other fields must return {null}. + #### Union Unions are an abstract types where no common fields are declared. The possible @@ -256,6 +266,7 @@ Fields union. They must be object types. * All other fields must return {null}. + #### Interface Interfaces is an abstract type where there are common fields declared. Any type @@ -275,6 +286,7 @@ Fields They must be object types. * All other fields must return {null}. + #### Enum Enums are special scalars that can only have a defined set of values. @@ -290,6 +302,7 @@ Fields {true}, deprecated enum values are also returned. * All other fields must return {null}. + #### Input Object Input objects are composite types used as inputs into queries defined as a list @@ -312,6 +325,7 @@ Fields * `inputFields`: a list of `InputValue`. * All other fields must return {null}. + #### List Lists represent sequences of values in GraphQL. A List type is a type modifier: @@ -324,7 +338,8 @@ Fields * `ofType`: Any type. * All other fields must return {null}. -#### Non-null + +#### Non-Null GraphQL types are nullable. The value {null} is a valid response for field type. @@ -336,6 +351,7 @@ required inputs for arguments and input object fields. * `ofType`: Any type except Non-null. * All other fields must return {null}. + #### Combining List and Non-Null List and Non-Null can compose, representing more complex types. diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index fccc5d54e..7a721efc8 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -65,6 +65,7 @@ type QueryRoot { } ``` + ## Operations ### Named Operation Definitions @@ -180,6 +181,7 @@ query getName { } ``` + ## Fields ### Field Selections on Objects, Interfaces, and Unions Types @@ -255,6 +257,7 @@ fragment directFieldSelectionOnUnion on CatOrDog { } ``` + ### Field Selection Merging ** Formal Specification ** @@ -366,6 +369,7 @@ fragment safeDifferingArgs on Pet { } ``` + ### Leaf Field Selections ** Formal Specification ** @@ -430,11 +434,13 @@ query directQueryOnUnionWithoutSubFields { } ``` + ## Arguments Arguments are provided to both fields and directives. The following validation rules apply in both cases. + ### Argument Names ** Formal Specification ** @@ -507,6 +513,7 @@ fragment multipleArgsReverseOrder on Arguments { } ``` + ### Argument Uniqueness Fields and directives treat arguments as a mapping of argument name to value. @@ -520,6 +527,7 @@ and invalid. * Let {arguments} be all Arguments named {argumentName} in the Argument Set which contains {argument}. * {arguments} must be the set containing only {argument}. + ### Argument Values Type Correctness #### Compatible Values @@ -560,6 +568,7 @@ fragment stringIntoInt on Arguments { } ``` + #### Required Arguments * For each Field or Directive in the document. @@ -607,6 +616,7 @@ fragment missingRequiredArg on Arguments { } ``` + ## Fragments ### Fragment Declarations @@ -669,6 +679,7 @@ fragment fragmentOne on Dog { } ``` + #### Fragment Spread Type Existence ** Formal Specification ** @@ -717,6 +728,7 @@ fragment inlineNotExistingType on Dog { } ``` + #### Fragments On Composite Types ** Formal Specification ** @@ -763,6 +775,7 @@ fragment inlineFragOnScalar on Dog { } ``` + #### Fragments Must Be Used ** Formal Specification ** @@ -788,6 +801,7 @@ fragment nameFragment on Dog { # unused } ``` + ### Fragment Spreads Field selection is also determined by spreading fragments into one @@ -795,6 +809,7 @@ another. The selection set of the target fragment is unioned with the selection set at the level at which the target fragment is referenced. + #### Fragment spread target defined ** Formal Specification ** @@ -817,6 +832,7 @@ not defined, this is an error: } ``` + #### Fragment spreads must not form cycles ** Formal Specification ** @@ -901,6 +917,7 @@ fragment ownerFragment on Dog { } ``` + #### Fragment spread is possible ** Formal Specification ** @@ -926,6 +943,7 @@ 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 In the scope of an object type, the only valid object type @@ -952,6 +970,7 @@ fragment catInDogFragmentInvalid on Dog { } ``` + ##### Abstract Spreads in Object Scope In scope of an object type, unions or interface spreads can be used @@ -991,6 +1010,7 @@ you could note that the 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 Union or interface spreads can be used within the context of an object type @@ -1039,6 +1059,7 @@ fragment humanOrAlienFragment on HumanOrAlien { is invalid. Likewise {Cat} is not a member of the union {HumanOrAlien}, and it can also never return meaningful results, making it invalid. + ##### Abstract Spreads in Abstract Scope Union or interfaces fragments can be used within each other. As long as there @@ -1077,8 +1098,10 @@ fragment sentientFragment on Sentient { is not valid because there exists no type that implements both {Pet} and {Sentient}. + ## Values + ### Input Object Field Uniqueness ** Formal Specification ** @@ -1102,8 +1125,10 @@ For example the following query will not pass validation. } ``` + ## Directives + ### Directives Are Defined ** Formal Specification ** @@ -1257,6 +1282,7 @@ query intToFloatQuery($floatVar: Float = 1) { } ``` + ### Variables Are Input Types ** Formal Specification ** @@ -1325,6 +1351,7 @@ query takesCatOrDog($catOrDog: CatOrDog) { } ``` + ### All Variable Uses Defined ** Formal Specification ** @@ -1467,6 +1494,7 @@ This is because {housetrainedQueryTwoNotDefined} does not define a variable ${atOtherHomes} but that variable is used by {isHousetrainedFragment} which is included in that operation. + ### All Variables Used ** Formal Specification ** @@ -1549,6 +1577,7 @@ fragment isHousetrainedFragment on Dog { This document is not valid because {queryWithExtraVar} defines an extraneous variable. + ### All Variable Usages are Allowed ** Formal Specification ** diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index fbbc83c68..7ba029ac3 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -2,6 +2,7 @@ This section describes how GraphQL generates a response from a request. + ## Evaluating requests To evaluate a request, the executor must have a parsed `Document` (as defined @@ -14,7 +15,8 @@ error. If the operation is found, then the result of evaluating the request should be the result of evaluating the operation according to the “Evaluating operations” section. -## Coercing Variables + +## 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 @@ -22,6 +24,7 @@ of variable's declared type. If a query error is encountered during input coercion of variable values, then the operation fails without execution. + ## Evaluating operations The type system, as described in the “Type System” part of the spec, must @@ -34,6 +37,7 @@ object. This selection set should be evaluated serially. If the operation is a query, the result of the operation is the result of evaluating the query’s top level selection set on the “Query Root” object. + ## Evaluating selection sets To evaluate a selection set, the executor needs to know the object on which it @@ -110,6 +114,7 @@ corresponding grouped field set. The corresponding grouped field set should be evaluated serially if the selection set is being evaluated serially, otherwise it should be evaluated normally. + ## Evaluating a grouped field set The result of evaluating a grouped field set will be an ordered map. For each @@ -117,6 +122,7 @@ item in the grouped field set, an entry is added to the resulting ordered map, where the key is the response key shared by all fields for that entry, and the value is the result of evaluating those fields. + ### Field entries Each item in the grouped field set can potentially create an entry in the @@ -199,6 +205,7 @@ ResolveAbstractType(abstractType, objectValue): system for determining the Object type of {abstractType} given the value {objectValue}. + ### Normal evaluation When evaluating a grouped field set without a serial execution order requirement, @@ -224,6 +231,7 @@ For example, given the following grouped field set to be evaluated normally: A valid GraphQL executor can resolve the four fields in whatever order it chose. + ### Serial execution Observe that based on the above sections, the only time an executor will run in @@ -298,12 +306,14 @@ A correct executor must generate the following result for that selection set: } ``` + ### Error handling If an error occurs when resolving a field, it should be treated as though the field returned null, and an error must be added to the "errors" list in the response. + ### Nullability If the result of resolving a field is null (either because the function to diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index e55c1a50f..14c950cf7 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -8,6 +8,7 @@ request. A response may contain both a partial response as well as encountered errors in the case that an error occurred on a field which was replaced with null. + ## Serialization Format GraphQL does not require a specific serialization format. However, clients @@ -32,6 +33,7 @@ may be used as a substitute for those primitives. * Float * Enum Value + ### JSON Serialization JSON is the preferred serialization format for GraphQL, though as noted above, @@ -52,6 +54,7 @@ the following JSON concepts: | Enum Value | String | + ## Response Format A response to a GraphQL operation must be a map. @@ -75,6 +78,7 @@ To ensure future changes to the protocol do not break existing servers and clients, the top level response map must not contain any entries other than the three described above. + ### Data The `data` entry in the response will be the result of the execution of the @@ -88,6 +92,7 @@ not be present in the result. If an error was encountered during the execution that prevented a valid response, the `data` entry in the response should be `null`. + ### Errors The `errors` entry in the response is a non-empty list of errors, where each