diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 92f222cb3..e75a0f5d4 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -133,6 +133,8 @@ lines and uniform indentation with {BlockStringValue()}. ## Document Syntax +Description : StringValue + Document : Definition+ Definition : @@ -149,7 +151,7 @@ ExecutableDefinition : OperationDefinition : -- OperationType Name? VariablesDefinition? Directives? SelectionSet +- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet - SelectionSet OperationType : one of `query` `mutation` `subscription` @@ -174,8 +176,8 @@ FragmentSpread : ... FragmentName Directives? InlineFragment : ... TypeCondition? Directives? SelectionSet -FragmentDefinition : fragment FragmentName TypeCondition Directives? -SelectionSet +FragmentDefinition : Description? fragment FragmentName TypeCondition +Directives? SelectionSet FragmentName : Name but not `on` @@ -213,7 +215,8 @@ ObjectField[Const] : Name : Value[?Const] VariablesDefinition : ( VariableDefinition+ ) -VariableDefinition : Variable : Type DefaultValue? Directives[Const]? +VariableDefinition : Description? Variable : Type DefaultValue? +Directives[Const]? Variable : $ Name @@ -268,8 +271,6 @@ SchemaExtension : RootOperationTypeDefinition : OperationType : NamedType -Description : StringValue - TypeDefinition : - ScalarTypeDefinition diff --git a/spec/Section 1 -- Overview.md b/spec/Section 1 -- Overview.md index b454b7c4d..c94c89a7b 100644 --- a/spec/Section 1 -- Overview.md +++ b/spec/Section 1 -- Overview.md @@ -63,10 +63,10 @@ GraphQL has a number of design principles: endpoints. A GraphQL response, on the other hand, contains exactly what a client asks for and no more. -- **Introspective**: GraphQL is introspective. A GraphQL service's type system - can be queryable by the GraphQL language itself, as will be described in this - specification. GraphQL introspection serves as a powerful platform for - building common tools and client software libraries. +- **Self-describing**: GraphQL is self-describing and introspective. A GraphQL + service's type system can be queryable by the GraphQL language itself, which + includes readable documentation. GraphQL introspection serves as a powerful + platform for building common developer tools and client software libraries. Because of these principles, GraphQL is a powerful and productive environment for building client applications. Product developers and designers building diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index a71cf041f..86efe1581 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -233,6 +233,57 @@ Any {Name} within a GraphQL type system must not start with two underscores {"\_\_"} unless it is part of the [introspection system](#sec-Introspection) as defined by this specification. +## Descriptions + +Description : StringValue + +Documentation is a first-class feature of GraphQL by including written +descriptions on all named definitions in executable {Document} and GraphQL type +systems, which is also made available via introspection ensuring the +documentation of a GraphQL service remains consistent with its capabilities (see +[Type System Descriptions](#sec-Type-System-Descriptions)). + +GraphQL descriptions are provided as Markdown (as specified by +[CommonMark](https://commonmark.org/)). Description strings (often +{BlockString}) occur immediately before the definition they describe. + +This is an example of a well-described operation: + +```graphql example +""" +Request the current status of a time machine and its operator. +You can also check the status for a particular year. +**Warning:** certain years may trigger an anomaly in the space-time continuum. +""" +query GetTimeMachineStatus( + "The unique serial number of the time machine to inspect." + $machineId: ID! + "The year to check the status for." + $year: Int +) { + timeMachine(id: $machineId) { + ...TimeMachineDetails + status(year: $year) + } +} + +"Details about a time machine and its operator." +fragment TimeMachineDetails on TimeMachine { + id + model + lastMaintenance + operator { + name + licenseLevel + } +} +``` + +Descriptions in GraphQL executable documents are purely for documentation +purposes. They MUST NOT affect the execution, validation, or response of a +GraphQL document. It is safe to remove all descriptions and comments from +executable documents without changing their behavior or results. + ## Document Document : Definition+ @@ -279,7 +330,7 @@ be executed must also be provided. OperationDefinition : -- OperationType Name? VariablesDefinition? Directives? SelectionSet +- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet - SelectionSet OperationType : one of `query` `mutation` `subscription` @@ -298,6 +349,10 @@ For example, this mutation operation might "like" a story and then retrieve the new number of likes: ```graphql example +""" +Mark story 12345 as "liked" +and return the updated number of likes on the story +""" mutation { likeStory(storyID: 12345) { story { @@ -322,6 +377,8 @@ For example, this unnamed query operation is written via query shorthand. } ``` +Descriptions are not permitted on query shorthand. + Note: many examples below will use the query short-hand syntax. ## Selection Sets @@ -523,8 +580,8 @@ which returns the result: FragmentSpread : ... FragmentName Directives? -FragmentDefinition : fragment FragmentName TypeCondition Directives? -SelectionSet +FragmentDefinition : Description? fragment FragmentName TypeCondition +Directives? SelectionSet FragmentName : Name but not `on` @@ -570,6 +627,7 @@ query withFragments { } } +"Common fields for a user's friends." fragment friendFields on User { id name @@ -1181,7 +1239,8 @@ Variable : $ Name VariablesDefinition : ( VariableDefinition+ ) -VariableDefinition : Variable : Type DefaultValue? Directives[Const]? +VariableDefinition : Description? Variable : Type DefaultValue? +Directives[Const]? DefaultValue : = Value[Const] @@ -1200,7 +1259,10 @@ In this example, we want to fetch a profile picture size based on the size of a particular device: ```graphql example -query getZuckProfile($devicePicSize: Int) { +query getZuckProfile( + "The size of the profile picture to fetch." + $devicePicSize: Int +) { user(id: 4) { id name diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index a3914d158..ec3d19b85 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -50,20 +50,16 @@ 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. -## Descriptions +## Type System Descriptions -Description : StringValue +Documentation is a first-class feature of GraphQL type systems, written +immediately alongside definitions in a {TypeSystemDocument} and made available +via introspection. -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. +[Descriptions](#sec-Descriptions) allow GraphQL service designers to easily +provide documentation which remains consistent with the capabilities of a +GraphQL service. Descriptions provided as Markdown (as specified by +[CommonMark](https://commonmark.org/)) for every definition in a type system. GraphQL schema and all other definitions (e.g. types, fields, arguments, etc.) which can be described should provide a {Description} unless they are considered diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index c77b73155..13606df18 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -33,6 +33,12 @@ Note: GraphQL requests do not require any specific serialization format or transport mechanism. Message serialization and transport mechanisms should be chosen by the implementing service. +Note: Descriptions and comments in executable documents (operation definitions, +fragment definitions, and variable definitions) MUST be ignored during execution +and have no effect on the observable execution, validation, or response of a +GraphQL document. Descriptions and comments on executable documents MAY be used +for non-observable purposes, such as logging and other developer tools. + ## Executing Requests To execute a request, the executor must have a parsed {Document} and a selected