Schema Objects

## The shape everyone gets wrong first In a Schema Object, requiredness is declared at the level of the *containing object*, not the property: ``` type: object properties: id: { type: string } nickname: { type: string } required: [id] ``` The common error is writing `required: true` inside the `id` property's schema. In a Schema Object that key is meaningless — it is not part of the JSON Schema vocabulary for a property — and most validators ignore it silently, so the document looks fine and enforces nothing. The confusion is understandable, because OpenAPI *does* use a boolean `required` in two other places: the Parameter Object (`required: true`, and it MUST be true for a path parameter) and the Request Body Object. Those are not Schema Objects. Inside a schema, requiredness is always the array form. ## What required asserts Exactly one thing: the named key is present in the object. It says nothing about the value beyond what the property's own schema says. The consequence that trips people up is null. If a property's schema permits null, then `{"id": null}` satisfies a `required: [id]` constraint — the key is there. Permitting null looks different by version: OpenAPI 3.0 uses the OpenAPI-specific `nullable: true` keyword; OpenAPI 3.1, aligned with JSON Schema 2020-12, uses a type array such as `type: ["string", "null"]`. So four combinations exist and all are meaningful: - required, not nullable → key must be present and hold a real value. - required, nullable → key must be present but may be explicitly null ("the caller must tell us, and 'nothing' is a valid answer"). - optional, not nullable → key may be absent; if present it holds a real value. - optional, nullable → key may be absent or explicitly null. This is usually a modelling smell, because absent and null then mean the same thing to the consumer and generated code cannot distinguish them without extra machinery. That third and fourth distinction matters most in PATCH payloads, where "field omitted" (leave it alone) and "field set to null" (clear it) are genuinely different instructions. ## required and readOnly / writeOnly OpenAPI adds `readOnly` and `writeOnly` to the schema vocabulary. The specification states that if a property is `readOnly: true` and appears in `required`, the requirement applies to the response only — a client must not send it, and a server must return it. `writeOnly: true` is the mirror image: required on the request, absent from the response. This is how one schema serves both directions for a resource with a server-assigned `id` or a write-only `password`. ## What generators do with it Code generators map required-ness directly onto the target language's nullability or optionality: - Required, non-nullable → a non-optional constructor parameter or field. - Optional → a nullable field, an `Optional`, or a field with a default, depending on the generator. So `required` is not merely documentation: it decides whether a consumer's code compiles when a field is missing. Under-declaring required fields produces SDKs full of optionals that callers must unwrap defensively; over-declaring them makes an additive server change a breaking client change, because a field the server stops sending now fails deserialization. ## Two smaller gotchas **Listing a name that has no property.** `required: [phone]` with no `phone` in `properties` is legal JSON Schema — it demands a key whose value is unconstrained. It is almost always a typo, and a good linter flags it. **required with composition.** When a schema is assembled from `allOf` branches, the `required` array in one branch refers to property names in the combined instance, not only to properties declared in that same branch. A branch can therefore require a property that a sibling branch declares. ## The interview answer in one line Required is an array on the object, it means "key present", and it is orthogonal to whether the value may be null.