Validation failure during OpenAPI 3.0 to 3.1 specification migration

Standard approach for backward compatibility

The safest way to keep legacy parsers working while adopting OAS 3.1 features is to avoid any construct that is only valid under JSON Schema 2020‑12. In practice this means either:

1. Maintain two separate documents – one marked openapi: 3.0.3 for legacy tooling and one marked openapi: 3.1.0 for newer validators.
2. Or keep a single document at openapi: 3.1.0 but strip out or refactor the 3.1‑only schema keywords so the document remains a valid JSON Schema 2020‑12 instance that older validators can still parse.

Likely explanation of validation failures

When the openapi version string is bumped to 3.1, validators switch to enforcing JSON Schema 2020‑12 rules. Constructs that were tolerated in 3.0 (because they relied on the older OpenAPI‑specific schema dialect) are now rejected.

Confirmed facts about the failing schema properties

• example – allowed only inside a media type under content or as schema.example; a top‑level example key causes a validation error.
• discriminator – must include a propertyName and be accompanied by oneOf, anyOf, or allOf schemas; a standalone discriminator without these is invalid.
• nullable – is a standalone keyword, not a property; writing nullable: true as a sibling of other properties (e.g., type: string; nullable: true) is rejected.
• required – must be an array of strings; a boolean or string value triggers failure.
• Deprecated XML keys (attribute, prefix, namespace) – removed in 3.1; their presence leads to validation errors.

Steps to resolve the most common failures

1. Locate the validation error message (note the line number or snippet).
2. If the error mentions example, move the value inside the appropriate content block or replace it with examples under a media type.
3. If the error mentions discriminator, add a propertyName field and wrap the discriminator’s values in a oneOf array of schemas.
4. If the error mentions nullable, ensure it appears as a schema‑level keyword (e.g., nullable: true at the same level as type or schema) and not as a property.
5. Correct required to be an array of strings (["id", "name"]).
6. Remove any XML‑specific keys (attribute, prefix, namespace) unless you are using a vendor extension that explicitly supports them.
7. Re‑run your OpenAPI validator (Swagger CLI, Redocly CLI, Spectral, etc.) to confirm the document now passes.

If you need to keep a single source file for both old and new tooling, apply the above refactors; the resulting document will be valid under both OAS 3.0 (via its backward‑compatible mode) and OAS 3.1.