by SchemaSafe (LX AI)

Last updated: 2026-11-04

additionalProperties and oneOf: two JSON Schema rules that surprise teams

JSON Schema Draft 2020-12 is a declarative contract, and two keywords cause most of the review-time confusion: additionalProperties and oneOf. Both are easy to write and easy to misread. The fix is usually not a new keyword — it is reading the error path and knowing what each keyword actually asserts.

additionalProperties is not a whitelist by itself

additionalProperties: false rejects keys that are not listed in the same schema object. It does not look at $ref targets, and it does not inherit from a parent schema. If properties is incomplete, a legitimate field is reported as an extra key; if a nested object is loosely typed, unknown siblings can still pass inside it.

What to check

• Every key the contract depends on appears in properties, including optional ones.
• additionalProperties sits next to properties at the level you mean, not only at the root.
• If extensions are expected, give additionalProperties a schema instead of false.

A typo such as userNmae is caught as an extra key — that is the keyword doing its job. The risk is the opposite case: a forgotten property list that makes the strictness look stronger than it is.

oneOf fails on overlap, not on mismatch

oneOf requires exactly one branch to validate. Two branches that both match produce an error even when the payload looks valid, which reads as a false alarm until you check the branches for overlap. Common causes are two object schemas that share most properties, or a string branch that also fits a format-constrained branch.

How to make branches disjoint

• Use anyOf when the real requirement is “at least one”.
• Add a const discriminator field that only one branch allows.
• Split required arrays per branch so each branch demands a distinct key.

Read the error path before editing the schema

Every SchemaSafe error carries an RFC 6901 JSON-pointer such as /items/0/price. The pointer tells you which field failed, and the error keyword tells you which rule failed. Fix the field it points at, re-run, and compare. Tuning the schema until the pointer disappears usually hides the real defect.

Two practical rules follow from this. First, treat a pointer that moved to a different path as a new error, not a fixed one. Second, keep the failing payload as a regression fixture so the same defect cannot return silently.

Where the validator stops

Structural conformance is all this checks: types, required, formats, and closed objects. Business rules, database state, and API contracts still need your own tests. SchemaSafe is decision-support for the structural layer; it is not proof that a payload is correct.

Validate a payload against your schema

Decision-support drafts. Not legal advice, certification, or proof that a payload is correct. Reviewed by SchemaSafe (LX AI), 2026-11-04.