Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Specification Basics

OpenAPI Data Types and Formats: string, integer, number, boolean

Master OpenAPI data types and formats: string, number, integer, boolean, array, object, null, plus date-time, uuid, email, int64, binary and 3.1 type arrays.

Every value in a request or response has a type. OpenAPI describes types with a schema, and the most basic parts of a schema are type and format. Getting these right is what lets generators produce correct code (int versus long, string versus DateTime) and lets validators reject bad data.

The six JSON types, plus null

OpenAPI uses the JSON Schema types:

type What it holds Example values
string text "Fido", "2025-01-31"
number any numeric value, including decimals 3.14, 10
integer whole numbers 42, -7
boolean true or false true
array an ordered list [1, 2, 3]
object a map of named properties {"id": 1}
null nothing (3.1 only as a type) null

Format: a hint that refines the type

format is a free-text modifier. Tools understand common ones and ignore the rest, so inventing a format is allowed but is only a label.

type format Meaning
integer int32 32-bit signed integer
integer int64 64-bit signed integer (use for ids and timestamps)
number float / double single / double precision
string date full date, 2025-01-31 (RFC 3339)
string date-time date and time with offset, 2025-01-31T10:30:00Z
string password hint to hide the value in UIs
string byte base64-encoded characters
string binary raw bytes (file contents, 3.0 style)
string email, uuid, uri, hostname, ipv4, ipv6 well-known textual formats
YAML
Pet:
  type: object
  properties:
    id:        { type: integer, format: int64 }
    name:      { type: string }
    weightKg:  { type: number, format: float }
    adopted:   { type: boolean }
    birthDate: { type: string, format: date }
    createdAt: { type: string, format: date-time }
    owner:     { type: string, format: uuid }

Constraints on each type

Constraints (also called validation keywords) narrow what is allowed:

YAML
# strings
name:
  type: string
  minLength: 1
  maxLength: 80
  pattern: '^[A-Za-z ]+$'

# numbers and integers
age:
  type: integer
  minimum: 0
  maximum: 40
price:
  type: number
  exclusiveMinimum: 0      # in 3.1 this is a number; in 3.0 it was a boolean
  multipleOf: 0.01

# arrays
tags:
  type: array
  items: { type: string }
  minItems: 1
  maxItems: 10
  uniqueItems: true

# a closed list of values
status:
  type: string
  enum: [available, pending, sold]

Nullable values: 3.0 versus 3.1

This is a classic migration trap.

YAML
# OpenAPI 3.0
nickname:
  type: string
  nullable: true

# OpenAPI 3.1 (JSON Schema): type becomes an array
nickname:
  type: [string, "null"]

In 3.1 the nullable keyword was removed. Use a type array, or oneOf with { type: "null" }.

Defaults, examples and read-only data

YAML
limit:
  type: integer
  default: 20          # what the server assumes if the caller omits it
  examples: [10, 50]   # 3.1: a list of examples
id:
  type: integer
  readOnly: true       # only appears in responses
password:
  type: string
  writeOnly: true      # only appears in requests

A default is not an example: it changes behavior. Do not set one unless the server really applies it.

A type and format checker, as a stand-in

A validator walks a value and a schema together. This stand-in checks type, a few formats and the common constraints for single values. (A real validator handles the whole JSON Schema vocabulary.)

Python Stand-in: check values against type and format

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Choosing int32 or int64

JavaScript numbers are doubles and lose precision above 2^53. For large ids some APIs send them as strings (type: string, format: int64 is a common convention, though not part of the spec's own format list). Decide early and be consistent, because generated clients pick their types from this.

Dates and times

  • Use format: date-time for moments in time and always include a time zone (Z or an offset).
  • Use format: date for calendar days (birthdays).
  • Document the format in the description if you use anything else (for example Unix timestamps as integer with format: int64 and a description "seconds since 1970-01-01 UTC").

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which pair describes a 64-bit identifier?

    integer with format: int64 is the standard way to say 64-bit integer.
  2. 2. How do you allow null for a string in OpenAPI 3.1?

    3.1 follows JSON Schema, which uses a type array; nullable belongs to 3.0.
  3. 3. What does readOnly: true on a property mean?

    readOnly properties are sent by the server; clients should not send them.
  4. 4. A format that your tools do not recognise will...

    Formats are open-ended; unknown ones are typically ignored by tools.

Summary

  • Core types: string, number, integer, boolean, array, object and null.
  • format refines the meaning (int64, date-time, uuid, email).
  • Constraints such as minimum, maxLength, pattern and enum narrow the allowed values.
  • 3.0 uses nullable: true; 3.1 uses type arrays such as [string, "null"].
  • readOnly and writeOnly separate response-only and request-only fields.

Next: Paths and operations