How to fix an OpenAPI array schema missing items

An array schema without items does not tell an SDK generator what each element contains. OpenAPI 3.0 rejects this shape. OpenAPI 3.1 permits it as an unconstrained JSON Schema array, but the missing element schema still gives generated clients no useful item type.

Broken YAML

This OpenAPI 3.0 response declares an array without an element schema:

openapi: 3.0.3
info:
  title: Tags API
  version: 1.0.0
paths:
  /tags:
    get:
      operationId: listTags
      responses:
        '200':
          description: Tags returned
          content:
            application/json:
              schema:
                type: array

Why it fails

The OpenAPI 3.0 Schema Object requires items when type is array. The items schema defines one array element. Without it, OpenAPI 3.0 cannot describe the response element type.

Do not replace items with properties. Properties describe an object. An array needs items, and that item schema can then be an object with properties.

Corrected YAML

Add the element schema:

openapi: 3.0.3
info:
  title: Tags API
  version: 1.0.0
paths:
  /tags:
    get:
      operationId: listTags
      responses:
        '200':
          description: Tags returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

For an array of objects, put an object schema or a $ref under items.

OpenAPI 3.0 vs 3.1

OpenAPI 3.0 requires items for every array schema. OpenAPI 3.1 uses JSON Schema 2020-12, where omitting items is valid and means that item values are not constrained.

This difference matters when the document feeds code generation. A valid but unconstrained 3.1 array can leave a generator with only an unknown or generic item type. Add items in both versions when the API has a known element shape.

# Recommended in OpenAPI 3.0 and 3.1
type: array
items:
  $ref: '#/components/schemas/Tag'

Validate the fix

For an OpenAPI 3.0 document, open the Sourced OpenAPI validator, paste the complete document, and select Validate spec. It reports every OpenAPI 3.0 array schema that has no items field.

For OpenAPI 3.1, a clean structural validation result does not prove that the array has a useful item type. Keep a content review or generator contract that rejects unconstrained arrays when typed SDK output is required.