How to fix "response description is required" in OpenAPI

Every inline OpenAPI Response Object needs a description. A response schema and media type do not replace this required field.

Broken YAML

The 200 response has content but no description:

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      operationId: getHealth
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object

Why it fails

The Response Object requires description. It is a short explanation of the response, such as Service status returned or User not found. Redocly reports The field description must be present on this level at the response object.

The response code is only a map key. The schema only defines the payload shape. Neither one describes the response in the place required by the specification.

Corrected YAML

Add description beside content:

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      operationId: getHealth
      responses:
        '200':
          description: Service status returned
          content:
            application/json:
              schema:
                type: object

OpenAPI 3.0 vs 3.1

OpenAPI 3.0 and OpenAPI 3.1 both require description on an inline Response Object. A reusable response under components.responses follows the same rule.

A Response Object can instead be a Reference Object. In that case, the referenced Response Object must contain the description. Do not add a description only beside a $ref and assume all tools will merge the fields.

Specification sections: OpenAPI 3.0.4 and OpenAPI 3.1.1.

Validate the fix

Save the complete document as openapi.yaml, then run:

pnpm --package=@redocly/cli@2.53.3 dlx redocly lint openapi.yaml --extends=minimal

The corrected response removes the structural missing-field error. The command can also report independent style warnings from the minimal preset.