FastAPI リクエストボディのフィールドとネストモデル

Pydantic モデル内では、以下を使用できます。Fieldフィールドに検証ルールとメタデータを宣言したり、モデルをネストして複雑な JSON データ構造を処理したりできます。


Field を使用してフィールド検証を宣言する

パスオペレーション関数で使用するのとQuery、Path検証を宣言するのと同じように、Pydantic モデル内ではFieldフィールド検証を宣言します:

例

from typing import Annotated
from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100, description="商品名")  # 必須、1〜100文字
    description: str | None = Field(default=None, max_length=300, description="商品説明")  # 任意
    price: float = Field(gt=0, description="商品価格")  # 必須、0より大きくなければならない
    tax: float | None = Field(default=None, ge=0, description="税金")  # 任意、>= 0


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

Fieldサポートされている検証パラメータ:

パラメータタイプパラメータ説明
文字列検証min_length最小長
max_length最大長
pattern正規表現マッチング
数値検証gtより大きい
ge以上
ltより小さい
le以下
メタデータtitleフィールドタイトル
descriptionフィールド説明

注意Fieldからpydanticインポートし、〜からではなくfastapiインポートします。これは〜とQuery、Pathなどが〜からfastapiインポートするのとは異なります。


リスト型のフィールド

フィールドをリストとして宣言し、要素の型を指定できます:

例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []  # 文字列リスト、デフォルトは空リスト


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

リクエストボディの例:

{
    "name": "Foo",
    "price": 42.0,
    "tags": ["rock", "metal", "bar"]
}

Set を使用して重複を除去する

タグを重複させたくない場合は、次を使用しますset型:

例

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()  # 重複タグを自動的に除去

リクエストに重複するタグが含まれていても、レスポンスでは自動的に重複が除去されます。


ネストモデル

Pydantic モデルのフィールド型は別の Pydantic モデルにすることができ、任意の深さのネストをサポートします:

例

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


# サブモデル:画像
class Image(BaseModel):
    url: HttpUrl      # 有効な URL かどうかを自動検証
    name: str


# メインモデル:商品、画像サブモデルを含む
class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    image: Image | None = None  # 任意の画像情報


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

対応するリクエストボディの構造:

{
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2,
    "tags": ["rock", "metal", "bar"],
    "image": {
        "url": "http://example.com/baz.jpg",
        "name": "The Foo live"
    }
}

リスト内のサブモデル

サブモデルをリストに入れることができます:

例

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


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


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None  # 画像リスト


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

対応するリクエストボディ:

{
    "name": "Foo",
    "price": 42.0,
    "images": [
        {"url": "http://example.com/baz.jpg", "name": "The Foo live"},
        {"url": "http://example.com/dave.jpg", "name": "The Baz"}
    ]
}

深いネストモデル

任意の深さのネスト構造を定義できます:

例

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


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


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None


class Offer(BaseModel):
    name: str
    description: str | None = None
    price: float
    items: list[Item]  # Offer は複数の Item を含み、Item はさらに複数の Image を含む


@app.post("/offers/")
async def create_offer(offer: Offer):
    return offer

純粋なリストのリクエストボディ

リクエストボディの最外層が JSON 配列の場合、関数パラメータで直接リスト型を宣言できます:

例

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


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


# リクエストボディが直接 Image のリスト
@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
    return images

任意の dict からなるリクエストボディ

キー名が不定な辞書データを受け取る必要がある場合は、次を宣言できますdict型のリクエストボディ:

例

from fastapi import FastAPI

app = FastAPI()


# キーが int、値が float の辞書を受け取る
@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
    return weights

リクエストボディの例:

{
    "1": 0.5,
    "2": 1.5,
    "3": 2.0
}

JSON は文字列型のキーのみサポートしますが、Pydantic は文字列キーを自動的に宣言された型に変換します(この例のようにint)。


まとめ

  • Pydantic のFieldモデルフィールドに検証とメタデータを追加する
  • list[str]、set[str]などのコレクション型でリスト/セットフィールドを宣言できる
  • モデルはネストして使用でき、任意の深さの JSON 構造をサポートします
  • HttpUrlなどの特殊型はフォーマットを自動検証します
  • 純粋なリストや任意の辞書もリクエストボディの型として使用できます
その他の拡張