TypedDict in Python

1. What is TypedDict?

TypedDict defines the expected structure of a dictionary using type hints.

from typing import TypedDict

class Student(TypedDict):
    name: str
    age: int
    marks: float

It is still a normal Python dictionary:

student: Student = {
    "name": "Ravi",
    "age": 21,
    "marks": 85.5
}

TypedDict is mainly for static type checking. It does not perform runtime validation.

Practice

Define a Movie TypedDict with fields title (str), year (int), and rating (float). Create a valid instance of it.

Solution

from typing import TypedDict

class Movie(TypedDict):
    title: str
    year: int
    rating: float

movie: Movie = {
    "title": "Inception",
    "year": 2010,
    "rating": 8.8
}

2. Required Keys

By default, all keys are required.

class Student(TypedDict):
    name: str
    age: int

student = {
    "name": "Ravi",
    "age": 21
}

Practice

Define a Product TypedDict with fields name (str) and price (float). Create an instance that misses a required key and note what a static type checker would report.

Solution

from typing import TypedDict

class Product(TypedDict):
    name: str
    price: float

# This is invalid because 'price' is missing:
# type checkers like mypy will raise an error.
invalid_product: Product = {
    "name": "Laptop"
}

3. Union Types with `|`

Modern Python supports | for union types.

class Student(TypedDict):
    name: str
    age: int | None

age is required, but its value can be int or None.

{"name": "Ravi", "age": 21}     # valid
{"name": "Ravi", "age": None}   # valid
{"name": "Ravi"}                # not valid

Important

int | None
    → controls the allowed VALUE

NotRequired[int]
    → controls whether the KEY can be omitted

Practice

Define a User TypedDict where email is str | None. Create an instance with email as None and another with a string email.

Solution

from typing import TypedDict

class User(TypedDict):
    username: str
    email: str | None

# Both are valid, but email must be present
user1: User = {
    "username": "alice",
    "email": None
}

user2: User = {
    "username": "bob",
    "email": "[email protected]"
}

4. Optional Keys with `NotRequired`

Use NotRequired when the key itself can be omitted.

from typing import TypedDict, NotRequired

class Student(TypedDict):
    name: str
    age: NotRequired[int]

Both are valid:

{"name": "Ravi", "age": 21}
{"name": "Ravi"}

To make the key optional and allow None:

class Student(TypedDict):
    age: NotRequired[int | None]

Now all are valid:

{"age": 21}
{"age": None}
{}

Practice

Define a Book TypedDict where title (str) and author (str) are required, but pages (int) and genre (str | None) are NotRequired. Create an instance without pages and genre, and another with both.

Solution

from typing import TypedDict, NotRequired

class Book(TypedDict):
    title: str
    author: str
    pages: NotRequired[int]
    genre: NotRequired[str | None]

# Valid: Pages and genre omitted
book1: Book = {
    "title": "1984",
    "author": "George Orwell"
}

# Valid: Pages and genre provided
book2: Book = {
    "title": "To Kill a Mockingbird",
    "author": "Harper Lee",
    "pages": 281,
    "genre": None
}

5. TypedDict vs Pydantic

TypedDict	Pydantic
Describes dictionary structure	Defines a data model
Mainly for type checking	Runtime validation
Object remains a `dict`	Object is a model
Common for internal state	Common for API/data validation

Simple rule:

TypedDict → What should the dictionary look like?

Pydantic → Is the data valid?

6. TypedDict in LangGraph

TypedDict is commonly used to define LangGraph state.

from typing import TypedDict, NotRequired

class AgentState(TypedDict):
    question: str
    context: NotRequired[str]
    answer: NotRequired[str]

Initially:

state = {
    "question": "What is RAG?"
}

After retrieval:

state = {
    "question": "What is RAG?",
    "context": "RAG retrieves relevant information..."
}

After generation:

state = {
    "question": "What is RAG?",
    "context": "RAG retrieves relevant information...",
    "answer": "RAG combines retrieval with generation."
}

This makes TypedDict particularly useful for state that evolves as it moves between LangGraph nodes.

Practice

Define an LLMState TypedDict for a translation agent with required key original_text (str), and optional keys source_language (NotRequired[str]), target_language (NotRequired[str]), and translated_text (NotRequired[str]). Create instances representing the state at different stages.

Solution

from typing import TypedDict, NotRequired

class LLMState(TypedDict):
    original_text: str
    source_language: NotRequired[str]
    target_language: NotRequired[str]
    translated_text: NotRequired[str]

# Stage 1: Initial state
state1: LLMState = {
    "original_text": "Bonjour tout le monde"
}

# Stage 2: Languages detected/defined
state2: LLMState = {
    "original_text": "Bonjour tout le monde",
    "source_language": "French",
    "target_language": "English"
}

# Stage 3: Translated text populated
state3: LLMState = {
    "original_text": "Bonjour tout le monde",
    "source_language": "French",
    "target_language": "English",
    "translated_text": "Hello everyone"
}

7. Quick Reference

TypedDict
    → defines dictionary structure

int | None
    → value can be int or None
    → key is still required

NotRequired[int]
    → key can be omitted
    → if present, value must be int

NotRequired[int | None]
    → key can be omitted
    → if present, value can be int or None

8. Key Takeaway

TypedDict = structure of a dictionary

Pydantic = validation of structured data

For LangGraph:
TypedDict → commonly used to define graph state

Practice & Exercises

To reinforce what you’ve learned in this section (defining TypedDicts, required vs optional keys, union types, and graph states), practice with these interactive notebooks:

Follow-Along Practice

Practice defining dictionary structures, working with Required and NotRequired keys, using modern Union types, and modeling LangGraph states.💻 VS Code | 🚀 Colab | 📥 Download

Practice Exercises

Test your knowledge by building schemas for Movies, Products, Users, Books, and translation LLMStates with proper type hinting.💻 VS Code | 🚀 Colab | 📥 Download

Python Foundations

Python Intermediate

Python Advanced

1. What is TypedDict?

Practice

2. Required Keys

Practice

3. Union Types with `|`

Important

Practice

4. Optional Keys with `NotRequired`

Practice

5. TypedDict vs Pydantic

6. TypedDict in LangGraph

Practice

7. Quick Reference

8. Key Takeaway

Practice & Exercises

Follow-Along Practice

Practice Exercises

​1. What is TypedDict?

​Practice

​2. Required Keys

​Practice

​3. Union Types with |

​Important

​Practice

​4. Optional Keys with NotRequired

​Practice

​5. TypedDict vs Pydantic

​6. TypedDict in LangGraph

​Practice

​7. Quick Reference

​8. Key Takeaway

​Practice & Exercises

Follow-Along Practice

Practice Exercises

1. What is TypedDict?

Practice

2. Required Keys

Practice

3. Union Types with `|`

Important

Practice

4. Optional Keys with `NotRequired`

Practice

5. TypedDict vs Pydantic

6. TypedDict in LangGraph

Practice

7. Quick Reference

8. Key Takeaway

Practice & Exercises