obsidian/wiki/payloadcms/graphql-schema.md

title	aliases	tags	sources	created	updated
GraphQL — Schema Generation	graphql-schema generate-graphql-schema payload-graphql	payloadcms graphql codegen typescript	raw/graphql__graphql-schema.md	2026-05-15	2026-05-15

Overview

Payload auto-generates a GraphQL schema from your Collections and Globals. The @payloadcms/graphql package exposes a CLI command to dump the full schema to a file.

Schema Generation

Install as a dev dependency:

pnpm add @payloadcms/graphql -D

Run the generator:

pnpm payload-graphql generate:schema

• Default output: ./schema.graphql (current working directory)
• If graphQL.schemaOutputFile is set in buildConfig, output goes there (e.g. ./graphql/schema.graphql)

Config Path Detection

Payload auto-detects your config, but fails if it lives in a non-standard location (e.g. src/). Fix with an npm script using PAYLOAD_CONFIG_PATH:

// package.json
{
  "scripts": {
    "generate:graphQLSchema": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload-graphql generate:schema"
  }
}

Custom Field Interfaces (interfaceName)

For array, block, group, and named tab fields, set interfaceName to produce a top-level reusable GraphQL type instead of an inline type:

{
  type: 'group',
  name: 'meta',
  interfaceName: 'SharedMeta',
  fields: [
    { name: 'title', type: 'text' },
    { name: 'description', type: 'text' },
  ],
}

Generated schema:

# Reusable top-level type
type SharedMeta {
  title: String
  description: String
}

# Referenced in the collection
type Collection1 {
  meta: SharedMeta
}

This mirrors how interfaceName works for wiki/payloadcms/typescript — same field config option, two outputs.

Key Takeaways

• pnpm payload-graphql generate:schema dumps the full schema to schema.graphql
• Set PAYLOAD_CONFIG_PATH env var when config is not at the project root
• interfaceName on group/array/block/tab fields creates reusable top-level GraphQL types (avoids inline duplication)
• Schema generation is a dev-time step — add it to CI alongside generate:types for drift detection
• Related: wiki/payloadcms/graphql-extending for adding custom ops on top of the generated schema

Sources

• raw/graphql__graphql-schema.md
• https://payloadcms.com/docs/graphql/graphql-schema