GraphQL Schema Specification: [API or graph name]

Specification of one GraphQL API: schema overview, types, queries, mutations, subscriptions, pagination, errors, nullability, naming, deprecation, authorisation, query cost limits, persisted queries, federation, performance and evolution. Written against the GraphQL specification, September 2025 edition (spec.graphql.org), with the widely used cursor connections convention for pagination. Replace every [bracketed] value and every row marked Example. Worked examples use a bookshop catalogue and ordering graph.

Document control

Approvals

Revision history

Contents

1. Introduction
2. Schema overview
3. Types
4. Queries
5. Mutations
6. Subscriptions
7. Nullability
8. Pagination
9. Naming conventions
10. Deprecation and evolution
11. Errors
12. Authorisation
13. Query cost and depth limits
14. Persisted queries and transport
15. Federation and composition
16. Performance
17. Observability
18. Schema governance
19. Glossary and references

1. Introduction

1.1 Purpose

[Example: The bookshop graph gives the web shop and mobile apps one API for browsing the catalogue, managing baskets and placing orders. It replaces four REST backends-for-frontends.]

1.2 Consumers

1.3 Design principles

• Demand-oriented: the schema models what client screens need, expressed in domain language, not the shape of backing services.
• One graph: one schema per organisation area, so clients do not stitch data together themselves.
• Evolve, do not version: additive change plus deprecation; no /v2 endpoint.
• Secure by default: every field is authorised server-side, regardless of which client asks.

1.4 Out of scope

[Example: Warehouse operations and finance reporting stay on their own APIs; the graph does not expose admin mutations.]

2. Schema overview

The diagram shows the main object types and their relationships.

3. Types

Full schema: [link to schema.graphql]. The type system uses the kinds defined by the GraphQL specification: scalars, objects, interfaces, unions, enums and input objects.

3.1 Custom scalars

Every custom scalar MUST declare @specifiedBy with a URL to its format.

"An instant in time, RFC 3339 format in UTC, e.g. 2026-03-14T09:30:00Z."
scalar DateTime @specifiedBy(url: "https://www.rfc-editor.org/rfc/rfc3339")

"ISO 4217 currency code, e.g. EUR."
scalar CurrencyCode @specifiedBy(url: "https://www.iso.org/iso-4217-currency-codes.html")

3.2 Core object types and interfaces

Objects that clients may need to refetch implement the Node interface with a globally unique, opaque id. Money is always an object with a decimal string and a currency, never a float. Enums are used for closed sets of values that clients branch on; clients MUST handle unknown enum values gracefully because new values are added without a new version. Every type and field carries a description string, which becomes the reference documentation.

"An object with a globally unique ID that can be refetched with Query.node."
interface Node {
  id: ID!
}

type Money {
  "Decimal amount as a string to avoid floating-point errors, e.g. \"12.90\"."
  amount: String!
  currency: CurrencyCode!
}

type Book implements Node {
  id: ID!
  isbn13: String!
  title: String!
  authors: [Author!]!
  price: Money!
  publishedOn: String
  stock: StockLevel
}

enum StockLevel {
  IN_STOCK
  LOW_STOCK
  OUT_OF_STOCK
}

3.3 Type register

4. Queries

type Query {
  "Refetch any object by its global ID."
  node(id: ID!): Node
  book(id: ID!): Book
  books(first: Int, after: String, filter: BookFilter): BookConnection!
  search(text: String!, first: Int = 20, after: String): SearchResultConnection!
  "The authenticated customer, or null for anonymous callers."
  viewer: Viewer
}

5. Mutations

Conventions:

• Name mutations verb first: addToBasket, placeOrder, cancelOrder.
• Each mutation takes a single argument input: <MutationName>Input! and returns <MutationName>Payload!.
• Payloads return the changed object and a list of typed userErrors for expected failures.
• Mutations with side effects accept a clientMutationId or an idempotency key in the input.

input PlaceOrderInput {
  basketId: ID!
  paymentMethod: PaymentMethodInput!
  idempotencyKey: String!
}

input PaymentMethodInput @oneOf {
  cardToken: String
  giftCardCode: String
}

