How to fix an invalid schema type in OpenAPI

OpenAPI does not use date, email, uuid, or int64 as schema types. These values are formats that refine a base JSON type.

Broken YAML

This response uses date as the type:

openapi: 3.1.0
info:
  title: Events API
  version: 1.0.0
paths:
  /events:
    get:
      operationId: listEvents
      responses:
        '200':
          description: Events returned
          content:
            application/json:
              schema:
                type: date

Why it fails

date is not a JSON Schema type. A calendar date is serialized as a string, then described with format: date. Redocly reports that type can only use the supported values and points to type: date.

Use format for semantic hints. Keep type aligned with the actual JSON value sent over the wire.

Corrected YAML

Use a string type with the date format:

openapi: 3.1.0
info:
  title: Events API
  version: 1.0.0
paths:
  /events:
    get:
      operationId: listEvents
      responses:
        '200':
          description: Events returned
          content:
            application/json:
              schema:
                type: string
                format: date

The same pattern applies to string formats such as date-time, email, and uuid. Use type: integer with format: int64 for a JSON integer.

OpenAPI 3.0 vs 3.1

OpenAPI 3.0 accepts the base types string, number, integer, boolean, array, and object. It uses nullable: true when the value can also be null.

OpenAPI 3.1 follows JSON Schema 2020-12. It also supports null and type arrays such as type: [string, 'null']. It still does not make date a type. Use type: string and format: date in both versions.

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 schema removes the structural invalid-type error. Format support can vary by downstream validator, so also test representative payloads when format enforcement matters.