Support descriptions on operations and fragments

Author: tyranron

juniper/CHANGELOG.md

@@ -16,6 +16,7 @@ All user visible changes to `juniper` crate will be documented in this file. Thi
     - Made `includeDeprecated` argument of `__Type.fields`, `__Type.enumValues`, `__Type.inputFields`, `__Field.args` and `__Directive.args` fields non-`Null`. ([#1348], [graphql/graphql-spec#1142])
     - Made `@deprecated(reason:)` argument non-`Null`. ([#1348], [graphql/graphql-spec#1040])
 - Changed `ScalarToken::String` to contain raw quoted and escaped `StringLiteral` (was unquoted but escaped string before). ([#1349])
+    - Added `description` field to `ast::Operation` and `ast::Fragment` field. ([#1349], [graphql/graphql-spec#1170])
 - Added `LexerError::UnterminatedBlockString` variant. ([#1349])
 
 ### Added
@@ -32,6 +33,7 @@ All user visible changes to `juniper` crate will be documented in this file. Thi
         - `schema::meta::Argument::deprecation_status` field.
     - Support for variable-length escaped Unicode characters (e.g. `\u{110000}`) in strings. ([#1349], [graphql/graphql-spec#849], [graphql/graphql-spec#687])
     - Full Unicode range support. ([#1349], [graphql/graphql-spec#849], [graphql/graphql-spec#687])
+    - Support parsing descriptions on fragments. ([#1349], [graphql/graphql-spec#1170])
 - Support for [block strings][0180-1]. ([#1349])
 
 ### Changed
@@ -56,6 +58,7 @@ All user visible changes to `juniper` crate will be documented in this file. Thi
 [graphql/graphql-spec#849]: https://github.com/graphql/graphql-spec/pull/849
 [graphql/graphql-spec#1040]: https://github.com/graphql/graphql-spec/pull/1040
 [graphql/graphql-spec#1142]: https://github.com/graphql/graphql-spec/pull/1142
+[graphql/graphql-spec#1170]: https://github.com/graphql/graphql-spec/pull/1170
 [0180-1]: https://spec.graphql.org/September2025/#sec-String-Value.Block-Strings
 
 

juniper/src/ast.rs

@@ -384,7 +384,7 @@ pub enum OperationType {
 #[expect(missing_docs, reason = "self-explanatory")]
 #[derive(Clone, Debug, PartialEq)]
 pub struct Operation<'a, S> {
-    //pub description: Option<Spanning<&'a str>>,
+    pub description: Option<Spanning<Cow<'a, str>>>,
     pub operation_type: OperationType,
     pub name: Option<Spanning<&'a str>>,
     pub variable_definitions: Option<Spanning<VariableDefinitions<'a, S>>>,
@@ -395,6 +395,7 @@ pub struct Operation<'a, S> {
 #[derive(Clone, Debug, PartialEq)]
 pub struct Fragment<'a, S> {
     pub name: Spanning<&'a str>,
+    pub description: Option<Spanning<Cow<'a, str>>>,
     pub type_condition: Spanning<&'a str>,
     pub directives: Option<Vec<Spanning<Directive<'a, S>>>>,
     pub selection_set: Vec<Selection<'a, S>>,
@@ -407,6 +408,16 @@ pub enum Definition<'a, S> {
     Fragment(Spanning<Fragment<'a, S>>),
 }
 
+impl<'a, S> Definition<'a, S> {
+    /// Sets or resets the provided `description` for this [`Definition`].
+    pub(crate) fn set_description(&mut self, description: Option<Spanning<Cow<'a, str>>>) {
+        match self {
+            Self::Operation(op) => op.item.description = description,
+            Self::Fragment(frag) => frag.item.description = description,
+        }
+    }
+}
+
 #[doc(hidden)]
 pub type Document<'a, S> = [Definition<'a, S>];
 #[doc(hidden)]

juniper/src/parser/document.rs

@@ -1,12 +1,13 @@
-use crate::ast::{
-    Arguments, Definition, Directive, Field, Fragment, FragmentSpread, InlineFragment, InputValue,
-    Operation, OperationType, OwnedDocument, Selection, Type, VariableDefinition,
-    VariableDefinitions,
-};
+use std::borrow::Cow;
 
 use crate::{
+    ast::{
+        Arguments, Definition, Directive, Field, Fragment, FragmentSpread, InlineFragment,
+        InputValue, Operation, OperationType, OwnedDocument, Selection, Type, VariableDefinition,
+        VariableDefinitions,
+    },
     parser::{
-        Lexer, OptionParseResult, ParseError, ParseResult, Parser, Spanning, Token,
+        Lexer, OptionParseResult, ParseError, ParseResult, Parser, ScalarToken, Spanning, Token,
         UnlocatedParseResult, value::parse_value_literal,
     },
     schema::{
@@ -54,18 +55,25 @@ fn parse_definition<'a, S>(
 where
     S: ScalarValue,
 {
-    match parser.peek().item {
+    let description = parse_description(parser)?;
+
+    let mut def = match parser.peek().item {
+        // Descriptions are not permitted on query shorthand.
+        // See: https://spec.graphql.org/September2025#sel-GAFTRJABAByBz7P
+        Token::CurlyOpen if description.is_some() => {
+            return Err(parser.next_token()?.map(ParseError::unexpected_token));
+        }
         Token::CurlyOpen
         | Token::Name("query")
         | Token::Name("mutation")
-        | Token::Name("subscription") => Ok(Definition::Operation(parse_operation_definition(
-            parser, schema,
-        )?)),
-        Token::Name("fragment") => Ok(Definition::Fragment(parse_fragment_definition(
-            parser, schema,
-        )?)),
-        _ => Err(parser.next_token()?.map(ParseError::unexpected_token)),
-    }
+        | Token::Name("subscription") => {
+            Definition::Operation(parse_operation_definition(parser, schema)?)
+        }
+        Token::Name("fragment") => Definition::Fragment(parse_fragment_definition(parser, schema)?),
+        _ => return Err(parser.next_token()?.map(ParseError::unexpected_token)),
+    };
+    def.set_description(description);
+    Ok(def)
 }
 
 fn parse_operation_definition<'a, S>(
@@ -85,6 +93,7 @@ where
             Operation {
                 operation_type: OperationType::Query,
                 name: None,
+                description: None,
                 variable_definitions: None,
                 directives: None,
                 selection_set: selection_set.item,
@@ -115,6 +124,7 @@ where
             Operation {
                 operation_type: operation_type.item,
                 name,
+                description: None,
                 variable_definitions,
                 directives: directives.map(|s| s.item),
                 selection_set: selection_set.item,
@@ -158,6 +168,7 @@ where
         &selection_set.span.end,
         Fragment {
             name,
+            description: None,
             type_condition: type_cond,
             directives: directives.map(|s| s.item),
             selection_set: selection_set.item,
@@ -460,6 +471,21 @@ where
     ))
 }
 
+fn parse_description<'a>(parser: &mut Parser<'a>) -> OptionParseResult<Cow<'a, str>> {
+    if !matches!(parser.peek().item, Token::Scalar(ScalarToken::String(_))) {
+        Ok(None)
+    } else {
+        let token = parser.next_token()?;
+        let Token::Scalar(ScalarToken::String(lit)) = token.item else {
+            unreachable!("already checked to be `ScalarToken::String`")
+        };
+        Ok(Some(Spanning::new(
+            token.span,
+            lit.parse().map_err(|e| Spanning::new(token.span, e))?,
+        )))
+    }
+}
+
 fn parse_directives<'a, S>(
     parser: &mut Parser<'a>,
     schema: &SchemaType<S>,