GraphQLConf 2025 brought together the GraphQL community for three days of talks on schema design, performance, and federation. UUID v7 was a recurring topic across the ID management, pagination, and real-time sessions. See UUID in GraphQL for implementation details.
Session: Custom UUID scalar
The foundational session explained why ID is insufficient for UUID-typed fields:
# Schema — custom UUID scalar instead of built-in ID
scalar UUID
type Order {
id: UUID! # validated as RFC 9562 UUID on input
customerId: UUID!
status: String!
}
type Query {
order(id: UUID!): Order
orders(after: UUID, first: Int = 20): OrderConnection!
}
// graphql-scalars UUID scalar — validates format and version
import { GraphQLUUID } from 'graphql-scalars';
const resolvers = {
UUID: GraphQLUUID,
Query: {
order: (_, { id }) => db.orders.findById(id),
},
};
See UUID v7 in GraphQL APIs for the full resolver pattern.
Session: Relay global IDs with UUID v7
// Relay-compatible global ID encoding with UUID v7
// Format: base64(TypeName:uuid)
function toGlobalId(type: string, uuid: string): string {
return Buffer.from(`${type}:${uuid}`).toString('base64url');
}
function fromGlobalId(globalId: string): { type: string; uuid: string } {
const [type, uuid] = Buffer.from(globalId, 'base64url').toString().split(':');
return { type, uuid };
}
// Order with UUID v7: globalId encodes type + id
const order = { id: uuidv7(), status: 'pending' };
const globalId = toGlobalId('Order', order.id);
// → 'T3JkZXI6MDE4ZmJlM2EtNGM1ZC03YjEyLThhYmMtMDEyMzQ1Njc4OWFi'
UUID v7’s timestamp prefix means global IDs sort chronologically when decoded and sorted by the UUID component.
Session: Subscription resume tokens
// Apollo Server — UUID v7 as subscription cursor
const resolvers = {
Subscription: {
orderUpdates: {
subscribe: async function* (_, { after }, { db }) {
// Resume from cursor — UUID v7 enables "events after this time"
const since = after ?? '00000000-0000-7000-8000-000000000000';
for await (const event of db.orderEvents.since(since)) {
yield { orderUpdates: event };
}
},
},
},
};
UUID v7 resume tokens persist across WebSocket reconnects without a separate timestamp field. See UUID v7 in GraphQL Subscriptions.
Further reading
- UUID in GraphQL — full guide
- UUID v7 in GraphQL APIs — IDs, types, scalars
- UUID v7 in GraphQL Subscriptions
- UUID v7 for Cursor Pagination
- UUID v7 in Microservices — trace IDs
External references
Frequently asked questions
Should GraphQL use the built-in ID scalar or a custom UUID scalar?
The built-in ID scalar accepts any string or integer and performs no format validation. For UUID-typed fields, a custom scalar (scalar UUID) lets you validate format on input and document the expected version in SDL descriptions. The graphql-scalars library provides a production-ready UUID scalar with RFC 9562 validation. Conference talks recommended the custom scalar approach for any API that exclusively uses UUIDs — it surfaces validation errors early and makes the API contract explicit. See UUID in GraphQL.
How do UUID v7 cursors improve GraphQL cursor pagination?
Standard Base64-encoded offset cursors are opaque but carry no timestamp. UUID v7 cursors encode creation time in the first 48 bits — so pageInfo.endCursor is both a stable page position and a timestamp the client can use to display "showing items up to X". On the server, WHERE id > $cursor ORDER BY id uses the primary key index directly. No separate createdAt column or index is needed. See UUID v7 for Cursor Pagination.