Configuration

Before generating schemas, you need (no you don't actually need, but you want, trust me!) to tell GQLSchemaGen how your project is structured and how you want the output organized. Running:

$ gqlschemagen init

creates a gqlschemagen.yml file in your project root. This file controls:

• which Go packages are scanned
• how output files are structured
• type and field naming rules
• enum generation
• auto-generation behavior
• gqlgen integration options
• file-preservation rules via @gqlKeep markers

Configure this once and the tool handles the rest.

1. Packages & Strategy

Packages

Define the Go packages where annotated structs (@gqlType, @gqlInput, @gqlEnum) are located. Supports glob patterns for recursive scanning.

Examples:

• ./models/ - Scan models directory
• ./internal/**/*.go - Recursively scan all Go files in internal
• ./pkg/types/user.go - Scan specific file

Output Strategy

Controls how schema files are generated:

Examples:

Single strategy - all types in one file:

Multiple strategy - separate files:

Package strategy - organized by Go package:

2. Output Structure

Output Path

Directory or file path where schema files will be generated. The meaning depends on your strategy:

• Single strategy: Full file path including filename
• Multiple/Package strategy: Directory path

Output File Name

Controls the filename when using single strategy:

Default: gqlschemagen.graphqls

Output File Extension

File extension for generated schema files in multiple and package strategies:

Default: .graphqls

Common alternatives: .gql, .graphql

Schema File Name Pattern

Customize file naming in multiple strategy using placeholders:

Available placeholders:

• {model_name} - Go struct name (e.g., User → User.graphqls)
• {type_name} - GraphQL type name (e.g., UserProfile → UserProfile.graphqls)

Examples:

3. Naming Conventions

Field Case Transformation

Controls how Go struct field names are converted to GraphQL field names:

Options:

Example:

Use JSON Tags

When enabled, uses json:"..." struct tags for field names if gql:"..." tags are not present:

Example:

Type Name Manipulation

Strip Prefix/Suffix

Remove common prefixes or suffixes from type names:

Example:

Add Type Prefix/Suffix

Add prefixes or suffixes to GraphQL output type names:

Example:

Add Input Prefix/Suffix

Add prefixes or suffixes to GraphQL input type names:

Example:

Note: These only apply when @gqlType or @gqlInput don't specify a custom name parameter.

4. Directives & gqlgen Integration

Enable gqlgen Directives

Generate gqlgen-compatible directives for seamless integration:

When enabled, generates:

• @goModel - Maps GraphQL type to Go struct
• @goField - Configures resolver behavior
• @goTag - Adds Go struct tags to generated code

Example output:

Model Path Override

Override the base import path used in @goModel directives:

When to use:

• Generating schemas for a different module path than source location
• Standardizing import paths across environments
• Building schemas for code generation

Example:

Default behavior: When empty (""), uses the actual package import path from go.mod.

5. Auto-Generation

GQLSchemaGen can automatically generate schemas for types referenced by annotated types, reducing manual @gqlType annotations.

Enable Auto-Generation

Strategies

none - Manual Only

Only generate types explicitly marked with @gqlType, @gqlInput, or @gqlInclude:

Use case: Full control, minimal schema

referenced - Smart Dependencies (Recommended)

Auto-generate types referenced by annotated types:

Example:

Generated: User, UserProfile, and Post types

all - Generate Everything

Generate schemas for all structs found in scanned packages:

Use case: Comprehensive API documentation, exploratory schemas

Warning: May generate types you don't want exposed

patterns - Pattern Matching

Generate based on glob patterns:

Use case: Convention-based generation (e.g., all types ending with "Connection")

Max Depth

Controls how deep to traverse type dependencies:

• 0 - Unlimited depth
• 1 - Direct references only (recommended)
• 2 - Direct + transitive references
• 3+ - Further nesting

Example with max_depth: 1:

Example with max_depth: 2:

Include Options

Include Embedded Types

Auto-generate schemas for embedded struct types:

Include Field Types

Auto-generate schemas for field types:

Out-of-Scope Types

Controls behavior when types are referenced but not in scanned packages:

Options:

Example:

• warn: Generates User type with Company field, shows warning
• fail: Generation stops with error
• ignore: Generates User type silently
• exclude: Generates User without Company field

Generic Type Handling

Unresolved Generic Type

What to use when generic type parameters can't be resolved:

Suppress Generic Warnings

Suppress out-of-scope warnings for type parameters (T, K, V, etc.):

Useful when working with generic types where type parameters are expected to be unresolved.

6. Known Scalars & Scalar Mappings

Known Scalars

List custom GraphQL scalars that are defined externally (in other schemas or libraries). These types are considered "in scope" and won't trigger out-of-scope warnings:

When to use:

• Using custom scalars defined in separate schema files
• Integrating with third-party GraphQL libraries
• Using scalars from gqlgen or other tools

Example:

Built-in scalars (always known): Int, Float, String, Boolean, ID

Scalar Mappings

Map Go types to GraphQL scalars globally. Similar to gqlgen's models configuration:

How it works:

1. When a field has a Go type matching a model entry, use the scalar instead of generating a new type
2. Scalar declarations are only generated for scalars that are:
   • Used in the schema
   • NOT built-in (Int, String, Float, Boolean, ID)
   • NOT in known_scalars

Example:

Generated schema:

Why DateTime is declared but ID is not:

• ID is a built-in GraphQL scalar
• DateTime is custom and not in known_scalars, so it needs declaration

Multiple UUID libraries:

All three UUID libraries map to the same ID scalar, ensuring consistency.

8. File Preservation (GQLKeep)

Preserve sections between regenerations:

Place custom code between markers in your schema files and it won’t be overwritten.

9. CLI & Watcher Settings

Configure file-watching for automatic schema regeneration during development.

Enable Watch Mode

Usage:

The tool monitors configured packages and regenerates schemas on file changes.

Debounce Delay

Delay in milliseconds before regenerating after file changes:

Recommended values:

• 100-300ms - Fast feedback, may trigger multiple times
• 500ms - Balanced (default)
• 1000ms+ - Slower, fewer regenerations

Additional Paths

Monitor additional directories beyond configured packages:

Use case: Watch configuration files or shared type definitions.

Ignore Patterns

Exclude directories from watching:

Default patterns: vendor, node_modules, .git

Watch Mode Example

Complete watcher configuration:

Terminal output:

Generate Your Schema

Once the config is set up:

$ gqlschemagen generate

This processes all annotated structs and outputs schema files according to your chosen strategy.

Example output:

Full Example Configuration

Below is the complete recommended config.

To learn how to annotate your structs and generate your first types, continue to the GQL Types guide.