What changed about data types in OpenAPI 3.1?

OpenAPI 3.1 is fully aligned with JSON Schema 2020-12. The standalone nullable keyword from 3.0 is removed; instead you express null with a type array such as type: [string, null]. The type keyword can also be a list, and exclusiveMinimum/Maximum became numbers rather than booleans.

How do I make a field nullable in OpenAPI 3.1?

Use a JSON Schema type array: set type to [string, null] (or include null among the allowed types). The 3.0-era nullable: true is no longer valid in 3.1. If you must stay on 3.0, keep nullable: true alongside a single type.

What is the difference between int32 and int64?

Both are integer types; the format is a hint about the expected size. int32 is a signed 32-bit integer (about ±2.1 billion) and int64 is a signed 64-bit integer (about ±9.2 quintillion). Note that JSON numbers and JavaScript cannot safely represent the full int64 range, so int64 is often serialised as a string.

Are OpenAPI formats validated?

Format is primarily an annotation. Some tools validate well-known formats like date-time, email and uuid, but many treat format as documentation only. Do not rely on the consumer enforcing a format; add explicit pattern, minimum or maxLength constraints where correctness matters.

Can I define custom formats?

Yes. The format keyword is an open string, so you can use custom values like format: phone or format: iso-currency for documentation. Validators ignore formats they do not recognise, so pair a custom format with a pattern regex if you need the constraint actually enforced.

OpenAPI Data Types Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

OpenAPI describes the shape of API data using JSON Schema’s primitive types (string, number, integer, boolean, array, object, null) refined by an optional format keyword. Choosing the right type/format pair makes generated clients, server stubs and documentation accurate. This reference lists the common combinations and their semantics.

How it works

Every schema in an OpenAPI document has a type. For scalar types a format narrows the meaning — for example type: string, format: date-time means an RFC 3339 timestamp, and type: integer, format: int64 means a 64-bit integer. Tooling uses these to pick the right language type (e.g. OffsetDateTime, UUID, long) when generating code. In OpenAPI 3.1, schemas are pure JSON Schema 2020-12, so null is expressed with type arrays rather than the old nullable keyword.

Nullable in 3.0 vs 3.1

# OpenAPI 3.0
nickname:
  type: string
  nullable: true

# OpenAPI 3.1 (JSON Schema 2020-12)
nickname:
  type: [string, "null"]

Notes and tips

Treat format as a hint: many validators ignore formats they do not recognise, so add explicit constraints (pattern, minimum, maxLength) when correctness matters. Because JSON and JavaScript cannot represent the full int64 range safely, large identifiers are often modelled as type: string even though they are numeric. Custom formats are allowed and simply pass through as documentation.