What does additionalProperties do in an OpenAPI schema, and when is false a mistake?

## The three forms `additionalProperties` applies to an object schema and decides what happens to keys not named in `properties` (nor matched by `patternProperties` in the JSON Schema 2020-12 dialect OpenAPI 3.1 uses). 1. **Omitted, or `true`** — undeclared keys are allowed and unconstrained. This is the default, and it is why a bare `type: object` accepts absolutely any object. 2. **`false`** — an undeclared key makes the instance invalid. This is "closed content" or strict validation. 3. **A Schema Object** — undeclared keys are allowed, but each of their *values* must satisfy that schema. ## Modelling maps Form 3 is how OpenAPI expresses a dictionary. `type: object` with `additionalProperties: {type: string}` describes an arbitrary-keyed map of strings, and generators emit the target language's map type. Combine it with `properties` to describe an object with a fixed core plus typed extras: ``` type: object properties: id: { type: string } additionalProperties: { type: string } ``` Here `id` must be a string because `properties` says so, and every other key must also be a string because `additionalProperties` says so. Generators handle this shape with varying grace — many produce a class with an extra `additionalProperties` map field. A fully free-form blob is `type: object` with no `properties` and either no `additionalProperties` or `additionalProperties: true`. It is honest when the payload really is opaque (a metadata bag, a vendor passthrough) and lazy when it is not. ## Why false breaks allOf This is the single most common production failure involving the keyword. Given: ``` Dog: allOf: - $ref: '#/components/schemas/Animal' # declares name - type: object properties: breed: { type: string } additionalProperties: false ``` Each `allOf` branch is validated **independently** against the whole instance. The second branch declares only `breed`, so when it sees `name`, that is an undeclared key — and `additionalProperties: false` rejects it. No payload can ever validate. The strictness cannot "see" the sibling branch's properties. The fixes are: drop the strictness, flatten the composition into one schema that declares every property and then closes it, or (in 3.1's dialect) use `unevaluatedProperties: false` at the composed level, which is aware of what sibling subschemas evaluated. `unevaluatedProperties` is a JSON Schema 2020-12 keyword and therefore available in OpenAPI 3.1, not in 3.0. ## Why false hurts evolution The tolerant-reader principle says a consumer should ignore fields it does not understand, so a server can add a response field without breaking anyone. `additionalProperties: false` on a response schema inverts that: the moment the server adds `loyaltyTier`, every client validating against the published schema rejects the response. What was an additive change becomes a breaking one, and you learn about it from consumers rather than from your own tests. The balanced policy most teams land on: - **Requests: strict.** Rejecting an unknown key catches typos and silently-dropped fields early, and closes off mass-assignment-style surprises where a client sends a field you did not intend to accept. The cost is that adding a client-side field requires a spec update first, which is usually the right ordering anyway. - **Responses: tolerant.** Leave the default so the server can grow the payload additively. If you need to prevent accidental leakage, enforce that in the serializer, not in the published contract. Be aware that the strictness applies to whoever is *validating*. A gateway validating requests against the spec is the enforcement point; a schema that says `false` does nothing if nothing validates against it. ## Codegen behaviour Generators differ. Some map `additionalProperties: false` to a class that silently drops unknown fields; some to a strict deserializer that throws; some ignore the keyword entirely. Since the keyword's whole point is boundary behaviour, verify what your generator actually emits for each target language before treating it as enforcement. ## A quick decision guide - Free-form metadata bag? `additionalProperties: true` (or a value schema) — and say so in the description. - A typed map? `additionalProperties: {…}`. - Strict request validation with no composition? `additionalProperties: false` on a single flat schema. - Strict validation *with* composition, on OpenAPI 3.1? `unevaluatedProperties: false` at the top level. - A response contract you intend to grow? Leave it open.