OpenAPI 3.0 vs 3.1: Schema Differences and Migration

What changes in the schema model?

OpenAPI 3.0 uses its own extended subset of an older JSON Schema draft. In 3.1, the default OpenAPI Schema Object dialect builds on JSON Schema 2020-12 and adds OpenAPI vocabulary. A 3.1 root Schema Object can declare a dialect with $schema; jsonSchemaDialect sets the document default. Check dialect support in your own tooling.

The openapi field identifies the document specification version. info.version labels your API contract. Updating either label alone does not establish whether an API change is compatible with existing consumers.

Null and a missing property are different

Null is a value; a missing key has no value to validate. In the examples below, id is required and nickname is optional. A nickname string or null is accepted, and nickname may also be absent. Removing id is not allowed. Making nickname required would still allow null but would disallow omitting that key.

For the simple 3.0 schema, nullable: true accompanies type: string in the same Schema Object. The 3.1 example uses type: [string, "null"]. Additional enum or composition constraints can change what is allowed; do not blindly rewrite a complex schema based only on this example.

Example: nullable text in OpenAPI 3.0

Paste the complete document into Version Checker to identify the 3.0 family, or into OpenAPI Validator for its selected structural checks. Neither tool validates response payloads against this schema.

openapi: 3.0.3
info: {title: Profile API, version: "1.0.0"}
paths:
  /profile:
    get:
      responses:
        "200":
          description: Profile returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Profile"
components:
  schemas:
    Profile:
      type: object
      required: [id]
      properties:
        id: {type: string}
        nickname:
          type: string
          nullable: true

Example: nullable text in OpenAPI 3.1

The quoted "null" is a JSON Schema type name. An unquoted null in a YAML type array becomes a null value instead of that string. For both intended schemas, {"id":"u-1"}, {"id":"u-1","nickname":null}, and {"id":"u-1","nickname":"Ada"} illustrate accepted shapes. {} and {"id":"u-1","nickname":17} do not satisfy the intended constraints.

openapi: 3.1.0
info: {title: Profile API, version: "1.0.0"}
paths:
  /profile:
    get:
      responses:
        "200":
          description: Profile returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Profile"
components:
  schemas:
    Profile:
      type: object
      required: [id]
      properties:
        id: {type: string}
        nickname:
          type: [string, "null"]

Reference behavior depends on where $ref appears

In 3.0, additional fields alongside a Reference Object's $ref are ignored. In a 3.1 Schema Object, $ref follows JSON Schema rules and sibling schema keywords can apply. That does not mean arbitrary siblings work everywhere: the separate 3.1 Reference Object outside Schema Objects supports summary and description where the referenced object type permits them, not every schema constraint.

When reviewing a reusable schema, check the reference's location, the target schema, and the declared dialect together. Small Tools comparison tools do not expand referenced definitions; a visible reference string is not a resolved schema.

A migration workflow for a real project

• Keep a versioned copy of the original contract and representative valid and invalid payloads.
• Confirm that each validator, renderer, client/server generator, and gateway you use understands the intended OpenAPI family and schema dialect. Test the exact versions installed in your project.
• Review nullable fields and other schema keywords individually. Do not treat a YAML-to-JSON conversion or a version-header edit as a semantic migration.
• Review references and constraints with version-aware validation, then generate documentation and client code in an isolated branch and inspect the results.
• Use Schema Diff to locate changed component names and Migration Report to summarize the documents. Test known consumers against the API; a report is not a compatibility verdict.

Common mistakes and the limits of these tools

• A structural success message does not prove correct JSON Schema semantics: the local validator can accept a 3.0 document containing a 3.1-style type array.
• Version Checker reads the declared version family. It does not inspect every schema or certify migration readiness.
• Formatters and YAML/JSON converters preserve a representation of parsed data; they do not convert nullable semantics or repair every invalid keyword combination.
• Schema Diff compares serialized component definitions. A Changed schema can represent an equivalent rewrite, while referenced definitions still need separate inspection.

Frequently asked questions

Should I always migrate to 3.1? Choose based on the capabilities and requirements of your project and its consumers. Verify your complete tooling chain rather than selecting a family from its version number alone.

Does nullable: true make a property optional? No. Requiredness is determined separately by the containing object's required list. Allowing null and allowing omission are different decisions.

Can Small Tools convert a 3.0 contract to a fully verified 3.1 contract? No. The linked tools help identify versions, inspect structure, compare components, and change YAML/JSON representation. They do not perform a complete semantic migration.

Privacy and practical use

The linked tools process pasted contracts in your browser. They do not call the listed API servers or fetch external references. Use redacted specifications when sharing review output, and keep consumer tests and version-aware validation in your own project.

Related tools

• OpenAPI Validator — Check OpenAPI documents for valid YAML or JSON and essential structure.
• OpenAPI Version Checker — Identify an OpenAPI version and report whether this toolset checks its version family.
• OpenAPI Schema Diff — Compare named component schemas between two OpenAPI documents.
• OpenAPI Migration Report — Summarize endpoint, component schema, version, and server URL changes between two specifications.
• OpenAPI YAML to JSON — Convert an OpenAPI YAML document into formatted JSON.

References

• OpenAPI 3.0.3 — Schema Object
• OpenAPI 3.1.0 — Schema Object and dialects
• OpenAPI 3.1.0 — Reference Object
• JSON Schema — null versus absence