Skip to content

Data Schemas (DTOs)

ZodiacCore provides a set of base Pydantic models and types to standardize Data Transfer Objects (DTOs). These mirror our database models to ensure end-to-end consistency.

1. Core Models

CoreModel

The CoreModel is the recommended base class for all your Pydantic models. It comes pre-configured with: - from_attributes=True: Allows easy conversion from ORM objects (like SQLModel or SQLAlchemy) using Model.model_validate(orm_obj).

from zodiac_core import CoreModel

class UserSchema(CoreModel):
    username: str
    email: str

2. Standard Schema Mixins

We provide several mixins to match the IntIDModel and UUIDModel found in the database layer.

Schema Primary Key Timestamps
IntIDSchema id: int created_at, updated_at
UUIDSchema id: UUID created_at, updated_at

Example Usage

from zodiac_core import IntIDSchema

class ProductRead(IntIDSchema):
    name: str
    price: float

3. UTC Datetime Utility

Handling timezones correctly is notoriously difficult. ZodiacCore includes a UtcDatetime type that automatically converts incoming datetime objects to UTC and ensures they are timezone-aware.

from zodiac_core import UtcDatetime
from pydantic import BaseModel

class Event(BaseModel):
    # Any incoming datetime will be converted to aware-UTC
    happened_at: UtcDatetime

4. API Reference

Base Schemas

UtcDatetime = Annotated[datetime, BeforeValidator(ensure_utc)] module-attribute

CoreModel

Bases: BaseModel

Base Pydantic model for all Zodiac schemas (DTOs).

Features: - Standard snake_case fields - From attributes enabled (ORM mode)

Source code in zodiac_core/schemas.py 
25
26
27
28
29
30
31
32
33
34
35
36
class CoreModel(BaseModel):
    """
    Base Pydantic model for all Zodiac schemas (DTOs).

    Features:
    - Standard snake_case fields
    - From attributes enabled (ORM mode)
    """

    model_config = ConfigDict(
        from_attributes=True,
    )

IntIDSchema

Bases: CoreModel, IntIDSchemaMixin, DateTimeSchemaMixin

Base schema for models with an Integer ID and Timestamps. Includes: Core Config + ID + CreatedAt + UpdatedAt.

Source code in zodiac_core/schemas.py 
70
71
72
73
74
class IntIDSchema(CoreModel, IntIDSchemaMixin, DateTimeSchemaMixin):
    """
    Base schema for models with an Integer ID and Timestamps.
    Includes: Core Config + ID + CreatedAt + UpdatedAt.
    """

UUIDSchema

Bases: CoreModel, UUIDSchemaMixin, DateTimeSchemaMixin

Base schema for models with a UUID and Timestamps. Includes: Core Config + ID + CreatedAt + UpdatedAt.

Source code in zodiac_core/schemas.py 
77
78
79
80
81
class UUIDSchema(CoreModel, UUIDSchemaMixin, DateTimeSchemaMixin):
    """
    Base schema for models with a UUID and Timestamps.
    Includes: Core Config + ID + CreatedAt + UpdatedAt.
    """

IntIDSchemaMixin

Bases: BaseModel

Mixin for models that include an integer ID.

Source code in zodiac_core/schemas.py 
52
53
54
55
56
57
58
class IntIDSchemaMixin(BaseModel):
    """Mixin for models that include an integer ID."""

    id: int = Field(
        ...,
        description="The unique integer identifier.",
    )

UUIDSchemaMixin

Bases: BaseModel

Mixin for models that include a UUID.

Source code in zodiac_core/schemas.py 
61
62
63
64
65
66
67
class UUIDSchemaMixin(BaseModel):
    """Mixin for models that include a UUID."""

    id: UUID = Field(
        ...,
        description="The unique UUID identifier.",
    )

DateTimeSchemaMixin

Bases: BaseModel

Mixin for models that include standard timestamps.

Source code in zodiac_core/schemas.py 
39
40
41
42
43
44
45
46
47
48
49
class DateTimeSchemaMixin(BaseModel):
    """Mixin for models that include standard timestamps."""

    created_at: UtcDatetime = Field(
        ...,
        description="The UTC timestamp when the record was created.",
    )
    updated_at: UtcDatetime = Field(
        ...,
        description="The UTC timestamp when the record was last updated.",
    )