The Specification Logic
Yes, the OpenAPI specification (and the underlying JSON Schema logic it employs) mandates that allOf acts as a logical conjunction. For a payload to be valid, it must satisfy every subschema listed within the allOf array. Consequently, if any subschema defines a property as required, that property must be present in the payload, regardless of whether the top-level schema or other subschemas also define required fields.
Required properties are not "merged" into a single list in a way that allows overrides; rather, they are cumulative. A parent schema's required list does not erase or supersede the requirements of a subschema.
Explanation of Tooling Inconsistency
The "Missing required property" error usually stems from a gap in tool implementation rather than a contradiction in the specification. While the spec is clear, validation tools vary in their depth of JSON Schema support:
- Validators: A fully compliant JSON Schema validator will reject any payload missing a property required by any
allOf component. Tools that only check the top-level schema are non-compliant.
- Swagger UI & ReDoc: These are primarily documentation and request-sending tools. They are not authoritative validation engines. If a field appears optional in the UI but is required in a subschema, it is a rendering limitation, not a specification rule.
- OpenAPI Generator: Behavior here is language-specific. Some generators flatten
allOf into a single class, while others use inheritance. If the generator fails to mark a subschema property as required in the target language (e.g., Java or TypeScript), the resulting code will not enforce the constraint at runtime.
Verification and Resolution Steps
To resolve the ambiguity and ensure your API is enforced correctly, follow these steps:
- Isolate the Schema: Create a minimal test case with one parent schema and one
allOf subschema, each with a unique required property.
- Test with a Standard Validator: Run the payload through a dedicated JSON Schema validator (supporting Draft 4 for OpenAPI 3.0 or 2020-12 for OpenAPI 3.1) rather than a UI tool.
- Inspect Generated Code: If using OpenAPI Generator, check the generated model files to see if the required property is marked as non-nullable or mandatory in the target language.
Missing Diagnostic Detail: To provide a specific fix for the "Missing required property" error, please provide the exact version of the validator or generator you are using and the OpenAPI version (3.0.x vs 3.1.x) declared in your document.
openapi