Add support for descriptions on executable documents (GraphQL September 2025)

crates/apollo-compiler/src/ast/from_cst.rs

@@ -125,6 +125,7 @@ impl Convert for cst::OperationDefinition {
             ast::OperationType::Query
         };
         Some(Self::Target {
+            description: self.description().convert(file_id)?,
             operation_type,
             name: self.name().convert(file_id)?,
             variables: collect_opt(file_id, self.variable_definitions(), |x| {
@@ -147,6 +148,7 @@ impl Convert for cst::FragmentDefinition {
 
     fn convert(&self, file_id: FileId) -> Option<Self::Target> {
         Some(Self::Target {
+            description: self.description().convert(file_id)?,
             name: self.fragment_name()?.name()?.convert(file_id)?,
             type_condition: self.type_condition()?.convert(file_id)?,
             directives: ast::DirectiveList(collect_opt(file_id, self.directives(), |x| {
@@ -530,6 +532,7 @@ impl Convert for cst::VariableDefinition {
         };
         let ty = &self.ty()?;
         Some(Self::Target {
+            description: self.description().convert(file_id)?,
             name: self.variable()?.name()?.convert(file_id)?,
             ty: with_location(file_id, ty.syntax(), ty.convert(file_id)?),
             default_value,

crates/apollo-compiler/src/ast/mod.rs

@@ -116,6 +116,7 @@ pub enum Definition {
 /// [_OperationDefinition_](https://spec.graphql.org/draft/#OperationDefinition).
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
 pub struct OperationDefinition {
+    pub description: Option<Node<str>>,
     pub operation_type: OperationType,
     pub name: Option<Name>,
     pub variables: Vec<Node<VariableDefinition>>,
@@ -127,6 +128,7 @@ pub struct OperationDefinition {
 /// [_FragmentDefinition_](https://spec.graphql.org/draft/#FragmentDefinition).
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
 pub struct FragmentDefinition {
+    pub description: Option<Node<str>>,
     pub name: Name,
     pub type_condition: NamedType,
     pub directives: DirectiveList,
@@ -335,6 +337,7 @@ pub enum DirectiveLocation {
 /// in an [`OperationDefinition`].
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
 pub struct VariableDefinition {
+    pub description: Option<Node<str>>,
     pub name: Name,
     pub ty: Node<Type>,
     pub default_value: Option<Node<Value>>,

crates/apollo-compiler/src/ast/serialize.rs

@@ -194,12 +194,14 @@ impl OperationDefinition {
     fn serialize_impl(&self, state: &mut State) -> fmt::Result {
         // Deconstruct to get a warning if we forget to serialize something
         let Self {
+            description,
             operation_type,
             name,
             variables,
             directives,
             selection_set,
         } = self;
+        serialize_description(state, description)?;
         // Only use shorthand when this is the first item.
         // If not, it might be following a `[lookahead != "{"]` grammar production
         let shorthand = state.output_empty
@@ -230,11 +232,13 @@ impl OperationDefinition {
 impl FragmentDefinition {
     fn serialize_impl(&self, state: &mut State) -> fmt::Result {
         let Self {
+            description,
             name,
             type_condition,
             directives,
             selection_set,
         } = self;
+        serialize_description(state, description)?;
         display!(state, "fragment {} on {}", name, type_condition)?;
         directives.serialize_impl(state)?;
         state.write(" ")?;
@@ -581,11 +585,13 @@ impl Directive {
 impl VariableDefinition {
     fn serialize_impl(&self, state: &mut State) -> fmt::Result {
         let Self {
+            description,
             name,
             ty,
             default_value,
             directives,
         } = self;
+        serialize_description(state, description)?;
         state.write("$")?;
         state.write(name)?;
         state.write(": ")?;

crates/apollo-compiler/src/executable/from_ast.rs

@@ -140,6 +140,7 @@ impl Operation {
         let mut selection_set = SelectionSet::new(ty);
         selection_set.extend_from_ast(schema, errors, &ast.selection_set);
         Some(Self {
+            description: ast.description.clone(),
             operation_type: ast.operation_type,
             name: ast.name.clone(),
             variables: ast.variables.clone(),
@@ -170,6 +171,7 @@ impl Fragment {
         let mut selection_set = SelectionSet::new(ast.type_condition.clone());
         selection_set.extend_from_ast(schema, errors, &ast.selection_set);
         Some(Self {
+            description: ast.description.clone(),
             name: ast.name.clone(),
             directives: ast.directives.clone(),
             selection_set,

crates/apollo-compiler/src/executable/mod.rs

@@ -123,6 +123,7 @@ pub struct FieldSet {
 /// annotated with type information.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Operation {
+    pub description: Option<Node<str>>,
     pub operation_type: OperationType,
     pub name: Option<Name>,
     pub variables: Vec<Node<VariableDefinition>>,
@@ -134,6 +135,7 @@ pub struct Operation {
 /// annotated with type information.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Fragment {
+    pub description: Option<Node<str>>,
     pub name: Name,
     pub directives: DirectiveList,
     pub selection_set: SelectionSet,

crates/apollo-compiler/src/executable/serialize.rs

@@ -28,6 +28,7 @@ impl ExecutableDocument {
 impl Operation {
     fn to_ast(&self, location: Option<SourceSpan>) -> ast::Definition {
         let def = ast::OperationDefinition {
+            description: self.description.clone(),
             operation_type: self.operation_type,
             name: self.name.clone(),
             variables: self.variables.clone(),
@@ -45,6 +46,7 @@ impl Operation {
 impl Fragment {
     fn to_ast(&self, location: Option<SourceSpan>) -> ast::Definition {
         let def = ast::FragmentDefinition {
+            description: self.description.clone(),
             name: self.name.clone(),
             type_condition: self.selection_set.ty.clone(),
             directives: self.directives.clone(),

crates/apollo-compiler/test_data/ok/0001_annonymous_operation_definition.txt

@@ -98,6 +98,7 @@ ExecutableDocument {
     operations: OperationMap {
         anonymous: Some(
             1..31 @3 Operation {
+                description: None,
                 operation_type: Query,
                 name: None,
                 variables: [],

crates/apollo-compiler/test_data/ok/0002_multiple_named_operation_definitions.txt

@@ -133,6 +133,7 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "getCatName": 0..41 @4 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "getCatName",
@@ -189,6 +190,7 @@ ExecutableDocument {
                 },
             },
             "getOwnerName": 43..106 @4 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "getOwnerName",

crates/apollo-compiler/test_data/ok/0010_operation_with_defined_fields.txt

@@ -252,6 +252,7 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "getProduct": 0..68 @12 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "getProduct",

crates/apollo-compiler/test_data/ok/0011_fragment_spreads_in_fragment_definitions.txt

@@ -122,6 +122,7 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "IntrospectionQuery": 0..51 @13 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "IntrospectionQuery",
@@ -166,6 +167,7 @@ ExecutableDocument {
     },
     fragments: {
         "Bar": 53..100 @13 Fragment {
+            description: None,
             name: "Bar",
             directives: [],
             selection_set: SelectionSet {
@@ -203,6 +205,7 @@ ExecutableDocument {
             },
         },
         "Quux": 102..131 @13 Fragment {
+            description: None,
             name: "Quux",
             directives: [],
             selection_set: SelectionSet {

crates/apollo-compiler/test_data/ok/0012_introspection_query.txt

@@ -78,6 +78,7 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "IntrospectionQuery": 0..271 @14 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "IntrospectionQuery",
@@ -418,6 +419,7 @@ ExecutableDocument {
     },
     fragments: {
         "FullType": 272..723 @14 Fragment {
+            description: None,
             name: "FullType",
             directives: [],
             selection_set: SelectionSet {
@@ -924,6 +926,7 @@ ExecutableDocument {
             },
         },
         "InputValue": 724..821 @14 Fragment {
+            description: None,
             name: "InputValue",
             directives: [],
             selection_set: SelectionSet {
@@ -1026,6 +1029,7 @@ ExecutableDocument {
             },
         },
         "TypeRef": 822..1265 @14 Fragment {
+            description: None,
             name: "TypeRef",
             directives: [],
             selection_set: SelectionSet {

crates/apollo-compiler/test_data/ok/0013_operation_with_used_variable_in_fragment.txt

@@ -210,12 +210,14 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "ExampleQuery": 0..81 @15 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "ExampleQuery",
                 ),
                 variables: [
                     19..33 @15 VariableDefinition {
+                        description: None,
                         name: "variable",
                         ty: 30..33 @15 Named(
                             "Int",
@@ -294,6 +296,7 @@ ExecutableDocument {
     },
     fragments: {
         "subFrag": 83..163 @15 Fragment {
+            description: None,
             name: "subFrag",
             directives: [],
             selection_set: SelectionSet {

crates/apollo-compiler/test_data/ok/0016_same_variables_in_multiple_operations.txt

@@ -146,12 +146,14 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "A": 0..61 @18 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "A",
                 ),
                 variables: [
                     8..30 @18 VariableDefinition {
+                        description: None,
                         name: "atOtherHomes",
                         ty: 23..30 @18 Named(
                             "Boolean",
@@ -174,12 +176,14 @@ ExecutableDocument {
                 },
             },
             "B": 63..124 @18 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "B",
                 ),
                 variables: [
                     71..93 @18 VariableDefinition {
+                        description: None,
                         name: "atOtherHomes",
                         ty: 86..93 @18 Named(
                             "Boolean",
@@ -205,6 +209,7 @@ ExecutableDocument {
     },
     fragments: {
         "HouseTrainedFragment": 126..228 @18 Fragment {
+            description: None,
             name: "HouseTrainedFragment",
             directives: [],
             selection_set: SelectionSet {

crates/apollo-compiler/test_data/ok/0017_variables_are_input_types.txt

@@ -225,12 +225,14 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "takesBoolean": 0..106 @19 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "takesBoolean",
                 ),
                 variables: [
                     19..41 @19 VariableDefinition {
+                        description: None,
                         name: "atOtherHomes",
                         ty: 34..41 @19 Named(
                             "Boolean",
@@ -307,12 +309,14 @@ ExecutableDocument {
                 },
             },
             "takesComplexInput": 108..213 @19 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "takesComplexInput",
                 ),
                 variables: [
                     132..159 @19 VariableDefinition {
+                        description: None,
                         name: "complexInput",
                         ty: 147..159 @19 Named(
                             "ComplexInput",
@@ -389,12 +393,14 @@ ExecutableDocument {
                 },
             },
             "TakesListOfBooleanBang": 215..311 @19 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "TakesListOfBooleanBang",
                 ),
                 variables: [
                     244..265 @19 VariableDefinition {
+                        description: None,
                         name: "booleans",
                         ty: 255..265 @19 List(
                             NonNullNamed(

crates/apollo-compiler/test_data/ok/0018_non_clashing_names.txt

@@ -117,6 +117,7 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "A": 173..203 @20 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "A",
@@ -161,6 +162,7 @@ ExecutableDocument {
     },
     fragments: {
         "A": 148..171 @20 Fragment {
+            description: None,
             name: "A",
             directives: [],
             selection_set: SelectionSet {

crates/apollo-compiler/test_data/ok/0020_merge_identical_fields.txt

@@ -111,6 +111,7 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "queryPupper": 76..175 @22 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "queryPupper",
@@ -161,6 +162,7 @@ ExecutableDocument {
     },
     fragments: {
         "mergeIdenticalFields": 177..231 @22 Fragment {
+            description: None,
             name: "mergeIdenticalFields",
             directives: [],
             selection_set: SelectionSet {
@@ -212,6 +214,7 @@ ExecutableDocument {
             },
         },
         "mergeIdenticalAliasesAndFields": 233..319 @22 Fragment {
+            description: None,
             name: "mergeIdenticalAliasesAndFields",
             directives: [],
             selection_set: SelectionSet {