Why is a custom executable directive in a GraphQL document not portable?

## What the specification actually mandates A conforming GraphQL schema carries a small set of built-in directives. On the **executable** side — the ones a client writes inside its document — there are exactly two: `@skip` and `@include`. On the **type-system** side — written in SDL, describing the schema — there are `@deprecated`, and `@specifiedBy` for pointing a custom scalar at its specification. That is the portable set. Everything beyond it exists because one schema author added it. This matters because "GraphQL supports custom directives" is true and misleading in the same breath. The specification supports *declaring* them: a schema may define a directive with a name, arguments and a location list, and clients may then apply it in those locations. What it does not do is say what applying one *means*. There is no execution rule attached to a custom directive anywhere in the specification. Semantics are implementation-defined, full stop. ## Failure mode one: the server has never heard of it A ticketing client sends a document that applies a directive its team invented for their own server: ```graphql query OrderTotals($orderId: ID!) { order(id: $orderId) { reference totalCents @currency(code: "EUR") } } ``` Against a server whose schema defines `@currency`, fine. Point the same document at any other GraphQL server — a staging environment built from an older schema, a partner's API, a public endpoint, a mock — and validation rejects it: ```json { "errors": [ { "message": "Unknown directive \"@currency\"." } ] } ``` This is a **request error**, so there is no `data` key and nothing in the document executes. A directive the target does not define is not silently ignored, and there is no "unknown directives are tolerated" mode in the specification. That is deliberate: silently dropping a directive whose whole purpose is to change behaviour would be worse than failing. Note how much stricter this is than `@skip`/`@include`, which are guaranteed present everywhere. A document restricted to the built-in executable directives runs against any conforming server; one custom directive binds it to a single schema. ## Failure mode two: the server has heard of it and means something else Suppose the target schema *does* define `@currency(code: String!) on FIELD`. Validation passes. Nothing guarantees you get the behaviour you expect, because nothing in the schema says what the behaviour is. One server might convert the amount; another might annotate the response; another might have defined it as a documentation marker that execution ignores entirely. The specification gives you no way to distinguish these. Introspection does not close the gap. A client can ask a server for its directives and get back, per directive, the **name**, an optional **description**, the **argument definitions**, the **locations** where it may be applied, and whether it is **repeatable**. Every one of those is structural. None of them is semantics. The description field is prose intended for a human reading documentation, not something a client can execute against. So a generic tool — an explorer, a typed client generator, a schema-diffing job — can tell you a custom directive exists and where it is legal, and can do precisely nothing useful with it. ## Failure mode three: the tooling on your own side Even within one organisation, custom executable directives leak. A typed client generator has no rule for what a custom directive does to a result type, so it generally ignores it — meaning generated types describe a shape the directive may have changed. Explorers will autocomplete it from introspection and give no hint about its effect. And support for even *reaching* a custom executable directive at execution time varies between server implementations: some expose a hook for it, some do not, and the ones that do disagree about ordering and about what a directive may modify. None of that variation is a bug in any of them, because there is nothing to conform to. ## What to do instead The portable way to express a per-request choice is the schema's own vocabulary, because that vocabulary *is* specified and *is* introspectable with types: * Want a currency? Make it an **argument**: `totalCents(currency: EUR)`, or expose a `totalIn(currency: Currency!): Money` field. The argument has a declared input type, it validates, it appears in generated code, and it works identically on every server. * Want a conditional? Use `@skip`/`@include`, which every server supports. * Want per-request metadata that is not really part of the graph — a trace id, a locale, a feature cohort? That belongs in a **transport header**, not in the document. The rule of thumb worth stating in an interview: a custom directive in an *executable document* couples that document to one server implementation, so keep them to schema-side annotations that tooling reads at build time, and express client intent through arguments and variables. And it is worth saying plainly which side of the line each claim sits on — that `@skip`/`@include` are specified, and that any behaviour attributed to a custom directive is a convention of one implementation.