From 5517373bab027c6fb5ec63e19df88eb7018e5271 Mon Sep 17 00:00:00 2001 From: Ivan Goncharov Date: Thu, 7 Oct 2021 19:15:34 +0300 Subject: [PATCH 01/14] Add descriptions to executable definitions --- spec/Appendix B -- Grammar Summary.md | 10 +++++----- spec/Section 2 -- Language.md | 13 +++++++++++++ 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 92f222cb3..8f681fe5e 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -147,9 +147,11 @@ ExecutableDefinition : - OperationDefinition - FragmentDefinition +Description : StringValue + OperationDefinition : -- OperationType Name? VariablesDefinition? Directives? SelectionSet +- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet - SelectionSet OperationType : one of `query` `mutation` `subscription` @@ -174,7 +176,7 @@ FragmentSpread : ... FragmentName Directives? InlineFragment : ... TypeCondition? Directives? SelectionSet -FragmentDefinition : fragment FragmentName TypeCondition Directives? +FragmentDefinition : Description? fragment FragmentName TypeCondition Directives? SelectionSet FragmentName : Name but not `on` @@ -213,7 +215,7 @@ ObjectField[Const] : Name : Value[?Const] VariablesDefinition : ( VariableDefinition+ ) -VariableDefinition : Variable : Type DefaultValue? Directives[Const]? +VariableDefinition : Description? Variable : Type DefaultValue? Directives[Const]? Variable : $ Name @@ -268,8 +270,6 @@ SchemaExtension : RootOperationTypeDefinition : OperationType : NamedType -Description : StringValue - TypeDefinition : - ScalarTypeDefinition diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index a71cf041f..0a67da057 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -275,6 +275,19 @@ 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. +## Descriptions + +Description : StringValue + +Documentation is a first-class feature of GraphQL. +GraphQL descriptions are defined using the Markdown syntax (as specified by +[CommonMark](https://commonmark.org/)). Description strings (often {BlockString}) +occur immediately before the definition they describe. + +GraphQL definitions (e.g. queries, fragments, types, fields, arguments, etc.) +which can be described should provide a {Description} unless they are considered +self descriptive. + ## Operations OperationDefinition : From 9f7ec6371e6bc7c640270427a7b97a3306c41f15 Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Thu, 5 Jun 2025 15:40:44 -0700 Subject: [PATCH 02/14] Updated spec wording for descriptions in executable documents - Expanded the "Descriptions" section to clarify that descriptions may appear before operation definitions (full form only), fragment definitions, and variable definitions, but not on the shorthand form of operations. - Updated grammar summary and relevant sections to permit descriptions in these locations. - Added a normative note that descriptions and comments do not affect execution, validation, or response, and are safe to remove from executable documents. - Clarified and consolidated description rules in the type system section, referencing the normative rules in the language section and removing redundant statements. - Updated execution section to include a clear normative note about ignoring descriptions and comments during execution. - Ensured all changes are cross-referenced and consistent across the specification. --- spec/Appendix B -- Grammar Summary.md | 7 +-- spec/Section 2 -- Language.md | 66 +++++++++++++++++++++++---- spec/Section 3 -- Type System.md | 3 ++ spec/Section 6 -- Execution.md | 6 +++ 4 files changed, 71 insertions(+), 11 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 8f681fe5e..049ff7d4f 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/spec/Appendix B -- Grammar Summary.md @@ -176,8 +176,8 @@ FragmentSpread : ... FragmentName Directives? InlineFragment : ... TypeCondition? Directives? SelectionSet -FragmentDefinition : Description? fragment FragmentName TypeCondition Directives? -SelectionSet +FragmentDefinition : Description? fragment FragmentName TypeCondition +Directives? SelectionSet FragmentName : Name but not `on` @@ -215,7 +215,8 @@ ObjectField[Const] : Name : Value[?Const] VariablesDefinition : ( VariableDefinition+ ) -VariableDefinition : Description? Variable : Type DefaultValue? Directives[Const]? +VariableDefinition : Description? Variable : Type DefaultValue? +Directives[Const]? Variable : $ Name diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 0a67da057..e2fa323a6 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -279,20 +279,70 @@ be executed must also be provided. Description : StringValue -Documentation is a first-class feature of GraphQL. -GraphQL descriptions are defined using the Markdown syntax (as specified by -[CommonMark](https://commonmark.org/)). Description strings (often {BlockString}) -occur immediately before the definition they describe. +Documentation is a first-class feature of GraphQL. GraphQL descriptions are +defined using the Markdown syntax (as specified by +[CommonMark](https://commonmark.org/)). Description strings (often +{BlockString}) occur immediately before the definition they describe. + +Descriptions may appear before: + +- Operation definitions (queries, mutations, subscriptions) in their full form + (not the shorthand form). +- Fragment definitions. +- Variable definitions within operation definitions. + +Descriptions are not permitted on the shorthand form of operations (e.g., +`{ ... }`). + +Note: Descriptions and comments in executable GraphQL 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. + +Example: + +```graphql +"Some description" +query SomeOperation( + "ID you should provide" + $id: String + + "Switch for experiment ...." + $enableBaz: Boolean = false, +) { + foo(id: $id) { + bar + baz @include(if: $enableBaz) { + ...BazInfo + } + } +} + +"Some description here" +fragment BazInfo on Baz { + # ... +} +``` + +Counterexample: -GraphQL definitions (e.g. queries, fragments, types, fields, arguments, etc.) -which can be described should provide a {Description} unless they are considered -self descriptive. +```graphql counter-example +"Descriptions are not permitted on the shorthand form of operations" +{ + foo { + bar + baz { + ...BazInfo + } + } +} +``` ## Operations OperationDefinition : -- OperationType Name? VariablesDefinition? Directives? SelectionSet +- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet - SelectionSet OperationType : one of `query` `mutation` `subscription` diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index a3914d158..746cc69f7 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -59,6 +59,9 @@ documentation of a GraphQL service remains consistent with its capabilities, descriptions of GraphQL definitions are provided alongside their definitions and made available via introspection. +Note: See Section 2, "Descriptions", for normative rules and additional details +on descriptions in executable documents. + 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 diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index c77b73155..7b86c785f 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 execution, validation, or response of a GraphQL +document. Descriptions and comments on executable documents MAY be used for +observability and logging purposes. + ## Executing Requests To execute a request, the executor must have a parsed {Document} and a selected From 1a1a4b381c2637c950a9e0f31892c247cbaa5b7f Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Thu, 5 Jun 2025 15:58:09 -0700 Subject: [PATCH 03/14] Add example label to GraphQL code block in Language section Enables the fancy formatting --- spec/Section 2 -- Language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index e2fa323a6..aaad09342 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -301,7 +301,7 @@ comments from executable documents without changing their behavior or results. Example: -```graphql +```graphql example "Some description" query SomeOperation( "ID you should provide" From 88c47a84e0f2f04321bf4ae931f8d7eaddd53b2b Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Wed, 11 Jun 2025 15:46:03 -0700 Subject: [PATCH 04/14] Refactor description section for clarity Also: - add color to operation description example and counter-example - add descriptions in operation examples throughout section 2 --- spec/Section 2 -- Language.md | 87 ++++++++++++++++++++++++----------- 1 file changed, 59 insertions(+), 28 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index aaad09342..0c70c5275 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -291,53 +291,76 @@ Descriptions may appear before: - Fragment definitions. - Variable definitions within operation definitions. -Descriptions are not permitted on the shorthand form of operations (e.g., -`{ ... }`). - -Note: Descriptions and comments in executable GraphQL 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. - Example: ```graphql example -"Some description" -query SomeOperation( - "ID you should provide" - $id: String +""" +Request the current status of a time machine and its operator. - "Switch for experiment ...." - $enableBaz: Boolean = false, +This operation retrieves the latest information about a specific time machine, +including its model, last maintenance date, and the operator currently assigned. + +You can also check the status for a particular year, to see if the time machine +was scheduled for travel or maintenance at that time. +""" +query GetTimeMachineStatus( + "The unique serial number of the time machine to inspect." + $machineId: ID! + + """ + The year to check the status for. + **Warning:** Requesting status information for certain years may trigger an anomaly in the space-time continuum. + """ + $year: Int ) { - foo(id: $id) { - bar - baz @include(if: $enableBaz) { - ...BazInfo + timeMachine(id: $machineId) { + ...TimeMachineDetails + operator { + ...OperatorDetails } + status(year: $year) } } -"Some description here" -fragment BazInfo on Baz { - # ... +""" +Time machine details. +""" +fragment TimeMachineDetails on TimeMachine { + id + model + lastMaintenance +} + +""" +Basic information about a time machine operator. +""" +fragment OperatorDetails on Operator { + name + licenseLevel } ``` -Counterexample: +Descriptions are not permitted on the shorthand form of operations: ```graphql counter-example -"Descriptions are not permitted on the shorthand form of operations" +"This description is invalid, because this is a shorthand operation definition" { - foo { - bar - baz { - ...BazInfo + timeMachine(id: "TM-1985") { + status + destination { + year + location } } } ``` +Note: Descriptions and comments in executable GraphQL 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. + + ## Operations OperationDefinition : @@ -361,6 +384,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 { @@ -633,6 +660,7 @@ query withFragments { } } +"""Common fields for a user's friends.""" fragment friendFields on User { id name @@ -1263,7 +1291,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 From f186ce71bd01d9e28514b09fcdd10d0b6d3a39c3 Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Wed, 11 Jun 2025 15:47:24 -0700 Subject: [PATCH 05/14] Add optional description to fragment and variable definitions --- spec/Section 2 -- Language.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 0c70c5275..3283a7218 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -613,8 +613,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` @@ -1272,7 +1272,8 @@ Variable : $ Name VariablesDefinition : ( VariableDefinition+ ) -VariableDefinition : Variable : Type DefaultValue? Directives[Const]? +VariableDefinition : Description? Variable : Type DefaultValue? +Directives[Const]? DefaultValue : = Value[Const] From 917505733dbbe668fe0d84072bb94bf78e4bec0d Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Wed, 11 Jun 2025 15:51:55 -0700 Subject: [PATCH 06/14] Prettier --- spec/Section 2 -- Language.md | 1 - 1 file changed, 1 deletion(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 3283a7218..b6f457d0b 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -360,7 +360,6 @@ 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. - ## Operations OperationDefinition : From 9af648090c17ae559d580a7a8f020736592b37c6 Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Wed, 11 Jun 2025 16:13:55 -0700 Subject: [PATCH 07/14] Refactor time machine status query documentation for clarity and conciseness --- spec/Section 2 -- Language.md | 28 +++++++++------------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index b6f457d0b..31fb2419c 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -300,43 +300,33 @@ Request the current status of a time machine and its operator. This operation retrieves the latest information about a specific time machine, including its model, last maintenance date, and the operator currently assigned. -You can also check the status for a particular year, to see if the time machine -was scheduled for travel or maintenance at that time. +You can also check the status for a particular year. + +**Warning:** certain years may trigger an anomaly in the space-time continuum. Use with caution! """ query GetTimeMachineStatus( "The unique serial number of the time machine to inspect." $machineId: ID! - - """ - The year to check the status for. - **Warning:** Requesting status information for certain years may trigger an anomaly in the space-time continuum. - """ + "The year to check the status for." $year: Int ) { timeMachine(id: $machineId) { ...TimeMachineDetails - operator { - ...OperatorDetails - } status(year: $year) } } """ -Time machine details. +Details about a time machine and its operator. """ fragment TimeMachineDetails on TimeMachine { id model lastMaintenance -} - -""" -Basic information about a time machine operator. -""" -fragment OperatorDetails on Operator { - name - licenseLevel + operator { + name + licenseLevel + } } ``` From 73c19c8a12d548e6c072956d9f9aadb77d37a1ab Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Wed, 11 Jun 2025 16:26:05 -0700 Subject: [PATCH 08/14] Reduced example --- spec/Section 2 -- Language.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 31fb2419c..dee6b1d43 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -291,18 +291,11 @@ Descriptions may appear before: - Fragment definitions. - Variable definitions within operation definitions. -Example: - ```graphql example """ Request the current status of a time machine and its operator. - -This operation retrieves the latest information about a specific time machine, -including its model, last maintenance date, and the operator currently assigned. - You can also check the status for a particular year. - -**Warning:** certain years may trigger an anomaly in the space-time continuum. Use with caution! +**Warning:** certain years may trigger an anomaly in the space-time continuum. """ query GetTimeMachineStatus( "The unique serial number of the time machine to inspect." @@ -316,9 +309,7 @@ query GetTimeMachineStatus( } } -""" -Details about a time machine and its operator. -""" +"Details about a time machine and its operator." fragment TimeMachineDetails on TimeMachine { id model From 6d7b259b52c528e2a4facf1c6c458e489a825456 Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Thu, 12 Jun 2025 10:08:49 -0700 Subject: [PATCH 09/14] Single quotes for single line description Co-authored-by: Glen --- spec/Section 2 -- Language.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index dee6b1d43..1128f6dd9 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -640,7 +640,7 @@ query withFragments { } } -"""Common fields for a user's friends.""" +"Common fields for a user's friends." fragment friendFields on User { id name @@ -1273,7 +1273,7 @@ particular device: ```graphql example query getZuckProfile( - """The size of the profile picture to fetch.""" + "The size of the profile picture to fetch." $devicePicSize: Int ) { user(id: 4) { From 22362752e004334bffc944238c6d3667f72febb1 Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Fri, 27 Jun 2025 18:38:16 -0700 Subject: [PATCH 10/14] Refactor descriptions text, incorporating feedback from working group --- spec/Section 2 -- Language.md | 60 +++++++++++++++++++++++++++++ spec/Section 3 -- Type System.md | 66 ++------------------------------ 2 files changed, 64 insertions(+), 62 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 1128f6dd9..752bff163 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -286,11 +286,67 @@ defined using the Markdown syntax (as specified by Descriptions may appear before: +**In type system definitions:** +- Schema definitions. +- Type definitions (scalars, objects, interfaces, unions, enums, input objects). +- Field definitions. +- Argument definitions. +- Enum value definitions. +- Input field definitions. +- Directive definitions. + +**In executable documents:** - Operation definitions (queries, mutations, subscriptions) in their full form (not the shorthand form). - Fragment definitions. - Variable definitions within operation definitions. +As an example, this simple GraphQL schema is well described: + +```raw graphql example +""" +A simple GraphQL schema which is well described. +""" +schema { + query: Query +} + +""" +Root type for all your query operations +""" +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 +} +``` + +This is an example of a well-described executable document: + ```graphql example """ Request the current status of a time machine and its operator. @@ -341,6 +397,10 @@ 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. +Descriptions in type system definitions are made available via introspection, +ensuring the documentation of a GraphQL service remains consistent with its +capabilities. + ## Operations OperationDefinition : diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 746cc69f7..51e79be00 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -50,71 +50,13 @@ 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. 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. -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. +Descriptions in the type system definition language occur immediately before the definition they describe and are made available via introspection, ensuring the documentation of a GraphQL service remains consistent with its capabilities. -Note: See Section 2, "Descriptions", for normative rules and additional details -on descriptions in executable documents. - -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: - -```raw graphql example -""" -A simple GraphQL schema which is well described. -""" -schema { - query: Query -} - -""" -Root type for all your query operations -""" -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 -} -``` +Note: See Section 2, "Descriptions", for normative rules and syntax details. Type system descriptions follow the same Markdown format and rules as executable document descriptions. ## Schema From b54fe84123d44f17482096e5ff760817a2b1cc26 Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Fri, 27 Jun 2025 18:39:15 -0700 Subject: [PATCH 11/14] formatting --- spec/Section 2 -- Language.md | 2 ++ spec/Section 3 -- Type System.md | 17 ++++++++++++----- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 752bff163..b41866632 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -287,6 +287,7 @@ defined using the Markdown syntax (as specified by Descriptions may appear before: **In type system definitions:** + - Schema definitions. - Type definitions (scalars, objects, interfaces, unions, enums, input objects). - Field definitions. @@ -296,6 +297,7 @@ Descriptions may appear before: - Directive definitions. **In executable documents:** + - Operation definitions (queries, mutations, subscriptions) in their full form (not the shorthand form). - Fragment definitions. diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 51e79be00..5a7cd27cf 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -52,11 +52,18 @@ choose to only allow {TypeSystemExtensionDocument} and not allow ## Type System Descriptions -Documentation is a first-class feature of GraphQL type systems. 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. - -Descriptions in the type system definition language occur immediately before the definition they describe and are made available via introspection, ensuring the documentation of a GraphQL service remains consistent with its capabilities. - -Note: See Section 2, "Descriptions", for normative rules and syntax details. Type system descriptions follow the same Markdown format and rules as executable document descriptions. +Documentation is a first-class feature of GraphQL type systems. 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. + +Descriptions in the type system definition language occur immediately before the +definition they describe and are made available via introspection, ensuring the +documentation of a GraphQL service remains consistent with its capabilities. + +Note: See Section 2, "Descriptions", for normative rules and syntax details. +Type system descriptions follow the same Markdown format and rules as executable +document descriptions. ## Schema From 07be572c1fa096335898461051d3b7a1f069312b Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Tue, 1 Jul 2025 10:23:08 -0700 Subject: [PATCH 12/14] Editorial: move descriptions definition above document --- spec/Appendix B -- Grammar Summary.md | 4 +- spec/Section 1 -- Overview.md | 8 +- spec/Section 2 -- Language.md | 103 +++++++++++++------------- 3 files changed, 59 insertions(+), 56 deletions(-) diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 049ff7d4f..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 : @@ -147,8 +149,6 @@ ExecutableDefinition : - OperationDefinition - FragmentDefinition -Description : StringValue - OperationDefinition : - Description? OperationType Name? VariablesDefinition? Directives? SelectionSet diff --git a/spec/Section 1 -- Overview.md b/spec/Section 1 -- Overview.md index b454b7c4d..451f8ea2f 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. +- **Introspective**: GraphQL is introspective and self-describing. 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 b41866632..e35549400 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -233,56 +233,20 @@ 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. -## Document - -Document : Definition+ - -Definition : - -- ExecutableDefinition -- TypeSystemDefinitionOrExtension - -ExecutableDocument : ExecutableDefinition+ - -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 -execution services which receive a Document containing these should return a -descriptive error. - -GraphQL services which only seek to execute GraphQL requests and not construct a -new GraphQL schema may choose to only permit {ExecutableDocument}. - -Documents which do not contain {OperationDefinition} or do contain -{TypeSystemDefinitionOrExtension} may still be parsed and validated to allow -client tools to represent many GraphQL uses which may appear across many -individual files. - -If a Document contains only one operation, that operation may be unnamed. If -that operation is a query without variables or directives then it may also be -represented in the shorthand form, omitting both the {`query`} keyword as well -as the operation name. Otherwise, if a GraphQL Document contains multiple -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. - ## Descriptions Description : StringValue -Documentation is a first-class feature of GraphQL. GraphQL descriptions are -defined using the Markdown syntax (as specified by +Documentation is a first-class feature of GraphQL by encouraging written +descriptions on all named definitions in both a GraphQL schema +{TypeSystemDocument} and an executable {Document}. GraphQL descriptions are +expected to provided as Markdown (as specified by [CommonMark](https://commonmark.org/)). Description strings (often -{BlockString}) occur immediately before the definition they describe. +{BlockString}) occur immediately before the named definition they describe. + +Descriptions in type system definitions are made available via introspection, +ensuring the documentation of a GraphQL service remains consistent with its +capabilities. Descriptions may appear before: @@ -396,12 +360,51 @@ Descriptions are not permitted on the shorthand form of operations: Note: Descriptions and comments in executable GraphQL 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. +response of a GraphQL document except for type and schema introspection. It is +otherwise safe to remove all descriptions and comments from executable documents +without changing their behavior or results. -Descriptions in type system definitions are made available via introspection, -ensuring the documentation of a GraphQL service remains consistent with its -capabilities. +## Document + +Document : Definition+ + +Definition : + +- ExecutableDefinition +- TypeSystemDefinitionOrExtension + +ExecutableDocument : ExecutableDefinition+ + +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 +execution services which receive a Document containing these should return a +descriptive error. + +GraphQL services which only seek to execute GraphQL requests and not construct a +new GraphQL schema may choose to only permit {ExecutableDocument}. + +Documents which do not contain {OperationDefinition} or do contain +{TypeSystemDefinitionOrExtension} may still be parsed and validated to allow +client tools to represent many GraphQL uses which may appear across many +individual files. + +If a Document contains only one operation, that operation may be unnamed. If +that operation is a query without variables or directives then it may also be +represented in the shorthand form, omitting both the {`query`} keyword as well +as the operation name. Otherwise, if a GraphQL Document contains multiple +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. ## Operations From 369dc2bbf81f40c75917754a0405b508b32be7b0 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Tue, 1 Jul 2025 10:47:15 -0700 Subject: [PATCH 13/14] editorial: move examples back to type system, add some links --- spec/Section 2 -- Language.md | 105 +++++-------------------------- spec/Section 3 -- Type System.md | 68 ++++++++++++++++---- 2 files changed, 70 insertions(+), 103 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index e35549400..67c376fd0 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -238,80 +238,16 @@ defined by this specification. Description : StringValue Documentation is a first-class feature of GraphQL by encouraging written -descriptions on all named definitions in both a GraphQL schema -{TypeSystemDocument} and an executable {Document}. GraphQL descriptions are -expected to provided as Markdown (as specified by -[CommonMark](https://commonmark.org/)). Description strings (often -{BlockString}) occur immediately before the named definition they describe. - -Descriptions in type system definitions are made available via introspection, -ensuring the documentation of a GraphQL service remains consistent with its -capabilities. - -Descriptions may appear before: - -**In type system definitions:** - -- Schema definitions. -- Type definitions (scalars, objects, interfaces, unions, enums, input objects). -- Field definitions. -- Argument definitions. -- Enum value definitions. -- Input field definitions. -- Directive definitions. - -**In executable documents:** - -- Operation definitions (queries, mutations, subscriptions) in their full form - (not the shorthand form). -- Fragment definitions. -- Variable definitions within operation definitions. - -As an example, this simple GraphQL schema is well described: - -```raw graphql example -""" -A simple GraphQL schema which is well described. -""" -schema { - query: Query -} - -""" -Root type for all your query operations -""" -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 -} +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)). -""" -The set of languages supported by `translate`. -""" -enum Language { - "English" - EN - - "French" - FR - - "Chinese" - CH -} -``` +GraphQL descriptions are expected to 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 executable document: +This is an example of a well-described operation: ```graphql example """ @@ -343,26 +279,11 @@ fragment TimeMachineDetails on TimeMachine { } ``` -Descriptions are not permitted on the shorthand form of operations: - -```graphql counter-example -"This description is invalid, because this is a shorthand operation definition" -{ - timeMachine(id: "TM-1985") { - status - destination { - year - location - } - } -} -``` - -Note: Descriptions and comments in executable GraphQL documents are purely for +Descriptions and comments in executable GraphQL documents are purely for documentation purposes. They MUST NOT affect the execution, validation, or -response of a GraphQL document except for type and schema introspection. It is -otherwise safe to remove all descriptions and comments from executable documents -without changing their behavior or results. +response of a GraphQL document except for type introspection. It is otherwise +safe to remove all descriptions and comments from executable documents without +changing their behavior or results. ## Document @@ -457,6 +378,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 diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 5a7cd27cf..ec3d19b85 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -52,18 +52,62 @@ choose to only allow {TypeSystemExtensionDocument} and not allow ## Type System Descriptions -Documentation is a first-class feature of GraphQL type systems. 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. - -Descriptions in the type system definition language occur immediately before the -definition they describe and are made available via introspection, ensuring the -documentation of a GraphQL service remains consistent with its capabilities. - -Note: See Section 2, "Descriptions", for normative rules and syntax details. -Type system descriptions follow the same Markdown format and rules as executable -document descriptions. +Documentation is a first-class feature of GraphQL type systems, written +immediately alongside definitions in a {TypeSystemDocument} and made available +via introspection. + +[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 +self descriptive. + +As an example, this simple GraphQL schema is well described: + +```raw graphql example +""" +A simple GraphQL schema which is well described. +""" +schema { + query: Query +} + +""" +Root type for all your query operations +""" +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 From f2b1b1f63b5a90918b33335c38dabfa406fa995f Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Tue, 1 Jul 2025 11:44:50 -0700 Subject: [PATCH 14/14] Editorial --- spec/Section 1 -- Overview.md | 2 +- spec/Section 2 -- Language.md | 13 ++++++------- spec/Section 6 -- Execution.md | 6 +++--- 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/spec/Section 1 -- Overview.md b/spec/Section 1 -- Overview.md index 451f8ea2f..c94c89a7b 100644 --- a/spec/Section 1 -- Overview.md +++ b/spec/Section 1 -- Overview.md @@ -63,7 +63,7 @@ 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 and self-describing. A GraphQL +- **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. diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 67c376fd0..86efe1581 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -237,13 +237,13 @@ defined by this specification. Description : StringValue -Documentation is a first-class feature of GraphQL by encouraging written +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 expected to provided as Markdown (as specified by +GraphQL descriptions are provided as Markdown (as specified by [CommonMark](https://commonmark.org/)). Description strings (often {BlockString}) occur immediately before the definition they describe. @@ -279,11 +279,10 @@ fragment TimeMachineDetails on TimeMachine { } ``` -Descriptions and comments in executable GraphQL documents are purely for -documentation purposes. They MUST NOT affect the execution, validation, or -response of a GraphQL document except for type introspection. It is otherwise -safe to remove all descriptions and comments from executable documents without -changing their behavior or results. +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 diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 7b86c785f..13606df18 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -35,9 +35,9 @@ 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 execution, validation, or response of a GraphQL -document. Descriptions and comments on executable documents MAY be used for -observability and logging purposes. +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