From 0b91f96465f43fa0b0865ca2877f34d63388c03b Mon Sep 17 00:00:00 2001 From: Ivan Goncharov Date: Wed, 13 Jun 2018 14:24:20 +0200 Subject: [PATCH 1/2] Move description section --- spec/Section 3 -- Type System.md | 114 +++++++++++++++---------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 5cbcb3be8..f34c055f3 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -38,6 +38,63 @@ 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. + +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 +} +``` + + ## Schema SchemaDefinition : schema Directives[Const]? { RootOperationTypeDefinition+ } @@ -169,63 +226,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 : From d034049d5b332238bea5644a1b527aff9efe4272 Mon Sep 17 00:00:00 2001 From: Ivan Goncharov Date: Wed, 13 Jun 2018 14:29:49 +0200 Subject: [PATCH 2/2] Add description to Schema --- spec/Appendix B -- Grammar Summary.md | 2 +- spec/Section 3 -- Type System.md | 15 +++++++++++---- spec/Section 4 -- Introspection.md | 1 + 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 0aff20f0e..3fa05e935 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 f34c055f3..3f8e8baea 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -53,9 +53,9 @@ 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. +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: @@ -63,6 +63,13 @@ As an example, this simple GraphQL schema is well described: """ 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. @@ -97,7 +104,7 @@ enum Language { ## Schema -SchemaDefinition : schema Directives[Const]? { RootOperationTypeDefinition+ } +SchemaDefinition : Description? schema Directives[Const]? { RootOperationTypeDefinition+ } RootOperationTypeDefinition : OperationType : NamedType 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