---
title: "Deprecate GraphQL fields before you remove · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/graphql-and-grpc/graphql-deprecation
id: API-82
level: Recommended
updated: 2026-10-22
tokens: 864
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Deprecate GraphQL fields before you remove them

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: API-82
- Level: Recommended
- Chapter: [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md)
- Rule: Change a GraphQL schema by adding types and fields, never by versioning the endpoint. Mark a field you plan to remove with `@deprecated(reason:)` and remove it only after 90 days with no use.
- Check: CI compares the new schema with the live one and fails on a removed or changed field that was not marked deprecated for 90 days. Field use metrics show zero calls over the last 30 days for each field removed.
- How: A GraphQL client gets only the fields it asks for, so a new field breaks no one. That is why graphql.org advises a schema without versions. The `@deprecated` directive shows in tools and generated clients, and the reason names the field to use instead. The September 2025 edition of the specification also allows deprecating arguments and input fields. Count use per field in your traces, and remove a field only when the count is zero. The REST form of this is [make only additive changes](https://agentwranglers.se/playbook/api-design/changes-over-time/additive-changes.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Plain text example

```graphql
type Invoice {
  id: ID!
  totalCents: Int!
  currency: String!
  total: Float @deprecated(reason: "Use totalCents and currency. Removed after 2027-02-01.")
}
```

### JavaScript example

```js
// Apollo Server reads @deprecated from the schema and reports use per field
const typeDefs = gql`
  type Invoice {
    id: ID!
    totalCents: Int!
    total: Float @deprecated(reason: "Use totalCents and currency.")
  }
`;
```

### Python example

```python
@strawberry.type
class Invoice:
    id: strawberry.ID
    total_cents: int
    total: float | None = strawberry.field(deprecation_reason="Use total_cents and currency.")
```

## Sources

- [GraphQL specification, September 2025](https://spec.graphql.org/September2025/)
- [GraphQL, Schema design](https://graphql.org/learn/schema-design/)

## Related rules

- API-27 [Make only additive changes](https://agentwranglers.se/playbook/api-design/changes-over-time/additive-changes.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/graphql-and-grpc/graphql-deprecation">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Accept GraphQL mutations only by POST with a JSON body](https://agentwranglers.se/playbook/api-design/graphql-and-grpc/graphql-post-mutations.md)
- Next: [Page GraphQL lists as cursor connections](https://agentwranglers.se/playbook/api-design/graphql-and-grpc/graphql-connections.md)
- [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md)