OpenAPI 3.1 Migration Failures: When Validators Reject Retained 3.0 Keywords

The problem: 3.1 rejects documents that still speak 3.0

After changing the root openapi field from 3.0.x to 3.1.x, validation pipelines that previously passed begin failing, or generated SDKs silently drop nullable fields. The document is often structurally sound; the failure comes from three retained OpenAPI 3.0 patterns that 3.1 either ignores or reinterprets under its JSON Schema alignment.

The practical takeaway: OpenAPI 3.1 is not a drop-in replacement. Before validators and code generators will accept the document, you must rewrite nullable, boolean exclusiveMinimum/exclusiveMaximum, and singular example keywords.

Recognizable condition

You are likely hitting this migration failure if you observe one or more of the following after bumping the version string:

• A version-aware validator reports unexpected or unknown keywords such as nullable or schema-level example.
• Generated client or server types are non-nullable even though the source document contains nullable: true.
• Numeric bound assertions in generated code are missing, or the generator rejects boolean values for exclusiveMinimum and exclusiveMaximum.
• Documentation portals render no examples for schemas that previously displayed them.

Cause and diagnostic table

Symptom	Retained 3.0 pattern	3.1 behavior
Validator warns about unknown keyword nullable	nullable: true on a schema	3.1 ignores nullable; nullability must be expressed in the type array
Generated types lack null checks or optional markers	nullable: true retained	Generators targeting 3.1 skip the ignored keyword
exclusiveMinimum/exclusiveMaximum rejected or ignored	Boolean values (true/false) paired with minimum/maximum	3.1 expects numeric bound values, not boolean flags
Examples missing from docs or validation	Singular example object at schema level	3.1 aligns with JSON Schema examples; singular example is deprecated in many contexts

Ordered checks

1. Confirm the declared version. From the directory containing your spec file, run grep -n "^openapi:" openapi.yaml. Replace openapi.yaml with your actual filename. No elevated permissions are required beyond read access. Expected check: the output should show 3.1.x. If it shows 3.0.x, validators will apply the wrong dialect and the remaining checks are moot.
2. Grep for legacy keywords. From the same directory, run grep -rnE "nullable|exclusiveM(inimum|aximum)|example" . to locate retained 3.0 patterns. Replace . with your spec directory if needed. Inspect each match: example also appears legitimately in Media Type and Parameter Objects, so do not assume every hit is a schema-level leftover.
3. Validate with a version-aware tool. Run a linter or schema validator that understands the exact OpenAPI version declared in the document. A generic JSON Schema validator may not enforce OpenAPI-specific constraints.

Fixes tied to their findings

Restore nullability with a type array

If the grep in check 2 finds nullable: true, replace it with a type array that includes the string "null".

# Before (3.0)
type: string
nullable: true

# After (3.1)
type: [string, "null"]

In YAML, quote "null" so it is parsed as the string null rather than the YAML null value. After the change, regenerate artifacts and confirm the produced type is nullable or optional.

Convert boolean exclusive bounds to numeric values

If the grep finds boolean exclusiveMinimum or exclusiveMaximum, convert them to numeric bounds. In 3.0, exclusiveMinimum: true modified the adjacent minimum. In 3.1, the keyword itself carries the numeric value.

# Before (3.0)
minimum: 0
exclusiveMinimum: true

# After (3.1)
exclusiveMinimum: 0

Remove the now-redundant minimum or maximum to avoid ambiguity. Verify that generated assertions reflect the strict inequality.

Migrate singular example to the examples array

If the grep finds schema-level example, migrate it to the examples keyword. The exact shape depends on the object location: Schema Objects in 3.1 follow JSON Schema and expect an array of instance values, while Media Type and Parameter Objects use a map of named Example Objects. Review the 3.1 specification for the location you are editing.

# Before (3.0, schema level)
type: string
example: "hello"

# After (3.1, schema level)
type: string
examples:
  - "hello"

Do not apply a blind regex replacement. The 3.0 singular example and the 3.1 examples keyword have different shapes, and automated converters can silently drop or reinterpret them, breaking example rendering in documentation UIs.

Escalation criteria

Escalate to the tooling owner or platform team when:

• Custom internal validators or API gateways hardcode OpenAPI 3.0 keyword handling and cannot parse 3.1 documents even after the fixes above.
• Older client or server generators reject 3.1-only constructs such as type arrays and no maintained upgrade path exists.
• Automated spec converters produce output that still fails validation, indicating the converter itself does not fully support the 3.1 dialect.

In these cases, the blocker is downstream tooling compatibility, not the specification document.

Limitations and practical verification

OpenAPI 3.1 is not a drop-in replacement for 3.0. Downstream consumers may reject documents that use 3.1-only constructs, so confirm that every consumer in your pipeline supports the new dialect before completing the migration.

To verify the result:

1. Validate the document with a linter configured for the exact openapi version declared at the root.
2. Generate client and server artifacts, then inspect the generated types for nullable fields and numeric bound assertions.
3. Extract individual schema objects and validate them against the OpenAPI 3.1 dialect using a standard JSON Schema validator.

Because tooling support for 3.1 varies by vendor and version, treat the generated output as the final source of truth for whether the migration succeeded.