Description
In OpenAPI 3.0 and Swagger 2.0, a schema declared as array must define its elements through items. Without it, document validation or code generation can fail, and consumers cannot consistently interpret the array’s contents.
Potential impact
Unclear element types can lead consumers to misunderstand request or response formats and cause integration errors.
Remediation
Define items with the element type or a schema reference. For OpenAPI 3.0 parameters, place it inside the schema. For Swagger 2.0 non-body array parameters, define items on the parameter itself.
Examples
These OpenAPI 3.0 schema excerpts omit the info and paths required for a complete document.
Before
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "array"
}
}
}
}
After
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
The before schema has no item definition. The after schema uses items.type: string to describe an array of strings. Verify that actual requests and responses follow that contract.