What must a custom GraphQL scalar define beyond its name in the schema?

## The declaration says almost nothing ```graphql scalar GeoPoint ``` That is the entire SDL surface of a custom scalar. Unlike an object type, which enumerates its fields, or an enum, which enumerates its values, a scalar declaration is a *name and a promise*. Everything a caller would want to know — what shape the value has on the wire, what strings are acceptable, whether it is a number or text — lives outside the type system, in whatever the server implements and whatever documentation you attach. This is why the interview question is not "how do you declare one" but "what do you have to define". ## Two directions, three entry points A scalar is defined by coercion, and coercion runs both ways. **Result coercion** is the outbound direction. Whatever the resolver returned — a domain object, a date, a decimal, a pair of doubles — has to become a value that can appear in the response. This runs as the field's value is completed, and it is the last chance to reject nonsense: a scalar that quietly serializes an unrepresentable value ships corruption to clients, so a coercion that cannot succeed must fail instead. **Input coercion** is the inbound direction, and it has *two* entry points, because a caller can supply the value in two different ways. 1. As a **literal written inside the executable document**. This value arrives having been parsed as syntax, so what the scalar sees is a node with a kind: a string token, an int token, a float token, a list, an input-object shape. A `GeoPoint` scalar written to accept a string literal will simply reject `{ lat: 51.5, lon: -0.12 }` unless it was also written to accept an object node. 2. As a value in the request's **variables map**. That value has already been decoded from the request body, so the scalar receives a plain decoded value — a string, a number, a boolean, a list, a map — with no syntax node around it. The classic defect is a scalar that implements only one of the two. Everything passes review, because the tests use inline literals; then a client that parameterises the same argument as a variable starts failing, or vice versa. When you are asked this question, naming *both* input paths is the answer the interviewer is listening for. ## Coercion is where format is enforced A custom scalar is the only place the type system can say anything about *format*. The schema can say a field is a `GeoPoint`; it cannot say `GeoPoint` is `"lat,lon"` with six decimal places. So the coercion function is simultaneously a converter and a validator, and every rule you want enforced — the string parses, the range is sane, the precision is bounded — has to live there or nowhere. That gives custom scalars a genuinely useful property: validation happens *once*, at the boundary, for every argument and input field of that type across the whole schema, before any resolver runs. A fleet telematics graph that types every position argument as `GeoPoint` gets its coordinate validation in one place rather than in forty resolvers. ## What it costs on the other side of the wire The cost lands on clients, and it is worth being able to state it. Introspection reports a custom scalar as a scalar with a name — that, plus an optional specification URL, is the whole machine-readable story. So a typed client generator has no idea what `GeoPoint` is. Its options are to type it as an unknown/opaque value, or to be *configured* with a mapping from that scalar name to a client-side type. Every custom scalar you add is therefore a configuration entry in every client codebase that consumes the schema, and a scalar added without telling those teams shows up as an untyped hole in their generated code. There is a second, quieter cost: because the value is opaque to the type system, nothing stops two teams from meaning slightly different things by the same scalar name, and nothing catches it at composition time either. ## Two properties people forget * **A custom scalar is a leaf.** No selection set may be written beneath it, exactly like a built-in. If you want the client to pick parts of the value, you wanted an object type, not a scalar. * **A custom scalar may be used on both sides.** Scalars and enums are the two kinds of type valid as both output types and input types, so the same `GeoPoint` can be a field's type and an argument's type. Object types cannot do this — input positions need input object types. ## Spec versus convention The specification requires the coercions and requires that an impossible coercion raise an error rather than produce a value. It does *not* define any particular custom scalar: `DateTime`, `JSON`, `UUID`, `Long` and friends are conventions the ecosystem converged on, and two servers that both offer a `DateTime` are not guaranteed to agree on its serialization. How a server registers the coercion behaviour — which functions, which interface, which registration call — is entirely a matter of the server you are using, and no part of the specification.