Description
items describes array elements. Adding it to an object or string schema does not constrain object fields or string contents. Keywords that do not fit the actual data type can mislead consumers about the API contract.
Potential impact
Consumers may assume intended validation applies or generate code using a type that differs from the actual data.
Remediation
For an actual array, define type: array and its element schema in items. For an object, use object constraints such as properties and remove irrelevant items. Do not arbitrarily change the API’s data type just to match a keyword.
Examples
These OpenAPI 3.0 schema excerpts omit info and paths. The comparison assumes the actual contract is an array of strings.
Before
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"items": {
"type": "string"
}
}
}
}
}
After
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
The before schema’s items does not constrain object fields to strings. The after schema declares a string array. If the actual data is an object, define its properties correctly instead of changing its type.