Keeping Schema Modifications
GQLSchemaGen is designed to be a source-of-truth generator: your Go structs define the schema, and running the generator keeps everything in sync. However, real-world GraphQL schemas often require hand-written additions—custom directives, complex unions, helper scalars, comments, or special fields that don’t belong in Go models.
To support this, the generator includes a built-in mechanism to preserve hand-written modifications across regenerations.
How Preservation Works
You can wrap any part of a generated schema with special markers:
Anything between these markers is:
- Read from the existing schema file
- Not touched during regeneration
- Reinserted at the configured placement (start or end)
This allows you to safely mix generated content with manual edits without losing work.
What You Can Keep
The preserved block can contain any GraphQL schema definition:
- Custom directives
- Manually added
uniondefinitions - Complete type definitions (not fields inside generated types)
- Comments or documentation blocks
- Temporary or experimental schema pieces
- Custom imports for downstream tools (e.g., Apollo Federation directives)
GQLSchemaGen treats the preserved block as opaque text—it doesn't parse it, modify it, or validate it.
Marker Details
The default markers are:
They must be placed on their own lines. Anything between them is kept exactly as-is.
Important: The preserved block is placed either at the top or bottom of the generated schema file based on your keep_section_placement configuration. You cannot place preserved content inside generated types.
The generator will locate these blocks before regenerating the file and restore them at the configured placement (start or end).
Example: Adding a Custom Directive
Even if the generator rewrites the entire file, your directive stays intact.
Controlling Placement via Configuration
By default, preserved blocks are placed at the end of a generated schema file.
You can change this behavior in your gqlschemagen.yml:
Placement Options
| Value | Effect |
|---|---|
start | Your preserved modifications appear at the top of the generated schema. Useful for directives or scalar definitions. |
end | Preserved code is appended after the generated content. Best for unions, extra types, or helper fields. |
Marker strings can be customised if your project already uses similar comment patterns.
Notes & Best Practices
- One keep block per file is recommended, but multiple blocks are supported.
- The generator will warn if markers are malformed or mismatched.
- Avoid placing
@GqlKeepblocks inside lists or enums unless intentional; they will be preserved verbatim. - If you're working with version control, it’s often helpful to commit schema files before regenerating so you can easily compare changes.