From 5517373bab027c6fb5ec63e19df88eb7018e5271 Mon Sep 17 00:00:00 2001 From: Ivan Goncharov Date: Thu, 7 Oct 2021 19:15:34 +0300 Subject: [PATCH 1/9] 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 2/9] 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 3/9] 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 4/9] 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 5/9] 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 6/9] 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 7/9] 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 8/9] 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 9/9] 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) {