FastAPI Path Parameter Numeric Validation

Use with query parametersQueryThe way to add validation is the same; you can usePathDeclare numeric validation and metadata for path parameters.

Import Path

fromfastapiImportPath, fromtypingImportAnnotated：

Example

from typing import Annotated
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
async def read_items(
# Add metadata and validation for path parameters
item_id: Annotated[int, Path(title="Product ID", description="Product ID to fetch", ge=1)],
):
return {"item_id": item_id}

Path parameters are always required because they must be part of the URL path. Even if you declare a default value for them, they are still treated as required parameters.

Numeric validation

PathandQueryAll support the following numeric validation parameters:

Parameter	Meaning	English source
`gt`	greater than	greater than
`ge`	greater than or equal to	greater than or equal
`lt`	less than	less than
`le`	less than or equal to	less than or equal

Greater than or equal to (ge)

Limititem_idMust be >= 1:

Example

from typing import Annotated
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
async def read_items(
item_id: Annotated[int, Path(ge=1)], # item_id must be >= 1
):
return {"item_id": item_id}

Combining numeric validation

Example

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/items/{item_id}")
async def read_items(
# item_id 必须 > 0 且 <= 1000
item_id: Annotated[int, Path(gt=0, le=1000)],
# Query parameters can also use numeric validation
size: Annotated[float, Query(gt=0, lt=10.5)] = 5.0,
):
return {"item_id": item_id, "size": size}

Floating-point number validation

Numeric validation also applies to floating-point numbers.gt(greater than) andgeThe difference (greater than or equal to) is important in floating-point scenarios:

Example

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/items/{item_id}")
async def read_items(
item_id: Annotated[int, Path(ge=1, le=1000)],
# size must be > 0 and < 10.5
# 0.5 is a valid value, 0.0 and 0 are not (because gt=0 is strictly greater than 0)
size: Annotated[float, Query(gt=0, lt=10.5)],
):
return {"item_id": item_id, "size": size}

Mixing path parameters and query parameters

When you use bothPathandQuerywhen usingAnnotatedThis can avoid issues with parameter order:

Example

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/items/{item_id}")
async def read_items(
# After using Annotated, the order of parameters doesn't matter
item_id: Annotated[int, Path(title="Product ID", ge=1, le=1000)],
q: Annotated[str | None, Query(max_length=50)] = None,
):
results = {"item_id": item_id}
if q:
results.update({"q": q})
return results

Summary

Key points of numeric validation for path parameters:

UsageAnnotated + PathDeclaring validation rules for path parameters
Numeric validation:gt(greater than),ge(greater than or equal to),lt(less than),le(less than or equal to)
PathandQuerySharing the same validation parameters, including string validation (min_lengthetc.) and metadata (title、descriptionetc.)
Path parameters are always required, whether or not a default value is declared.

other extensions