Extra Data Types

Learn how to use specialized data types in FastAPI including UUID, datetime, timedelta, and more

Beyond basic types like str, int, and float, FastAPI supports many specialized data types from Python’s standard library and Pydantic.

Common Extra Data Types

FastAPI/Pydantic support these additional types with automatic validation:

• UUID: Universal Unique Identifier
• datetime: Date and time
• date: Date only
• time: Time only
• timedelta: Time duration
• frozenset: Immutable set
• bytes: Binary data
• Decimal: Precise decimal numbers

Complete Example

from datetime import datetime, time, timedelta
from uuid import UUID
from fastapi import Body, FastAPI

app = FastAPI()

@app.put("/items/{item_id}")
async def read_items(
    item_id: UUID,
    start_datetime: datetime = Body(),
    end_datetime: datetime = Body(),
    process_after: timedelta = Body(),
    repeat_at: time | None = Body(default=None),
):
    start_process = start_datetime + process_after
    duration = end_datetime - start_process
    return {
        "item_id": item_id,
        "start_datetime": start_datetime,
        "end_datetime": end_datetime,
        "process_after": process_after,
        "repeat_at": repeat_at,
        "start_process": start_process,
        "duration": duration,
    }

All these types are automatically:

• Validated from the request
• Serialized in the response
• Documented in OpenAPI

UUID Type

UUIDs are commonly used as unique identifiers:

from uuid import UUID
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: UUID):
    return {"item_id": item_id}

Valid UUID

curl http://localhost:8000/items/123e4567-e89b-12d3-a456-426614174000
# ✓ Valid UUID format

UUIDs are represented as strings in JSON but validated as proper UUID format.

DateTime Types

datetime - Date and Time

from datetime import datetime
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Event(BaseModel):
    name: str
    created_at: datetime
    updated_at: datetime | None = None

@app.post("/events/")
async def create_event(event: Event):
    return event

Example JSON:

{
  "name": "Conference",
  "created_at": "2026-03-01T10:30:00",
  "updated_at": "2026-03-01T14:45:00Z"
}

date - Date Only

from datetime import date
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Event(BaseModel):
    name: str
    event_date: date

@app.post("/events/")
async def create_event(event: Event):
    return event

Example JSON:

{
  "name": "Birthday",
  "event_date": "2026-03-01"
}

time - Time Only

from datetime import time
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Schedule(BaseModel):
    name: str
    start_time: time
    end_time: time

@app.post("/schedules/")
async def create_schedule(schedule: Schedule):
    return schedule

Example JSON:

{
  "name": "Morning Meeting",
  "start_time": "09:00:00",
  "end_time": "10:30:00"
}

timedelta - Duration

from datetime import timedelta
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Task(BaseModel):
    name: str
    duration: timedelta

@app.post("/tasks/")
async def create_task(task: Task):
    return {
        "name": task.name,
        "duration_seconds": task.duration.total_seconds()
    }

Example JSON:

{
  "name": "Review code",
  "duration": 3600
}

timedelta is represented as seconds (float) in JSON.

Numeric Types

Decimal - Precise Numbers

Use Decimal for financial calculations where precision matters:

from decimal import Decimal
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Product(BaseModel):
    name: str
    price: Decimal
    tax: Decimal

@app.post("/products/")
async def create_product(product: Product):
    total = product.price + product.tax
    return {
        "product": product,
        "total": total
    }

Use Decimal instead of float for money to avoid floating-point precision errors.

Good: Using Decimal

price: Decimal = Decimal("10.50")
tax: Decimal = Decimal("0.75")
total = price + tax  # Exactly 11.25

Binary Data Types

bytes - Binary Data

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class FileData(BaseModel):
    filename: str
    content: bytes

@app.post("/files/")
async def create_file(file_data: FileData):
    return {
        "filename": file_data.filename,
        "size": len(file_data.content)
    }

bytes are represented as base64-encoded strings in JSON.

Collection Types

frozenset - Immutable Set

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    tags: frozenset[str]

@app.post("/items/")
async def create_item(item: Item):
    return item

Example JSON:

{
  "name": "Widget",
  "tags": ["electronics", "gadget", "new"]
}

frozenset ensures unique values and is immutable, but is represented as a list in JSON.

URL Types

HttpUrl - URL Validation

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()

class Website(BaseModel):
    name: str
    url: HttpUrl

@app.post("/websites/")
async def create_website(website: Website):
    return website

This validates that the URL:

• Has a valid scheme (http/https)
• Has a valid domain
• Is properly formatted

Email and Other String Types

EmailStr - Email Validation

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()

class User(BaseModel):
    username: str
    email: EmailStr

@app.post("/users/")
async def create_user(user: User):
    return user

EmailStr requires the email-validator package:

pip install pydantic[email]

Path and File Types

FilePath and DirectoryPath

from pathlib import Path
from fastapi import FastAPI
from pydantic import BaseModel, FilePath, DirectoryPath

app = FastAPI()

class Config(BaseModel):
    config_file: FilePath
    data_dir: DirectoryPath

# These validate that paths exist on the filesystem

Color Type

from fastapi import FastAPI
from pydantic import BaseModel, ColorStr

app = FastAPI()

class Theme(BaseModel):
    name: str
    primary_color: ColorStr
    secondary_color: ColorStr

@app.post("/themes/")
async def create_theme(theme: Theme):
    return theme

Accepts formats:

• "red"
• "#ff0000"
• "rgb(255, 0, 0)"
• "rgba(255, 0, 0, 0.5)"

All Supported Types Summary

1. Standard Python

   UUID, datetime, date, time, timedelta, Decimal, bytes, frozenset

2. Pydantic Types

   EmailStr, HttpUrl, FilePath, DirectoryPath, ColorStr, Json

3. Network Types

   IPvAnyAddress, IPvAnyInterface, IPvAnyNetwork

4. Secret Types

   SecretStr, SecretBytes (not logged/dumped by default)

Type Conversion and Validation

All these types provide:

1. Automatic Conversion: String → Type
2. Validation: Ensures format is correct
3. Serialization: Type → JSON
4. Documentation: Correct OpenAPI schema

Request (JSON strings)

{
  "item_id": "123e4567-e89b-12d3-a456-426614174000",
  "start_datetime": "2026-03-01T10:30:00",
  "process_after": 3600
}

Related Topics

• Request Body - Use these types in request models
• Response Model - Use these types in responses
• Path Parameters - Use UUID and other types in URLs