type PlaceOrderPayload {
  order: Order
  userErrors: [PlaceOrderError!]!
}

type PlaceOrderError {
  code: PlaceOrderErrorCode!
  message: String!
  "Path to the input field that caused the error, e.g. [\"paymentMethod\", \"cardToken\"]."
  field: [String!]
}

enum PlaceOrderErrorCode {
  BASKET_EMPTY
  ITEM_OUT_OF_STOCK
  PAYMENT_DECLINED
}

type Mutation {
  placeOrder(input: PlaceOrderInput!): PlaceOrderPayload!
}

6. Subscriptions

type Subscription {
  orderStatusChanged(orderId: ID!): Order!
}

Transport: [Example: GraphQL over WebSocket using the graphql-transport-ws subprotocol; connection authenticated in the connection_init payload].

7. Nullability

8. Pagination

type BookConnection {
  edges: [BookEdge!]!
  pageInfo: PageInfo!
  "Approximate; may be omitted for expensive filters."
  totalCount: Int
}

type BookEdge {
  cursor: String!
  node: Book!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

• first default [20], maximum [50]; larger values return a validation error.
• Cursors are opaque, base64-encoded and valid for at least [24 hours].
• Backward pagination (last, before) is supported only where [listed].

9. Naming conventions

Names come from the domain's ubiquitous language, never from backing service or table names.

10. Deprecation and evolution

type Book implements Node {
  id: ID!
  "Use price.amount and price.currency."
  priceInCents: Int @deprecated(reason: "Use `price`. Removal after 2026-12-31.")
  price: Money!
}

Policy: [Example: minimum 90 days after deprecation and two app release cycles; removal requires zero usage from first-party clients for 14 days].

11. Errors

{
  "data": {"book": {"title": "Dune", "stock": null}},
  "errors": [{
    "message": "Stock information is temporarily unavailable.",
    "path": ["book", "stock"],
    "extensions": {"code": "UNAVAILABLE", "traceId": "4bf92f35"}
  }]
}

Error messages MUST NOT include stack traces or internal hostnames. The list of extensions.code values is fixed: [UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, BAD_USER_INPUT, RATE_LIMITED, UNAVAILABLE, INTERNAL].

12. Authorisation

13. Query cost and depth limits

Cost is calculated statically before execution. Each field costs 1; a connection multiplies its children by its first argument:

$\text{cost}(f) = 1 + n_f \sum_{c \in \text{children}(f)} \text{cost}(c)$

where $n_f$ is the page size for connections and 1 otherwise.

14. Persisted queries and transport

15. Federation and composition

Composition checks run in CI; a subgraph change that breaks composition or an active client operation is blocked.

16. Performance

• Resolvers that load by key use a per-request batching loader (the DataLoader pattern) so books { authors } makes one author call per request, not one per book.
• Loaders cache only within one request; cross-request caching uses the services' own caches.
• Target latency: p95 [250 ms] for persisted first-party queries, p99 [800 ms].
• Resolver timeouts: [2 s] per downstream call; the field returns null with an UNAVAILABLE error when exceeded.

The sequence below shows batched loading for a list query.

17. Observability

18. Schema governance

Change process: a schema change starts as a pull request against the SDL file, owned by the team that owns the affected types. The graph owners review new root fields, new cross-team relationships and anything that changes nullability or authorisation. Approved changes are published to the schema registry, which notifies client teams of new deprecations.

Clients must send an operation name and a client name header ([x-client-name]) so usage can be attributed.

19. Glossary and references

References: GraphQL specification September 2025 (https://spec.graphql.org/September2025/); Relay cursor connections specification; GraphQL over HTTP working draft; [federation documentation used].

Standard and licence note

Structure aligned with the GraphQL specification, September 2025 edition (https://spec.graphql.org/), for the type system, directives (@deprecated, @specifiedBy, @oneOf), schema coordinates, error and response format. Pagination follows the Relay cursor connections convention; federation and the GraphQL over HTTP transport are referenced as separate documents. This template is original text written for this collection and reproduces no text from those specifications; consult them for normative requirements. Template licence: MIT.