Pydantic Objects vs Dictionaries

Understanding the core issue when working with Pydantic objects and dictionaries in FastAPI applications.

The Core Issue

When working with Pydantic models across different layers of your application, you'll encounter scenarios where you need to pass data between different Pydantic models. The key issue is that Pydantic is strict about type validation - even if two models have identical fields, they're considered different types.

Common Scenarios

Scenario 1: Direct Assignment (✅ Works)

This works - creating a Pydantic model from a dictionary:

Scenario 2: Nested Pydantic Objects (❌ Fails)

This fails - trying to assign a Pydantic object where dict is expected:

Scenario 3: Converting Objects to Dicts (✅ Works)

This works - converting Pydantic objects to dictionaries first:

Why This Happens

Pydantic Type Validation

When Pydantic validates a field like installment_options: List[CreditCardInstallmentOption], it expects:

1. Dictionary → Converts to CreditCardInstallmentOption automatically
2. Already a CreditCardInstallmentOption → Accepts directly
3. Different Pydantic model (like InstallmentOption) → REJECTS even if fields match!

The Error Message Decoded

1Input should be a valid dictionary or instance of CreditCardInstallmentOption
2[type=model_type, input_value=InstallmentOption(months=10, total='R$ 960,60'),
3input_type=InstallmentOption]

Our Specific Case

What Was Happening

AI Response (from core/ai/models/responses.py):

Invoice Schema (from domains/invoices/schemas.py):

The Fix

Convert Pydantic objects to dictionaries:

Common Pydantic Patterns

1. Dictionary → Pydantic (✅ Always Works)

2. Pydantic → Dictionary

3. Same-Class Assignment (✅ Works)

4. Different-Class Assignment (❌ Fails)

Best Practices

1. Use .model_dump() for Cross-Domain Data

When passing data between different domains:

2. Keep Schema Consistency

Better: Use the same schema across domains:

3. Validate Early

Validate at boundaries:

Why We Had This Issue

Our Solution Strategy

This pattern is super common in FastAPI applications where you have multiple layers (API, AI, Domain) with their own Pydantic models! 🚀