Deep Dive into `Annotated`

Understanding `Annotated`

Throughout this course, you’ve seen two different ways of writing validations and dependencies. For example, in Pydantic models, we previously wrote:

from pydantic import BaseModel, Field

class EmployeeCreateRequest(BaseModel):
    name: str = Field(min_length=2)

Later, we switched to the recommended syntax:

from typing import Annotated
from pydantic import BaseModel, Field

class EmployeeCreateRequest(BaseModel):
    name: Annotated[str, Field(min_length=2)]

Similarly, for Dependency Injection, we can write:

from fastapi import Depends

def get_employees(
    repository: EmployeeRepository = Depends(get_employee_repository),
):
    ...

or the recommended syntax:

from typing import Annotated
from fastapi import Depends

def get_employees(
    repository: Annotated[
        EmployeeRepository,
        Depends(get_employee_repository),
    ],
):
    ...

Both styles are equivalent. However, Annotated is the recommended approach in modern FastAPI and Pydantic.

Why Use `Annotated`?

The purpose of Annotated is to separate the actual data type from its metadata. General syntax:

Annotated[Type, Metadata]

Type describes the expected data type.
Metadata provides additional instructions such as validation rules or dependency information.

Common Examples

Purpose	Old Style	Recommended Style
Request Body	`name: str = Field(...)`	`name: Annotated[str, Field(...)]`
Query Parameter	`limit: int = Query(...)`	`limit: Annotated[int, Query(...)]`
Path Parameter	`id: int = Path(...)`	`id: Annotated[int, Path(...)]`
Header	`token: str = Header(...)`	`token: Annotated[str, Header(...)]`
Dependency	`repo: EmployeeRepository = Depends(...)`	`repo: Annotated[EmployeeRepository, Depends(...)]`

Notice that only the metadata changes.

How to Read `Annotated`

Consider this example.

name: Annotated[str, Field(min_length=2)]

It can be read as:

The value is a string.
It must satisfy the validation rules defined by Field().

Likewise,

repository: Annotated[
    EmployeeRepository,
    Depends(get_employee_repository),
]

can be read as:

The value is an EmployeeRepository.
FastAPI should obtain it by calling get_employee_repository().

`Field()` vs `Depends()`

Although both are used with Annotated, they serve different purposes.

`Field()`

Used inside Pydantic models to validate data.

class EmployeeCreateRequest(BaseModel):
    name: Annotated[str, Field(min_length=2)]

Here:

Type: str
Metadata: Field(min_length=2)

`Depends()`

Used by FastAPI for Dependency Injection.

repository: Annotated[
    EmployeeRepository,
    Depends(get_employee_repository),
]

Here:

Type: EmployeeRepository
Metadata: Depends(get_employee_repository)

Unlike Field(), Depends() does not perform validation. Instead, it tells FastAPI how to create the required object.

Creating Reusable Dependency Aliases

Suppose many endpoints need an EmployeeRepository. Instead of repeatedly writing:

repository: Annotated[
    EmployeeRepository,
    Depends(get_employee_repository),
]

we can create a reusable alias.

RepositoryDep = Annotated[
    EmployeeRepository,
    Depends(get_employee_repository),
]

Now the endpoint becomes much cleaner.

@router.get("/employees")
def get_employees(
    repository: RepositoryDep,
):
    ...

FastAPI expands this alias internally to:

repository: Annotated[
    EmployeeRepository,
    Depends(get_employee_repository),
]

Mental Model

Think of Annotated as attaching extra information to a type.

Annotated[
    Type,
    Metadata
]

Examples:

Annotated[str, Field(min_length=2)]

Type
 └── str

Metadata
 └── Validate minimum length = 2

Annotated[
    EmployeeRepository,
    Depends(get_employee_repository),
]

Type
 └── EmployeeRepository

Metadata
 └── Create using get_employee_repository()

Key Takeaway

Annotated always combines two things:

The actual type (str, int, EmployeeRepository, etc.).
Metadata that describes how the value should be validated or obtained.

