diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index e65d84ed2..a0ab1494f 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -218,7 +218,7 @@ TypeSystemExtension : - SchemaExtension - TypeExtension -SchemaDefinition : schema Directives[Const]? { RootOperationTypeDefinition+ } +SchemaDefinition : Description? schema Directives[Const]? { RootOperationTypeDefinition+ } SchemaExtension : - extend schema Directives[Const]? { RootOperationTypeDefinition+ } diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 166db9632..e68ae473c 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -38,9 +38,73 @@ 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. +## Descriptions + +Description : StringValue + +Documentation is a first-class feature of GraphQL type systems. To ensure +the documentation of a GraphQL service remains consistent with its capabilities, +descriptions of GraphQL definitions are provided alongside their definitions and +made available via introspection. + +To allow GraphQL service designers to easily publish documentation alongside the +capabilities of a GraphQL service, GraphQL descriptions are defined using the +Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). In the +type system definition language, these description strings (often {BlockString}) +occur immediately before the definition they describe. + +GraphQL schema and all other definitions (e.g. types, fields, arguments, etc.) +which can be described should provide a {Description} unless they are considered +self descriptive. + +As an example, this simple GraphQL schema is well described: + +```graphql example +""" +A simple GraphQL schema which is well described. +""" +schema { + query: Query +} + +""" +Root type for all your queries +""" +type Query { + """ + Translates a string from a given language into a different language. + """ + translate( + "The original language that `text` is provided in." + fromLanguage: Language + + "The translated language to be returned." + toLanguage: Language + + "The text to be translated." + text: String + ): String +} + +""" +The set of languages supported by `translate`. +""" +enum Language { + "English" + EN + + "French" + FR + + "Chinese" + CH +} +``` + + ## Schema -SchemaDefinition : schema Directives[Const]? { RootOperationTypeDefinition+ } +SchemaDefinition : Description? schema Directives[Const]? { RootOperationTypeDefinition+ } RootOperationTypeDefinition : OperationType : NamedType @@ -169,63 +233,6 @@ Schema extensions have the potential to be invalid if incorrectly defined. original Schema. -## Descriptions - -Description : StringValue - -Documentation is a first-class feature of GraphQL type systems. To ensure -the documentation of a GraphQL service remains consistent with its capabilities, -descriptions of GraphQL definitions are provided alongside their definitions and -made available via introspection. - -To allow GraphQL service designers to easily publish documentation alongside the -capabilities of a GraphQL service, GraphQL descriptions are defined using the -Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). In the -type system definition language, these description strings (often {BlockString}) -occur immediately before the definition they describe. - -All GraphQL types, fields, arguments and other definitions which can be -described should provide a {Description} unless they are considered self -descriptive. - -As an example, this simple GraphQL schema is well described: - -```graphql example -""" -A simple GraphQL schema which is well described. -""" -type Query { - """ - Translates a string from a given language into a different language. - """ - translate( - "The original language that `text` is provided in." - fromLanguage: Language - - "The translated language to be returned." - toLanguage: Language - - "The text to be translated." - text: String - ): String -} - -""" -The set of languages supported by `translate`. -""" -enum Language { - "English" - EN - - "French" - FR - - "Chinese" - CH -} -``` - - ## Types TypeDefinition : diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index d2f85c55c..d1920cc63 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -117,6 +117,7 @@ The schema of the GraphQL schema introspection system: ```graphql type __Schema { + description: String types: [__Type!]! queryType: __Type! mutationType: __Type