#2638·ajv

feat: Global additionalProperties validation option

Author: luke-perry-ckCreated Jun 22, 2026Updated Jun 22, 2026
Labelsenhancement

What version of Ajv you are you using?

8.20.0

What problem do you want to solve?

I want to override how additional (unknown) object properties are handled across all schemas validated by an Ajv instance, without editing each schema's additionalProperties keyword.

Today the only instance-level control over additional properties is removeAdditional, which mutates the data by stripping the extra properties. There is no equivalent option that simply validates — i.e. globally rejects additional properties (or globally allows them) while leaving the data untouched.

Concretely:

  • I want to enforce a strict "no unknown properties" policy on every object schema (treat additionalProperties as false everywhere) and get a validation error rather than have the data silently modified.
  • Conversely, I sometimes want to relax schemas that declare additionalProperties: false and accept the extra properties without changing the schemas themselves.

What do you think is the correct solution to problem?

Add a new instance option additionalProperties with three values:

  • "default" (default) — respect each schema's additionalProperties keyword (current behavior).
  • "alwaysAllow" — additional properties are always allowed regardless of the schema; the keyword is treated as true (never validated against a subschema, never rejected).
  • "alwaysError" — additional properties always produce a validation error; the keyword is treated as false.

Notes on the semantics:

  • Unlike removeAdditional, this option never modifies the data — it only affects validation outcomes.
  • "alwaysError" uses the same trigger model as removeAdditional: "all": it applies to object schemas that contain a properties, patternProperties, or additionalProperties keyword, not to a bare type: "object" schema with none of these.
  • If removeAdditional is also set, it takes precedence (additional properties are removed rather than producing an error).
  • The option is ignored for meta-schema validation (added to META_IGNORE_OPTIONS), so user schemas legitimately containing extra keywords still compile.

Will you be able to implement it? Yes, PR already open here: https://github.com/ajv-validator/ajv/pull/2637