The metadata depends on the context:

Field() → Request body validation.
Query() → Query parameter validation.
Path() → Path parameter validation.
Header() → Header extraction.
Depends() → Dependency Injection.

Once you understand this pattern, you’ll notice that FastAPI and Pydantic use Annotated consistently throughout the framework.

`Annotated` and Default Values

A common question is:

If Annotated moves the metadata inside the type annotation, where do default values go?

The answer is simple:

Validation metadata goes inside Annotated.
Default values are still assigned using =.

Example 1: `Field()`

from typing import Annotated
from pydantic import BaseModel, Field

class Employee(BaseModel):
    name: Annotated[str, Field(min_length=2)]
    department: Annotated[str, Field(max_length=30)] = "Engineering"

Here:

str is the type.
Field(...) defines the validation rules.
"Engineering" is the default value.

Example 2: `Query()`

from typing import Annotated
from fastapi import Query

@app.get("/employees")
def get_employees(
    limit: Annotated[int, Query(ge=1, le=100)] = 10,
):
    ...

Here:

int is the type.
Query(...) defines the validation rules.
10 is the default value.

Example 3: `Header()`

from typing import Annotated
from fastapi import Header

@app.get("/profile")
def profile(
    language: Annotated[str, Header()] = "en",
):
    ...

Here:

str is the type.
Header() tells FastAPI to read the value from the request header.
"en" is the default value if the header is not provided.

Example 4: `Depends()`

Although less common, the same syntax applies.

from typing import Annotated
from fastapi import Depends

def get_employees(
    repository: Annotated[
        EmployeeRepository,
        Depends(get_employee_repository),
    ],
):
    ...

Notice that there is no default value here because FastAPI always injects the dependency.

General Rule

parameter: Annotated[Type, Metadata] = DefaultValue

Type → What kind of value is expected.
Metadata → Validation or dependency information.
DefaultValue → Used only when the value is optional.

Examples

Parameter	Type	Metadata	Default
`name: Annotated[str, Field(min_length=2)]`	`str`	`Field()`	None (required)
`limit: Annotated[int, Query(ge=1)] = 10`	`int`	`Query()`	`10`
`department: Annotated[str, Header()] = "Engineering"`	`str`	`Header()`	`"Engineering"`
`repository: Annotated[EmployeeRepository, Depends(get_employee_repository)]`	`EmployeeRepository`	`Depends()`	None (injected)

Key Takeaway

Think of the syntax as three separate parts:

parameter: Annotated[Type, Metadata] = DefaultValue

Type defines what the value is.
Metadata defines how FastAPI or Pydantic should process it.
DefaultValue defines what to use when the value is optional.

Backend-Foundations

Backend-Advanced

Frontend with Streamlit

Deployment

Understanding `Annotated`

Why Use `Annotated`?

Common Examples

How to Read `Annotated`

`Field()` vs `Depends()`

`Field()`

`Depends()`

Creating Reusable Dependency Aliases

Mental Model

Key Takeaway

`Annotated` and Default Values

Example 1: `Field()`

Example 2: `Query()`

Example 3: `Header()`

Example 4: `Depends()`

General Rule

Examples

Key Takeaway

​Understanding Annotated

​Why Use Annotated?

​Common Examples

​How to Read Annotated

​Field() vs Depends()

​Field()

​Depends()

​Creating Reusable Dependency Aliases

​Mental Model

​Key Takeaway

​Annotated and Default Values

​Example 1: Field()

​Example 2: Query()

​Example 3: Header()

​Example 4: Depends()

​General Rule

​Examples

​Key Takeaway

Understanding `Annotated`

Why Use `Annotated`?

Common Examples

How to Read `Annotated`

`Field()` vs `Depends()`

`Field()`

`Depends()`

Creating Reusable Dependency Aliases

Mental Model

Key Takeaway

`Annotated` and Default Values

Example 1: `Field()`

Example 2: `Query()`

Example 3: `Header()`

Example 4: `Depends()`

General Rule

Examples

Key Takeaway