graphql · fotoetienne · Feb 20, 2026
diff --git a/src/type/__tests__/definition-test.ts b/src/type/__tests__/definition-test.ts
@@ -188,6 +188,7 @@ describe('Type System: Objects', () => {
       extensions: {},
       astNode: undefined,
       extensionASTNodes: [],
+      deprecationReason: undefined,
     });
   });
 
@@ -222,11 +223,26 @@ describe('Type System: Objects', () => {
       extensions: { someExtension: 'extension' },
       astNode: dummyAny,
       extensionASTNodes: [dummyAny],
+      deprecationReason: undefined,
     };
     const someObject = new GraphQLObjectType(someObjectConfig);
     expect(someObject.toConfig()).to.deep.equal(someObjectConfig);
   });
 
+  it('defines a deprecated object type', () => {
+    const DeprecatedType = new GraphQLObjectType({
+      name: 'foo',
+      fields: {
+        bar: {
+          type: ScalarType,
+        },
+      },
+      deprecationReason: 'A terrible reason',
+    });
+
+    expect(DeprecatedType.deprecationReason).to.equal('A terrible reason');
+  });
+
   it('does not mutate passed field definitions', () => {
     const outputFields = {
       field1: { type: ScalarType },

diff --git a/src/type/__tests__/introspection-test.ts b/src/type/__tests__/introspection-test.ts
@@ -96,7 +96,21 @@ describe('Introspection', () => {
                 },
                 {
                   name: 'types',
-                  args: [],
+                  args: [
+                    {
+                      name: 'includeDeprecated',
+                      type: {
+                        kind: 'NON_NULL',
+                        name: null,
+                        ofType: {
+                          kind: 'SCALAR',
+                          name: 'Boolean',
+                          ofType: null,
+                        },
+                      },
+                      defaultValue: 'false',
+                    },
+                  ],
                   type: {
                     kind: 'NON_NULL',
                     name: null,
@@ -290,7 +304,21 @@ describe('Introspection', () => {
                 },
                 {
                   name: 'possibleTypes',
-                  args: [],
+                  args: [
+                    {
+                      name: 'includeDeprecated',
+                      type: {
+                        kind: 'NON_NULL',
+                        name: null,
+                        ofType: {
+                          kind: 'SCALAR',
+                          name: 'Boolean',
+                          ofType: null,
+                        },
+                      },
+                      defaultValue: 'false',
+                    },
+                  ],
                   type: {
                     kind: 'LIST',
                     name: null,
@@ -395,6 +423,28 @@ describe('Introspection', () => {
                   isDeprecated: false,
                   deprecationReason: null,
                 },
+                {
+                  name: 'isDeprecated',
+                  args: [],
+                  type: {
+                    kind: 'SCALAR',
+                    name: 'Boolean',
+                    ofType: null,
+                  },
+                  isDeprecated: false,
+                  deprecationReason: null,
+                },
+                {
+                  name: 'deprecationReason',
+                  args: [],
+                  type: {
+                    kind: 'SCALAR',
+                    name: 'String',
+                    ofType: null,
+                  },
+                  isDeprecated: false,
+                  deprecationReason: null,
+                },
               ],
               inputFields: null,
               interfaces: [],
@@ -992,6 +1042,7 @@ describe('Introspection', () => {
                 'ARGUMENT_DEFINITION',
                 'INPUT_FIELD_DEFINITION',
                 'ENUM_VALUE',
+                'OBJECT',
               ],
               args: [
                 {
@@ -1277,6 +1328,133 @@ describe('Introspection', () => {
     });
   });
 
+  it('identifies deprecated objects', () => {
+    const schema = buildSchema(`
+      type Query {
+        dragon: [Dragon] @deprecated(reason: "Use phoenix")
+      }
+      type Dragon @deprecated(reason: "No longer known to exist") {
+        name: String
+      }
+    `);
+
+    const source = `
+      {
+        __schema {
+          types(includeDeprecated: true) {
+            name
+            isDeprecated
+            deprecationReason
+          }
+        }
+        dragon: __type(name: "Dragon") {
+          name
+          isDeprecated
+          deprecationReason
+        }
+      }
+    `;
+
+    const result = graphqlSync({ schema, source });
+
+    const types = (result.data as any).__schema.types;
+    expect(types).to.deep.include.members([
+      {
+        name: 'Dragon',
+        isDeprecated: true,
+        deprecationReason: 'No longer known to exist',
+      },
+    ]);
+    expect((result.data as any).dragon).to.deep.equal({
+      name: 'Dragon',
+      isDeprecated: true,
+      deprecationReason: 'No longer known to exist',
+    });
+  });
+
+  it('respects the includeDeprecated parameter for types', () => {
+    const schema = buildSchema(`
+      type Query {
+        dragon: [Dragon] @deprecated(reason: "Use phoenix")
+      }
+      type Dragon @deprecated(reason: "No longer known to exist") {
+        name: String
+      }
+    `);
+
+    const source = `
+      {
+        __schema {
+          trueTypes: types(includeDeprecated: true) {
+            name
+          }
+          falseTypes: types(includeDeprecated: false) {
+            name
+          }
+          omittedTypes: types {
+            name
+          }
+        }
+      }
+    `;
+
+    const result = graphqlSync({ schema, source });
+    const response = result.data as any;
+    expect(response.__schema.trueTypes).to.deep.include.members([
+      { name: 'Dragon' },
+    ]);
+    expect(response.__schema.falseTypes).to.not.deep.include.members([
+      { name: 'Dragon' },
+    ]);
+    expect(response.__schema.omittedTypes).to.not.deep.include.members([
+      { name: 'Dragon' },
+    ]);
+  });
+
+  it('respects the includeDeprecated parameter for possibleTypes', () => {
+    const schema = buildSchema(`
+      type Query {
+        animals: [Animal]
+      }
+
+      interface Animal {
+        name: String
+      }
+
+      type Dog implements Animal {
+        name: String
+      }
+
+      type Dragon implements Animal @deprecated(reason: "No longer known to exist") {
+        name: String
+      }
+    `);
+
+    const source = `
+      {
+        animal: __type(name: "Animal") {
+          trueTypes: possibleTypes(includeDeprecated: true) {
+            name
+          }
+          falseTypes: possibleTypes(includeDeprecated: false) {
+            name
+          }
+          omittedTypes: possibleTypes {
+            name
+          }
+        }
+      }
+    `;
+
+    const result = graphqlSync({ schema, source });
+    const animal = (result.data as any).animal;
+    expect(animal.trueTypes).to.deep.include.members([{ name: 'Dragon' }]);
+    expect(animal.falseTypes).to.not.deep.include.members([{ name: 'Dragon' }]);
+    expect(animal.omittedTypes).to.not.deep.include.members([
+      { name: 'Dragon' },
+    ]);
+  });
+
   it('identifies deprecated args', () => {
     const schema = buildSchema(`
       type Query {

diff --git a/src/type/__tests__/validation-test.ts b/src/type/__tests__/validation-test.ts
@@ -3380,6 +3380,40 @@ describe('Interfaces must adhere to Interface they implement', () => {
       },
     ]);
   });
+
+  it('rejects non-deprecated field returning deprecated type', () => {
+    const schema = buildSchema(`
+      type Query {
+        dragon: Dragon
+      }
+
+      type Dragon @deprecated(reason: "No longer known to exist") {
+        name: String
+      }
+    `);
+
+    expectJSON(validateSchema(schema)).toDeepEqual([
+      {
+        message:
+          'The type of Query.dragon is deprecated type "Dragon". Either deprecate the field or change its return type.',
+        locations: [{ line: 3, column: 17 }],
+      },
+    ]);
+  });
+
+  it('accepts deprecated field returning deprecated type', () => {
+    const schema = buildSchema(`
+      type Query {
+        dragon: Dragon @deprecated(reason: "Use phoenix instead")
+      }
+
+      type Dragon @deprecated(reason: "No longer known to exist") {
+        name: String
+      }
+    `);
+
+    expectJSON(validateSchema(schema)).toDeepEqual([]);
+  });
 });
 
 describe('assertValidSchema', () => {

diff --git a/src/type/definition.ts b/src/type/definition.ts
@@ -906,6 +906,7 @@ export class GraphQLObjectType<TSource = any, TContext = any, TAbstract = any>
   extensions: Readonly<GraphQLObjectTypeExtensions<TSource, TContext>>;
   astNode: Maybe<ObjectTypeDefinitionNode>;
   extensionASTNodes: ReadonlyArray<ObjectTypeExtensionNode>;
+  deprecationReason: Maybe<string>;
 
   private _fields: ThunkObjMap<GraphQLField<TSource, TContext>>;
   private _interfaces: ThunkReadonlyArray<GraphQLInterfaceType>;
@@ -920,6 +921,7 @@ export class GraphQLObjectType<TSource = any, TContext = any, TAbstract = any>
     this.extensions = toObjMapWithSymbols(config.extensions);
     this.astNode = config.astNode;
     this.extensionASTNodes = config.extensionASTNodes ?? [];
+    this.deprecationReason = config.deprecationReason;
     this._fields = (defineFieldMap<TSource, TContext>).bind(
       undefined,
       this,
@@ -956,6 +958,7 @@ export class GraphQLObjectType<TSource = any, TContext = any, TAbstract = any>
       extensions: this.extensions,
       astNode: this.astNode,
       extensionASTNodes: this.extensionASTNodes,
+      deprecationReason: this.deprecationReason,
     };
   }
 
@@ -1002,6 +1005,7 @@ export interface GraphQLObjectTypeConfig<
   extensions?: Maybe<Readonly<GraphQLObjectTypeExtensions<TSource, TContext>>>;
   astNode?: Maybe<ObjectTypeDefinitionNode>;
   extensionASTNodes?: Maybe<ReadonlyArray<ObjectTypeExtensionNode>>;
+  deprecationReason?: Maybe<string>;
 }
 
 export interface GraphQLObjectTypeNormalizedConfig<

diff --git a/src/type/directives.ts b/src/type/directives.ts
@@ -242,6 +242,7 @@ export const GraphQLDeprecatedDirective: GraphQLDirective =
       DirectiveLocation.ARGUMENT_DEFINITION,
       DirectiveLocation.INPUT_FIELD_DEFINITION,
       DirectiveLocation.ENUM_VALUE,
+      DirectiveLocation.OBJECT,
     ],
     args: {
       reason: {

diff --git a/src/type/introspection.ts b/src/type/introspection.ts
@@ -46,8 +46,19 @@ export const __Schema: GraphQLObjectType = new GraphQLObjectType({
       types: {
         description: 'A list of all types supported by this server.',
         type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(__Type))),
-        resolve(schema) {
-          return Object.values(schema.getTypeMap());
+        args: {
+          includeDeprecated: {
+            type: new GraphQLNonNull(GraphQLBoolean),
+            default: { value: false },
+          },
+        },
+        resolve(schema, { includeDeprecated }) {
+          const types = Object.values(schema.getTypeMap());
+          return includeDeprecated === true
+            ? types
+            : types.filter(
+                (type) => !isObjectType(type) || type.deprecationReason == null,
+              );
         },
       },
       queryType: {
@@ -291,9 +302,18 @@ export const __Type: GraphQLObjectType = new GraphQLObjectType({
       },
       possibleTypes: {
         type: new GraphQLList(new GraphQLNonNull(__Type)),
-        resolve(type, _args, _context, { schema }) {
+        args: {
+          includeDeprecated: {
+            type: new GraphQLNonNull(GraphQLBoolean),
+            default: { value: false },
+          },
+        },
+        resolve(type, { includeDeprecated }, _context, { schema }) {
           if (isAbstractType(type)) {
-            return schema.getPossibleTypes(type);
+            const possibleTypes = schema.getPossibleTypes(type);
+            return includeDeprecated === true
+              ? possibleTypes
+              : possibleTypes.filter((t) => t.deprecationReason == null);
           }
         },
       },
@@ -343,6 +363,16 @@ export const __Type: GraphQLObjectType = new GraphQLObjectType({
           }
         },
       },
+      isDeprecated: {
+        type: GraphQLBoolean,
+        resolve: (type) =>
+          isObjectType(type) ? type.deprecationReason != null : undefined,
+      },
+      deprecationReason: {
+        type: GraphQLString,
+        resolve: (type) =>
+          isObjectType(type) ? type.deprecationReason : undefined,
+      },
     }) as GraphQLFieldConfigMap<GraphQLType, unknown>,
 });