Nullable by Default

## The default the specification chose GraphQL's type system has exactly two *wrapping* types: List and Non-Null. Everything else — object types, interfaces, unions, enums, scalars and input objects — is nullable the instant you declare it. There is no keyword that means "nullable"; nullable is simply what you get when you write a type name on its own. Non-Null is the opt-in, spelled as a trailing `!` after the type it wraps. This is the reverse of many programming languages, where a reference is non-null-ish by convention and optionality is the annotated case, and it is the single most common source of surprise for someone reading SDL for the first time. In a course-enrolment graph the choice reads directly off the schema: ```graphql type Enrollment { id: ID! course: Course! learner: Learner! finalGrade: String certificate: Certificate } ``` `id`, `course` and `learner` are promises: any `Enrollment` the server hands back will carry all three. `finalGrade` and `certificate` are not promises — a learner halfway through a course has no grade and no certificate, and null is the honest answer. ## What nullable actually means Nullable is a statement about the *value that may appear in the response*, and it binds both sides. For the server it is a permission: returning null there is a legitimate, in-contract answer. For the client it is an obligation: code reading that position must cope with null arriving, on every response, forever. Three things nullable is *not*, and all three are common misreadings: - It is not "optional to select". Which fields a client asks for is entirely the client's choice; a Non-Null field the client did not select simply is not in the response, and that is not a violation of anything. Absence-because-not-selected and null-because-nullable are different situations that happen to look adjacent. - It is not "the field might not be implemented yet". Nullable describes the value, not the maturity of the resolver behind it. - It is not about arguments. Whether a client *must supply* an argument is decided in the input position by a different combination of rules, and the two positions behave in opposite directions when you change them. ## Why the specification defaulted this way GraphQL was designed to answer one document from many independent sources — a relational store, a search index, a third-party service — and to return whatever it could rather than nothing. Nullable-by-default is what makes that possible: when one part of the response cannot be produced, there has to be somewhere in the response shape for the absence to sit. If every field were non-null by default, an ordinary domain absence like "this enrolment has no certificate yet" would have no legal representation at all, and schema authors would have to model absence with sentinel values or extra wrapper types. The default is also the safer starting point for a schema you have to live with. Nullable is the weaker, more permissive contract, and a weaker contract can be strengthened later. Starting from the stronger one and discovering you cannot keep it is the expensive direction. ## What Non-Null promises `!` is a promise made to every current and future client, and its cost is asymmetric. To the client it is a simplification: no null check, no defensive branch, and a typed client generator can emit a plain type instead of a nullable one. To the server it is a permanent constraint: that position must always be fillable, for every object of that type, under every backend condition, for as long as the field exists. That is why `!` belongs on things guaranteed by the object's own identity — an `id`, a `createdAt`, a `Course` an `Enrollment` cannot exist without — and not on things that merely happen to be populated in today's data. The wrapper is visible in the schema itself: introspection reports it as a type of kind `NON_NULL` whose `ofType` is the wrapped type, which is exactly how schema-diffing tools and client generators see nullability rather than by parsing the `!` character. ## Reading a response ```json { "data": { "enrollment": { "id": "enr_8412", "finalGrade": null, "certificate": null } } } ``` Nothing here is anomalous. `finalGrade` and `certificate` were declared nullable, the learner is still enrolled, and null is the modelled answer. A client written against this schema must treat that response as completely ordinary — which is the whole point of the default.