diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 92f222cb3..a842e4b62 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -248,6 +248,8 @@ TypeSystemDefinition : TypeSystemExtensionDocument : TypeSystemDefinitionOrExtension+ +SourceSchemaDocument : TypeSystemDefinitionOrExtension+ + TypeSystemDefinitionOrExtension : - TypeSystemDefinition @@ -258,6 +260,8 @@ TypeSystemExtension : - SchemaExtension - TypeExtension +FullSchemaDocument : TypeSystemDefinition+ + SchemaDefinition : Description? schema Directives[Const]? { RootOperationTypeDefinition+ } diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 3ac7c7e60..56f8b5b20 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -242,6 +242,12 @@ Definition : - ExecutableDefinition - TypeSystemDefinitionOrExtension +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. + +### Executable document + ExecutableDocument : ExecutableDefinition+ ExecutableDefinition : @@ -249,10 +255,6 @@ ExecutableDefinition : - OperationDefinition - FragmentDefinition -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. - Documents are only executable by a GraphQL service if they are {ExecutableDocument} and contain at least one {OperationDefinition}. A Document which contains {TypeSystemDefinitionOrExtension} must not be executed; GraphQL @@ -275,6 +277,90 @@ 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. +### Source schema document + +SourceSchemaDocument : TypeSystemDefinitionOrExtension+ + +TypeSystemDefinitionOrExtension : + +- TypeSystemDefinition +- TypeSystemExtension + +TypeSystemDefinition : + +- SchemaDefinition +- TypeDefinition +- DirectiveDefinition + +A {SourceSchemaDocument} describes the user types of a schema. A GraphQL +implementation may use a {SourceSchemaDocument} as input to represent the schema +and execute operations. + +For brevity, and to avoid conflicting with the implementation, all _built-in +definitions_ must be omitted in a {SourceSchemaDocument}. + +**Default Root Operation Type Names** + +:: The _default root type name_ for each {`query`}, {`mutation`}, and +{`subscription`} _root operation type_ are {"Query"}, {"Mutation"}, and +{"Subscription"} respectively. + +The type system definition language can omit the schema definition when each +_root operation type_ uses its respective _default root type name_ and no other +type uses any _default root type name_. + +Likewise, when part of a {SourceSchemaDocument}, a schema definition should be +omitted if each _root operation type_ uses its respective _default root type +name_ and no other type uses any _default root type name_. + +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. + +```graphql example +type Query { + someField: String +} +``` + +This example describes a valid GraphQL schema without a {`mutation`} _root +operation type_, even though it contains a type named {"Mutation"}. The schema +definition must be included, otherwise the {"Mutation"} type would be +incorrectly presumed to be the {`mutation`} _root operation type_ of the schema. + +```graphql example +schema { + query: Query +} + +type Query { + latestVirus: Virus +} + +type Virus { + name: String + mutations: [Mutation] +} + +type Mutation { + name: String +} +``` + +### Full schema document + +FullSchemaDocument : TypeSystemDefinition+ + +A {FullSchemaDocument} describes all the types in the schema, including the +built-in ones. Tools that are not implementations may use a {FullSchemaDocument} +to validate an operation, generate code, provide IDE features and other tooling. + +All _built-in definitions_ must be included in a {FullSchemaDocument}. + +A {FullSchemaDocument} must exactly include one {SchemaDefinition}. That +{SchemaDefinition} must include a _root operation type definition_ for each +supported operation. + ## Operations OperationDefinition : diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index d32b08566..3321d357b 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -5,8 +5,6 @@ used to determine if a requested operation is valid, to guarantee the type of response results, and describes the input types of variables to determine if values provided at request time are valid. -TypeSystemDocument : TypeSystemDefinition+ - TypeSystemDefinition : - SchemaDefinition @@ -21,7 +19,7 @@ to provide utilities such as client code generation or service boot-strapping. GraphQL tools or services which only seek to execute GraphQL requests and not construct a new GraphQL schema may choose not to allow {TypeSystemDefinition}. Tools which only seek to produce schema and not execute requests may choose to -only allow {TypeSystemDocument} and not allow {ExecutableDefinition} or +only allow {TypeSystemDefinition} and not allow {ExecutableDefinition} or {TypeSystemExtension} but should provide a descriptive error if present. Note: The type system definition language is used throughout the remainder of @@ -29,13 +27,6 @@ this specification document when illustrating example type systems. ## Type System Extensions -TypeSystemExtensionDocument : TypeSystemDefinitionOrExtension+ - -TypeSystemDefinitionOrExtension : - -- TypeSystemDefinition -- TypeSystemExtension - TypeSystemExtension : - SchemaExtension @@ -47,8 +38,8 @@ a local service to represent data a GraphQL client only accesses locally, or by a GraphQL service which is itself an extension of another GraphQL service. Tools which only seek to produce and extend schema and not execute requests may -choose to only allow {TypeSystemExtensionDocument} and not allow -{ExecutableDefinition} but should provide a descriptive error if present. +choose to only allow {TypeSystemDefinition} and {TypeSystemExtension} and not +allow {ExecutableDefinition} but should provide a descriptive error if present. ## Descriptions @@ -139,6 +130,8 @@ All types and directives defined within a schema must not have a name which begins with {"\_\_"} (two underscores), as this is used exclusively by GraphQL's introspection system. +A document may include at most one {SchemaDefinition}. + ### Root Operation Types :: A schema defines the initial _root operation type_ for each kind of operation @@ -189,9 +182,6 @@ mutation { } ``` -When using the type system definition language, a document must include at most -one {`schema`} definition. - In this example, a GraphQL schema is defined with both a query and mutation _root operation type_: @@ -210,55 +200,6 @@ type MyMutationRootType { } ``` -**Default Root Operation Type Names** - -:: The _default root type name_ for each {`query`}, {`mutation`}, and -{`subscription`} _root operation type_ are {"Query"}, {"Mutation"}, and -{"Subscription"} respectively. - -The type system definition language can omit the schema definition when each -_root operation type_ uses its respective _default root type name_ and no other -type uses any _default root type name_. - -Likewise, when representing a GraphQL schema using the type system definition -language, a schema definition should be omitted if each _root operation type_ -uses its respective _default root type name_ and no other type uses any _default -root type name_. - -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. - -```graphql example -type Query { - someField: String -} -``` - -This example describes a valid GraphQL schema without a {`mutation`} _root -operation type_, even though it contains a type named {"Mutation"}. The schema -definition must be included, otherwise the {"Mutation"} type would be -incorrectly presumed to be the {`mutation`} _root operation type_ of the schema. - -```graphql example -schema { - query: Query -} - -type Query { - latestVirus: Virus -} - -type Virus { - name: String - mutations: [Mutation] -} - -type Mutation { - name: String -} -``` - ### Schema Extension SchemaExtension : @@ -407,9 +348,6 @@ referenced built-in scalars must be included. If a built-in scalar type is not referenced anywhere in a schema (there is no field, argument, or input field of that type) then it must not be included. -When representing a GraphQL schema using the type system definition language, -all built-in scalars must be omitted for brevity. - **Custom Scalars** GraphQL services may use custom scalar types in addition to the built-in @@ -1949,12 +1887,6 @@ schema. GraphQL implementations that support the type system definition language should provide the `@specifiedBy` directive if representing custom scalar definitions. -When representing a GraphQL schema using the type system definition language any -_built-in directive_ may be omitted for brevity. - -When introspecting a GraphQL service all provided directives, including any -_built-in directive_, must be included in the set of returned directives. - **Custom Directives** :: GraphQL services and client tooling may provide any additional _custom