GQL Types
GQLSchemaGen generates GraphQL object types directly from your Go structs, but only for types that are explicitly annotated. To include a struct in schema generation, add the @GqlType annotation above your type:
This will produce:
Additional Fields with @GqlTypeExtraField and @GqlExtraField
Sometimes you need fields in your GraphQL API that don't exist in your Go structs. GQLSchemaGen supports this through three directives:
@GqlTypeExtraField— adds fields only to GraphQL types@GqlInputExtraField— adds fields only to GraphQL inputs@GqlExtraField— adds fields to both GraphQL types and inputs
Adding Type-Only Fields with @GqlTypeExtraField
Use this directive when the extra field should appear on the GraphQL type only, not on the input.
This generates a posts field on the GraphQL type without requiring it in your Go struct:
Adding Fields to Both Types and Inputs with @GqlExtraField
If the extra field should exist on both the GraphQL type and the input type, use @GqlExtraField instead:
This produces the field on both structures:
Use @GqlTypeExtraField for type-only additions, and @GqlExtraField when inputs need to mirror those fields as well.
Directive Parameters Reference
Use these directives to control which Go structs and fields are included in your GraphQL schema and how additional fields are added.
| Directive | Parameter | Description | Example |
|---|---|---|---|
@GqlType | name | The GraphQL type name to generate. | "UserProfile" |
@GqlType | description | Documentation for the GraphQL type, included in the schema as a doc string. | "Represents a user in the system" |
@GqlType | namespace | Optional namespace for organizing schema files. Used with multiple files strategy. | "api/v1" |
@GqlType | ignoreAll | When true, ignores all struct fields by default (opt-in mode). Use with field-level rw tag or include. | ignoreAll:"true" |
@GqlTypeExtraField | name | Name of an additional field to include in the GraphQL type. | "posts" |
@GqlTypeExtraField | type | GraphQL type for the extra field. | "[Post!]!" |
@GqlTypeExtraField | description | Documentation string for the extra field. | "User's posts" |
@GqlTypeExtraField | resolver | Optional Go resolver function for computed fields. | "ComputePosts" |
@GqlTypeExtraField | tags | Optional Go struct tags to attach to the field. | "json:\"user_posts\"" |
@GqlTypeExtraField | on | Optional list of type names this field should apply to. Defaults to * (all types). Supports comma-separated lists or array syntax. | on:"Type1,Type2" / on:["Type1","Type2"] |
Accepted formats for on
- Comma-separated string
on:"Type1,Type2" - Array (double quotes)
on:["Type1","Type2"] - Array (single quotes)
on:['Type1','Type2'] - Apply to none
on:[]oron:"" - Apply to all types (wildcard)
on:"*"oron:["*"]
Field-level Struct Tags
Individual struct fields can be customized using the gql: struct tag. The first value in the tag defines the GraphQL field name. If you omit it (e.g., start with a comma), GQLSchemaGen falls back to the JSON tag or a transformed Go field name.
| Option | Description | Example |
|---|---|---|
| First value | Custom field name | gql:"userId" or gql:"userId,type:ID" |
| Omit name | Use JSON tag or transformed name | gql:",type:ID" |
type:value | Custom GraphQL type | gql:"createdAt,type:DateTime" |
description:value | Field documentation | gql:"email,description:User's email" |
deprecated | Mark field deprecated | gql:"oldField,deprecated" |
deprecated:value | Mark field deprecated with reason | gql:"oldField,deprecated:\"Use newField instead\"" |
ignore / omit | Skip field entirely | gql:"ignore" |
include | Include field even if @GqlIgnoreAll is used | gql:"include" |
optional | Make field nullable (removes !) | gql:"age,optional" |
required | Force non-null (adds !) | gql:"email,required" |
forceResolver | Adds @goField(forceResolver: true) for gqlgen | gql:"author,forceResolver" |
Read/Write Visibility Tags
GQLSchemaGen also supports fine-grained visibility rules for controlling whether fields appear in types, inputs, or both. These rules work independently of field names and are especially useful for sensitive or internal-only properties.
| Tag | Behavior | Example |
|---|---|---|
ro[:types] | Read-only: omitted from inputs | gql:"createdAt,ro" |
wo[:types] | Write-only: omitted from types | gql:"password,wo" |
rw[:types] | Read-write: included everywhere | gql:"name,rw" |
You can restrict these tags to specific GraphQL types or inputs by providing a comma-separated list (no spaces):
gql:"createdAt,ro:User,UserProfile"gql:"password,wo:UserInput"
Additional Rules and Behavior
omitandignorebehave identically- When using lists, no spaces between names (
ro:User,Admin, notro:User, Admin) - The
:is optional if you want the rule to apply to all generated types/inputsrois identical toro:*
- Names in lists must match the names defined in
@GqlTypeor@GqlInput - Visibility tags combine cleanly with all other modifiers
- Example:
These struct tags give you precise control over how each field is represented across your GraphQL schema—without altering your Go data models.
Type-Level Directives
@GqlInclude - Include Without Specifying Type/Input
Use @GqlInclude when you want a type to be included in schema generation but don't need to specify whether it's a type or input. This is particularly useful with auto-generation strategies:
Generates:
Use @GqlInclude when:
- You want both type and input generated automatically
- Working with auto-generation strategies (see Auto-Generation)
- You don't need custom names or descriptions
@GqlIgnoreAll - Opt-In Field Inclusion
Use @GqlIgnoreAll to ignore all struct fields by default, then selectively include fields using the include or rw tag:
Generates:
Use @GqlIgnoreAll when:
- Working with types that have many internal/sensitive fields
- You want a security-first approach (explicit opt-in)
- The majority of fields should NOT be exposed
Note: @GqlIgnoreAll can also be set per-type/input using the ignoreAll parameter:
Best Practices
- Use descriptive names and doc strings to generate self-documenting GraphQL types.
- Keep your Go struct fields aligned with your GraphQL type naming conventions (
camelCaseby default). - Use
@GqlTypeExtraFieldfor computed or virtual fields that exist only in GraphQL. - Use
@GqlIncludefor simple cases where you want both type and input generated. - Use
@GqlIgnoreAllfor security-sensitive types to ensure explicit field opt-in.
Once you have annotated your types, run:
$ gqlschemagen generateto produce your GraphQL schema.