Namespaces

Organize Your Schema

Namespaces let you organize generated GraphQL schema files into subdirectories. This is especially useful for large projects with many types, making the schema easier to navigate.

GQLSchemaGen supports namespaces, which allow you to control where generated schema files are placed. Namespaces can be applied at the file level or on individual types, and they work with all generation strategies (single, multiple, or package).

File-Level Namespaces

To apply a namespace to all types in a file, use @GqlNamespace above your type definitions:

models/user_product.go

Behavior depends on your output strategy:

Multiple/package strategy: Each type generates its own file under the namespace directory: {output}/api/v1/User.graphql and {output}/api/v1/Product.graphql
Single strategy: All types in the namespace are combined into one file: {output}/api/v1.graphql

Type-Level Namespace Overrides

You can override the file-level namespace for specific types by setting the namespace parameter on @GqlType, @GqlInput, or @GqlEnum:

models/user_product_override.go

Resulting schema files:

User → {output}/user/auth/User.graphql (type-level override)
Product → {output}/common/Product.graphql (file-level namespace)

Combining Namespaces Across Files

When using the single strategy, types from multiple files that share the same namespace are merged into a single schema file. For example:

user.go

product.go

Both User and Product are generated into:

Custom Namespace Separator

By default, namespaces use / to create subdirectories:

You can change the separator if you prefer a flat file structure with a different naming convention:

Strategy-Specific Behavior

Strategy	Namespace Behavior
Single	Generates one file per unique namespace. Types sharing a namespace are combined.
Multiple	Combines namespace path with type name: `{namespace}/{typename}.graphql`.
Package	Combines namespace path with package name: `{namespace}/{package}.graphql`.

Parameters

Directive	Parameter	Description
`@GqlNamespace`	`name` (required)	The namespace path for generated files (e.g., `api/v1`, `user/auth`).
`@GqlType`, `@GqlInput`, `@GqlEnum`	`namespace`	Optional type-level override of the file-level namespace.

Notes

File-level @GqlNamespace must appear before any type, input, or enum definitions in the file.
Types without a namespace are generated into the root output directory.
Type-level namespaces always override file-level namespaces.
Using single strategy without namespaces combines all types into a single schema file.

Once your namespaces are configured, running:

$ gqlschemagen generate

will place your schema files according to the namespace rules.

Next: Keeping Schema Modifications