What are GraphQL directives and what are common built-in ones?
Learn what GraphQL directives are, how executable and type-system directives differ, and the common built-in ones every server supports, with clear examples.
Expected Interview Answer
GraphQL directives are annotations prefixed with @ that attach declarative instructions to a query, mutation, or schema element, telling the execution engine to alter behavior at that location without changing the underlying resolver logic.
They come in two flavors: executable directives used inside operations (like @skip, @include, @defer) and type-system directives used inside the schema (like @deprecated, @specifiedBy). The three built-in executable directives every spec-compliant server must support are @skip(if:), @include(if:), and @deprecated. Directives can be defined by anyone with a directive definition specifying its name, arguments, and valid locations, then applied wherever those locations occur.
- Conditionally include or skip fields at query time
- Mark fields and enum values as deprecated with a reason
- Enable server-driven features like @defer and @stream
- Keep behavior declarative instead of hardcoding it in resolvers
- Extend the schema with custom cross-cutting concerns like auth or formatting
AI Mentor Explanation
A directive is like the signals an umpire flashes with hand gestures over the ongoing play. The batters keep batting, but a raised finger for @skip removes a delivery from the count, while a wide-arm signal for @include adds extra runs. The players and pitch never change; only the umpire's annotation changes how that moment is scored and processed.
Step-by-Step Explanation
Step 1
Define the directive
Declare its name, arguments, and valid locations, e.g. directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT.
Step 2
Apply it in an operation or schema
Attach @directive after the field or type element it should modify, passing any required arguments.
Step 3
Engine reads the location
During validation and execution, the server checks that the directive is used only in its allowed locations.
Step 4
Behavior is altered
The execution engine applies the directive's rule, for example omitting a field when @skip(if: true).
Step 5
Result reflects the directive
The response is shaped by the directive without any resolver code being changed.
What Interviewer Expects
- Knows the @ prefix and declarative nature of directives
- Names @skip, @include, and @deprecated as built-ins
- Distinguishes executable vs type-system directives
- Understands directive locations restrict where they can be used
- Can mention custom directives for auth or formatting
Common Mistakes
- Confusing @skip and @include logic (they are inverses)
- Thinking directives require changing resolver code
- Believing custom directives are automatically executable on any server
- Forgetting @deprecated is a schema directive, not an operation one
- Not knowing directives are restricted to specific locations
Best Answer (HR Friendly)
“GraphQL directives are little tags starting with an @ that you attach to parts of a query or schema to change how they behave, like conditionally including a field or marking one as outdated. The common built-in ones are @skip, @include, and @deprecated.”
Code Example
query GetUser($withEmail: Boolean!, $expanded: Boolean!) {
user(id: "1") {
name
email @include(if: $withEmail)
phone @skip(if: $expanded)
}
}type User {
name: String!
username: String @deprecated(reason: "Use name instead")
}
scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")Follow-up Questions
- How do @skip and @include differ, and what happens if both are applied?
- How would you implement a custom @auth directive on the server?
- What are directive locations and why do they matter?
- What do @defer and @stream do and why are they useful?
MCQ Practice
1. Which three directives must every spec-compliant GraphQL server support?
@skip, @include, and @deprecated are the built-in directives required by the GraphQL specification.
2. What does @include(if: false) do to a field?
@include(if: false) excludes the field, the inverse of @skip(if: false).
3. Where is @deprecated typically used?
@deprecated is a type-system directive applied to schema fields and enum values to mark them as retired.
Flash Cards
What prefix marks a GraphQL directive? — The @ symbol, e.g. @skip.
Name the three built-in directives. — @skip, @include, and @deprecated.
@skip(if: true) does what? — Omits the annotated field from the response.
Executable vs type-system directive? — Executable runs in operations (@skip); type-system annotates the schema (@deprecated).