Fix OpenAPI additionalProperties Errors
An additionalProperties error means an object contains a field that its schema does not permit, or a dictionary value does not match the declared schema. Fix the contract owner rather than weakening validation blindly.
Find the exact instance and schema paths
Preserve a redacted failing payload and the complete validator message. Identify both the JSON instance path and the schema location. A nested error may refer to one item inside an array, not the top-level object. Resolve references and composed schemas before deciding which declaration applies. Different validators format paths differently, so confirm the actual offending property.
Understand strict object schemas
Object properties are normally declared under properties. Setting additionalProperties: false rejects keys outside the permitted set. This is useful for catching misspellings and contract drift, but it also makes additive API changes breaking for strict consumers. If the payload contains a typo, remove or rename that field. If the field is legitimate, add it to the correct schema and review compatibility.
Model dictionaries explicitly
For a map with arbitrary keys, set type: object and use a schema under additionalProperties to describe each value. A string map permits keys chosen at runtime while still requiring string values. Use a referenced schema for structured values. Do not list unknown future keys as fake fixed properties.
Inspect composed schemas
Errors often appear around allOf, oneOf, and inherited generated models. A strict subschema may reject properties introduced by another branch depending on the OpenAPI version, schema design, and validator behavior. Test the final resolved schema with the validators used in production and generation. Prefer a composition structure whose ownership of properties is explicit and supported by the target toolchain.
Check version and generator behavior
OpenAPI 3.0 and 3.1 use different Schema Object foundations, and tools implement features at different rates. Confirm the document version and validator support before copying a JSON Schema solution. Generated clients may represent a free-form object as a map, a language-specific object, or a dedicated model. Review generated output after changing strictness.
Choose strictness deliberately
Keep additionalProperties: false when rejecting unknown fields is part of the contract, such as configuration where typos are dangerous. Allow or type additional fields when extensibility is intentional, such as labels or metadata. Removing the keyword simply to pass one payload can hide producer mistakes. Validate locally with the OpenAPI Validator and inspect rules with the OpenAPI Linter.
Frequently Asked Questions
What does additionalProperties false do?
It rejects object keys that the schema does not permit.
How is a string dictionary described?
Use an object with a string schema under additionalProperties.
Should strictness simply be removed?
Only when arbitrary fields are genuinely part of the contract.