GraphQL directives can be used to transform the schema types, fields and arguments as well as modify the runtime
behavior of the query (e.g. implement access control, etc). Common use cases involve limiting functionality based on the
user authentication and authorization. While GraphQL
spec specifies two types of directives -
executable (aka query) and
type system (aka schema) directives, only the latter one is supported by
@deprecated - schema directive used to represent deprecated portion of the schema.
See @Deprecated annotation documentation for more details
@skip - query directive that allows for conditional exclusion of fields or fragments
@include - query directive that allows for conditional inclusion of fields or fragments
Custom directives can be added to the schema using custom annotations:
The directive will then added to the schema as:
Directives can be added to various places in the schema. See the
graphql-java for a full list of valid locations.
As described in the example above, the directive name in the schema will by default come from the
@GraphQLDirective.name attribute which should follow
lowerCamelCase format. If this value is not specified, the
directive name will default to the normalized decapitalized name of the annotated annotation (eg:
the example above).
Directives allow you to customize the behavior of your schema based on some predefined conditions. Simplest way to
modify the default behavior of your GraphQLTypes is by providing your custom
KotlinDirectiveWiringFactory factory used by your
Example of a directive that converts field to lowercase
While you can manually apply all the runtime wirings to the corresponding GraphQL types directly in
SchemaGeneratorHooks#onRewireGraphQLType, we recommend the usage of our
to simplify the integrations.
KotlinDirectiveWiringFactory accepts a mapping of directives to corresponding wirings or
could be extended to provide the wirings through
KotlinDirectiveWiringFactory#getSchemaDirectiveWiring that accepts
While providing directives on different schema elements you will be able to modify the underlying GraphQL types. Keep in mind though that data fetchers are used to resolve the fields so only field directives (and by association their arguments directives) can modify runtime behavior based on the context and user input.
graphql-kotlin prioritizes manual wiring mappings over the wirings provided by the
This is a different behavior than
graphql-java which will first attempt to use
WiringFactory and then fallback to manual overrides.
For more details please refer to the example usage of directives in our example app.
Directives are applied in the order annotations are declared on the given object. Given
Directive1 will be applied first followed by the
Normally if you wanted to exclude a field or argument from the schema, you could use @GraphQLIgnore. However, due to reflection and kotlin limitations, the generated JVM code for interface arguments can only have annotations on getters.
This will generate the following schema