Fix nullable syntax errors in OpenAPI 3.0 and 3.1

OpenAPI 3.0 and 3.1 use different syntax for a value that can be a string or null. A 3.1 type array is invalid in a 3.0 document. A 3.0 nullable keyword does not express nullability in the OpenAPI 3.1 Schema Object dialect.

Broken YAML

This OpenAPI 3.0 document uses OpenAPI 3.1 syntax:

openapi: 3.0.3
info:
  title: Contacts API
  version: 1.0.0
paths: {}
components:
  schemas:
    Contact:
      type: object
      properties:
        phone:
          type: [string, "null"]

Why it fails

OpenAPI 3.0 supports a restricted Schema Object. Its type value must be one string, and null is not a supported type. OpenAPI 3.0 adds nullable: true as a separate modifier.

OpenAPI 3.1 uses JSON Schema 2020-12. In that dialect, null is a real type and type can be an array. The openapi version at the top of the file tells tools which rules to apply.

Corrected YAML

Keep the 3.0 version and use nullable: true:

openapi: 3.0.3
info:
  title: Contacts API
  version: 1.0.0
paths: {}
components:
  schemas:
    Contact:
      type: object
      properties:
        phone:
          type: string
          nullable: true

OpenAPI 3.0 vs 3.1

Use one form that matches the declared version:

# OpenAPI 3.0
type: string
nullable: true

# OpenAPI 3.1
type: [string, "null"]

Quote "null" in a YAML flow sequence. An unquoted YAML null value is not the JSON Schema type name.

Do not put both forms in one schema for compatibility. Convert the schema when you convert the OpenAPI version.

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

Run the command against the converted output, not only the source document. The OpenAPI 3.0 vs 3.1 guide lists other schema keywords that change at the same version boundary.