Supported Types and JSON Schemas

The building blocks of your schemas

To define the structure of your responses, you have seven JSON types. Each serves a specific need in modeling your data. Understanding these types is essential for designing effective schemas.

The seven supported types

string

The most common type. Used for names, descriptions, identifiers, and any text content.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "description": { "type": "string" }
  }
}

number

Covers integers and floats. No distinction between integer and float — a single number type handles both.

{
  "properties": {
    "price": { "type": "number" },
    "quantity": { "type": "number" }
  }
}

boolean

True or false. Perfect for flags, validations, and binary decisions.

{
  "properties": {
    "in_stock": { "type": "boolean" },
    "express_delivery": { "type": "boolean" }
  }
}

object

Lets you nest structures. An object can contain other objects, arrays, or scalars — with no depth limit.

{
  "type": "object",
  "properties": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "postal_code": { "type": "string" }
      }
    }
  }
}

array

Lists of elements of the same type. You can have arrays of strings, numbers, objects, or even arrays.

{
  "properties": {
    "skills": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

enum

A finite set of allowed values. Essential for categorizations and classifications.

{
  "properties": {
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"]
    }
  }
}

anyOf

Lets you define type unions. A field can accept several different structures. Useful when a single field can take varied forms.

{
  "properties": {
    "contact": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "email": { "type": "string" }
          }
        },
        {
          "type": "object",
          "properties": {
            "phone": { "type": "string" }
          }
        }
      ]
    }
  }
}

Combining types

The power of schemas comes from combining these types. Here’s a realistic schema to analyze a product:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "price": { "type": "number" },
    "in_stock": { "type": "boolean" },
    "category": {
      "type": "string",
      "enum": ["electronics", "clothing", "grocery", "other"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "manufacturer": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "country": { "type": "string" }
      }
    }
  }
}

This schema mixes scalars, an enum, an array, and a nested object. The model will respect every constraint on every call.

Optional fields

To make a field optional, use anyOf with null:

{
  "properties": {
    "phone": {
      "anyOf": [
        { "type": "string" },
        { "type": "null" }
      ]
    }
  }
}

In Pydantic, this corresponds to phone: str | None.

Key takeaways

• Seven available types: string, number, object, array, boolean, enum, anyOf
• Types combine freely to model complex structures
• Optional fields use anyOf with null
• No integer/float distinction — a single number type
• enum forces predefined values for classifications