Managing IDs

IDs that exist as scalars on a GraphQL Schema are considered part of the data of a Document. GraphQL Paper doesn't use them for tracking uniqueness although it does have ways of helping ensure that data for ID fields are kept unique and also help in generating ID values.

Automatically Generating IDs

It can be helpful to have an automatically generated ID that reflects the ID format used by the GraphQL API being mocked.

Using a Custom Hook

This can be done by using an afterTransaction hook function to ensure that any IDs that are missing are added automatically. Learn more about creating custom hooks.

Assuming the GraphQL Paper document has an id field:

type SomeType {
id: ID!

Using auto-incrementing IDs

For most testing and development cases this should run fast enough, and only after each transaction. In the case this is too slow a custom operation could be created (see below).

function autoIncrementIdHook({ getStore }) {
const store = getStore();
Object.entries(store).forEach(([type, documents]) => {
// find the current maximum id for the current type
let maxId = documents.reduce((previous, document) => {
return Math.max(previous, Number(;
}, 0);
// loop over each document that's missing an ID and
// add an incremented id
documents.forEach((document) => {
if (typeof document !== 'string') { = String(++maxId);

Using UUIDs

Using a custom uuid function is simpler to generate a missing ID for any document missing one after a transaction is complete.

function addUuidHook({ getStore }) {
const store = getStore();
Object.entries(store).forEach(([type, documents]) => {
documents.forEach((document) => {
if (typeof document !== 'string') {
// using a uuid function from an npm package = uuid();

Using a Custom Operation

Another solution is to create a custom operation that wraps the provided create operation and keeps tracks of IDs. Learn more about creating custom operations.

import { create } from 'graphql-paper/operations';
// track ids { [typename: string] : number }
const ids = {};
const customCreate = (context, typename, documentPartial) => {
const document = create(context, typename, documentPartial);
// increment or initialize
ids[typename] = (ids[typename] ?? 0) + 1;
// set incremented id = String(ids[typename]);
return document;
const paper = new Paper(graphqlSchema, { operations: { customCreate } });

Validating Unique IDs

By default GraphQL Paper is checking for unique IDs on a per-type basis with the uniqueIdFieldValidator. If the ID constraint is more complicated than per type then it's recommended to create a custom field validator. Learn more about creating custom field validators.