Description
An object schema’s required list requires a property to exist, while properties constrains its value. A required name absent from the local properties can still be valid when additional properties are allowed or a composed schema defines it. Presence and type definition are distinct.
Potential impact
If the required value’s format is not defined anywhere, consumers may not know what to supply and type validation may be incomplete. Forbidding a required name through additional-property restrictions can create contradictory constraints.
Remediation
Review referenced and composed schemas and additionalProperties, then define necessary types and descriptions. Keep genuinely required properties in required; do not make them optional merely because a local definition is missing.
Examples
These OpenAPI 3.0 object-schema excerpts omit info and paths. The first already requires code and message. It permits additional properties, so a missing local definition for message does not by itself make the schema invalid.
Before
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer"
}
},
"required": [
"code",
"message"
]
}
}
}
}
After
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
]
}
}
}
}
The second adds a string type for message. It retains the presence requirement while describing the value format needed by the actual API.