OpenAPI Data Types and Formats Reference
OpenAPI schemas describe the shape and constraints of API data. A format refines a base type for documentation and tooling, but validators and generators differ in which formats they enforce.
Core schema types
| Type | JSON values | Common constraints |
|---|---|---|
| string | Text | minLength, maxLength, pattern, enum, format |
| number | Any JSON number | minimum, maximum, multipleOf |
| integer | Whole numbers | minimum, maximum, multipleOf, format |
| boolean | true or false | const or enum where supported |
| array | Ordered values | items, minItems, maxItems, uniqueItems |
| object | Named properties | properties, required, additionalProperties |
JSON has one number syntax, while target languages split integers and floating-point values into sizes. Document ranges rather than assuming every consumer can represent arbitrarily large values exactly. JavaScript numbers, for example, cannot exactly represent every 64-bit integer.
Common string formats
| Format | Meaning |
|---|---|
| date | A full calendar date. |
| date-time | A timestamp using the RFC 3339 profile. |
| uuid | A UUID text representation. |
| An email-address syntax hint under tool-specific validation. | |
| uri | A URI syntax hint. |
| hostname | A host name syntax hint. |
| byte | Base64-encoded data in OpenAPI 3.0 conventions. |
| binary | Binary data representation in OpenAPI 3.0 conventions. |
Format behavior is not uniform. A renderer may show a specialized input while a validator treats the same format as annotation. Test critical formats in the actual server, client, linter, and generator. Add patterns only when they accurately represent the domain; a simplistic email regex often rejects valid addresses without improving security.
Numeric formats
OpenAPI commonly uses int32 and int64 with integer, and float and double with number. These guide code generation but do not change JSON wire syntax. Set minimum and maximum when the API has actual bounds. For money, prefer a documented decimal string or minor-unit integer when binary floating-point rounding is unacceptable.
Arrays
Every array schema should define items. Use minItems and maxItems for meaningful limits and uniqueItems only when equality semantics match the domain and validator cost is acceptable. Pagination collections usually wrap an array with cursor or link metadata rather than placing pagination fields on each item.
Objects and required fields
List property schemas under properties. The required array belongs to the object schema and names properties that must appear. Optional does not automatically mean nullable. Model arbitrary maps with a schema under additionalProperties; set additionalProperties false only when unknown fields must be rejected as part of the contract.
Nullability and OpenAPI versions
OpenAPI 3.0 uses its Schema Object rules, including the nullable keyword in supported positions. OpenAPI 3.1 aligns its Schema Object with a newer JSON Schema vocabulary and can represent null in the type system. Do not copy nullability syntax between versions without checking tool support. Validate the complete document after migration.
Examples and defaults
An example illustrates a value; it does not make invalid data valid. A default communicates behavior for an omitted value under the schema semantics and is not necessarily inserted by every tool. Keep examples free of secrets and ensure they validate. Test the specification with the OpenAPI Validator.
Frequently Asked Questions
Does format always validate?
No. Tool support varies.
How do date and date-time differ?
One is a calendar date; the other is an RFC 3339 timestamp.
How are string maps modeled?
Use object with string-valued additionalProperties.