What does `extend type` do in GraphQL SDL, and what may an extension not do?

## The construct `extend type Seat { ... }` is a statement about a type that already exists: somewhere in this type system there is an object type called `Seat`, and these fields, interfaces or directives belong to it too. After assembly there is exactly one `Seat`, carrying everything its original definition and all of its extensions declared. Every definition kind has an extension form, and they all work the same way: * `extend type` — adds fields, interfaces, directives to an object type * `extend interface` — adds fields, interfaces, directives to an interface * `extend union` — adds members * `extend enum` — adds values * `extend input` — adds input fields * `extend scalar` — adds directives * `extend schema` — adds root operation types or directives to the schema definition ## Why the specification has it The stated motivation is representing a type system that has been extended from an original one: a caller adding fields it only knows about locally, or a service whose schema is genuinely an extension of another description. The everyday use is more mundane — one service splitting a large schema by concern so that a document boundary follows an ownership boundary. A seating document defines `Seat`; a loyalty document adds the one field loyalty cares about; nobody edits anyone else's file. ```graphql # seating type Seat { number: String! cabin: CabinClass! blocked: Boolean! } # loyalty extend type Seat { upgradeEligible: Boolean! } extend schema { subscription: SeatMapSubscription } ``` ## The rules an extension must satisfy Type-system validation enforces roughly this set: 1. **The named type must already be defined, and be the same kind.** You cannot extend a type nobody declared, and you cannot extend an object type with an `extend interface`. 2. **No duplicate field names.** A field declared by the extension must not already exist on the original type or on any other extension of it. 3. **No duplicate non-repeatable directives.** If the original already carries a non-repeatable directive, an extension may not apply it again. 4. **Added interfaces must not already be implemented, and must be satisfied.** If the extension says `implements Bookable`, the assembled type — original plus every extension — must declare every field `Bookable` requires, with matching arguments. 5. **The result must be a valid type of its kind**, judged after assembly rather than per document. ## Additive only — there is no override This is the point interviews turn on. If the seating document declares `blocked: Boolean!` and a second document writes `extend type Seat { blocked: Boolean }`, hoping to relax the nullability, the build fails. It does not take the later declaration, it does not take the earlier one, and it does not depend on which document was read first. Extension is *addition with collision as an error*, which is what makes it safe for several teams to write into one type: nobody can silently change the meaning of somebody else's field. The same applies to `extend schema`. Adding a subscription root that is already declared is an error, not a replacement. ## Not inheritance, not a subtype An extension produces no new type. There is no `Seat` and `ExtendedSeat`; there is one `Seat`, and every field that returns a `Seat` — including ones written before the extension existed — now sees the added fields. Candidates who describe `extend` as a subclassing mechanism are reaching for the wrong model entirely: GraphQL's shared-contract mechanism is the interface, and `extend` is closer to filling in a form that has already been started. ## Extensions carry no description of their own The grammar gives a type extension no description slot. Documentation of the type belongs to its original definition. Fields declared *inside* an extension do carry their own descriptions normally — it is only the extension as a whole that cannot be described. Practically that means the extending team can document what it added but cannot re-document the type. ## Where extensions go Extensions are resolved when the type system is assembled, before any operation runs. Introspection shows the merged type and nothing about provenance: a client cannot tell that `upgradeEligible` arrived from a different document than `number`, and there is no per-request cost — a peak of 1,200 requests a minute pays nothing for however many extensions the schema was built from. ## What `extend` is not for It is not a mechanism for combining several *services* into one graph; that is a separate composition problem with its own machinery. It is not a versioning device — you cannot extend your way to a changed field. And it is not a way to make a type conditional: everything an extension adds is unconditionally part of the schema every client introspects.