From 6916e89d2c6d7b7c7113e29cad5f625d10d831d8 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 4 Oct 2023 16:43:49 +0200 Subject: [PATCH 1/4] introduce source schema document and full schema document --- spec/Appendix B -- Grammar Summary.md | 16 ++--- spec/Section 2 -- Language.md | 94 +++++++++++++++++++++++++-- spec/Section 3 -- Type System.md | 78 ++-------------------- 3 files changed, 103 insertions(+), 85 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 92f222cb3..d7e835110 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -238,7 +238,12 @@ Directives[Const] : Directive[?Const]+ Directive[Const] : @ Name Arguments[?Const]? -TypeSystemDocument : TypeSystemDefinition+ +SourceSchemaDocument : TypeSystemDefinitionOrExtension+ + +TypeSystemDefinitionOrExtension : + +- TypeSystemDefinition +- TypeSystemExtension TypeSystemDefinition : @@ -246,18 +251,13 @@ TypeSystemDefinition : - TypeDefinition - DirectiveDefinition -TypeSystemExtensionDocument : TypeSystemDefinitionOrExtension+ - -TypeSystemDefinitionOrExtension : - -- TypeSystemDefinition -- TypeSystemExtension - 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..820614ca0 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. + +All _built-in definitions_ must be included in a {SourceSchemaDocument}. + +A {SourceSchemaDocument} must exactly 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..53e54bc8b 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 must 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 From 58a3a7506425adb7625647c56bba51f4c3a606e0 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 5 Oct 2023 16:18:57 +0200 Subject: [PATCH 2/4] keep TypeSystemDocument and TypeSystemExtensionDocument, make everything additive for now --- spec/Appendix B -- Grammar Summary.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index d7e835110..a842e4b62 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -238,12 +238,7 @@ Directives[Const] : Directive[?Const]+ Directive[Const] : @ Name Arguments[?Const]? -SourceSchemaDocument : TypeSystemDefinitionOrExtension+ - -TypeSystemDefinitionOrExtension : - -- TypeSystemDefinition -- TypeSystemExtension +TypeSystemDocument : TypeSystemDefinition+ TypeSystemDefinition : @@ -251,6 +246,15 @@ TypeSystemDefinition : - TypeDefinition - DirectiveDefinition +TypeSystemExtensionDocument : TypeSystemDefinitionOrExtension+ + +SourceSchemaDocument : TypeSystemDefinitionOrExtension+ + +TypeSystemDefinitionOrExtension : + +- TypeSystemDefinition +- TypeSystemExtension + TypeSystemExtension : - SchemaExtension From 65c9e4109321381369b6ea16fd85ba644b1f70b0 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 20 Nov 2023 18:49:54 +0100 Subject: [PATCH 3/4] Update spec/Section 3 -- Type System.md Co-authored-by: Matt Mahoney --- spec/Section 3 -- Type System.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 53e54bc8b..3321d357b 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -130,7 +130,7 @@ 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 must include at most one {SchemaDefinition}. +A document may include at most one {SchemaDefinition}. ### Root Operation Types From 00a3f3ab6fa14527d231d0ea4c928af03474c4d0 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 20 Nov 2023 18:52:42 +0100 Subject: [PATCH 4/4] code review --- spec/Section 2 -- Language.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 820614ca0..56f8b5b20 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -353,11 +353,11 @@ 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. +to validate an operation, generate code, provide IDE features and other tooling. -All _built-in definitions_ must be included in a {SourceSchemaDocument}. +All _built-in definitions_ must be included in a {FullSchemaDocument}. -A {SourceSchemaDocument} must exactly one {SchemaDefinition}. That +A {FullSchemaDocument} must exactly include one {SchemaDefinition}. That {SchemaDefinition} must include a _root operation type definition_ for each supported operation.