Lesson 0012 · Core Designer · Module 3

Value Objects and Aggregates

Two containers protect the domain: value objects make data trustworthy, aggregates make change trustworthy. This lesson builds both on one example.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: "use value objects and aggregates to protect integrity" — the mechanism behind lesson 0011's "make invalid states impossible."

Knowledge: the two protectors

Value object: an immutable thing whose identity is its value. Two instances with equal fields are interchangeable. Money is the classic:

@dataclass(frozen=True)
class Money:
    amount: Decimal
    currency: str

    def __post_init__(self) -> None:
        if self.amount < 0:
            raise ValueError("amount cannot be negative")
        if not self.currency.isalpha() or len(self.currency) != 3:
            raise ValueError("currency must be an ISO code")

    def __add__(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise CurrencyMismatch()
        return Money(self.amount + other.amount, self.currency)

Before: amount and currency drifted through the codebase as two unconnected numbers, each function re-validating or forgetting. After: you cannot construct a broken Money, and adding dollars to euros refuses itself. The value object killed a whole family of bugs — and it's shareable and testable because it's immutable.

Aggregate: a cluster of objects that must change together, with one root guarding the cluster's invariants. The order and its lines:

class Order:
    def __init__(self, order_id: str, customer: CustomerId, currency: str) -> None:
        self.order_id = order_id
        self.customer = customer
        self._currency = currency
        self._lines: list[OrderLine] = []
        self._status = Status.PENDING

    def add_line(self, product: ProductId, qty: int, price: Money) -> None:
        if self._status != Status.PENDING:          # invariant: only drafts change
            raise OrderLockedError()
        if price.currency != self._currency:        # invariant: one currency per order
            raise CurrencyMismatch()
        self._lines.append(OrderLine(product, qty, price))

    def total(self) -> Money:
        total = Money(Decimal("0"), self._currency)
        for line in self._lines:
            total = total + line.total()            # Money refuses a mismatch anyway
        return total

Order is the root: every change to the cluster goes through it, and it enforces the invariants from lesson 0011. Lines are edited only via the root — no one reaches into _lines to bend a rule.

Watch the two layers cooperate. Money refuses to add euros to dollars — a rule about one value. Order refuses a line in the wrong currency at the moment it is added — a rule about the cluster, caught at the door rather than three steps later inside total(). The value object makes each datum trustworthy; the aggregate makes each transition trustworthy. Neither can do the other's job.

How a senior designer works the case

The returns-resolution initiative: customers open returns against existing orders, and one rule matters to finance — a customer must never be refunded more than they paid. A modeller's instinct is to put the orders and the returns inside one Customer aggregate, where that rule is a single method away from being an enforced invariant.

What they look at first. Not the class diagram — the write pattern. How many writes per second hit one customer, how many orders does a heavy customer have, and which of these facts have to agree at commit time versus within a few seconds? For a retailer's returns flow, a given customer writes rarely, but the eligibility check reads the order, and the customer with 400 orders is exactly the one who returns things.

The question they ask. "What breaks, in business terms, if these two facts are stale relative to each other for two seconds?" If the honest answer is "a return is accepted against an order that was cancelled a second ago, and we reject it on review", that is a recoverable business event, not a corruption — so the two facts do not need one transaction.

The alternative they reject. The Customer-as-root design. It makes the refund-total rule enforceable in one place, and it costs: every return on any order locks the customer, a heavy customer loads hundreds of orders to add one line, and two teams now write to the same aggregate. Worse, on inspection the rule was never an invariant — the fraud guardrail it was protecting is a policy with thresholds a risk team tunes monthly. Enforcing policy as an invariant means a business tuning decision becomes a domain deployment.

@dataclass(frozen=True)
class OrderId:
    value: str

class Return:                                     # its own aggregate root
    def __init__(self, return_id: str, order_id: OrderId, currency: str) -> None:
        self.return_id = return_id
        self.order_id = order_id                  # reference by identity, not object
        self._currency = currency
        self._lines: list[ReturnLine] = []
        self._state = ReturnState.REQUESTED

    def add_line(self, sku: str, qty: int, refund: Money) -> None:
        if self._state is not ReturnState.REQUESTED:
            raise ReturnLockedError(self.return_id)
        if refund.currency != self._currency:
            raise CurrencyMismatch()
        self._lines.append(ReturnLine(sku, qty, refund))

    def reject(self, reason: str) -> None:        # the compensating transition
        self._state = ReturnState.REJECTED

The consequence over time. Two aggregates mean two teams can hold two locks, ship on two schedules, and reason about two state machines. The price is explicit and paid once: eligibility is checked against a snapshot at creation, the order system stays authoritative, and the race — a return raised against an order that changed underneath it — surfaces as a reject() transition you can test, count and show a customer. Compare that to the contention failure of the big aggregate, which shows up as timeouts at peak, six months later, in code nobody wants to reshape by then.

When this is the wrong move

• Bulk and analytics paths. Reconciling ten million rows through Money constructors buys validation you already have from the source system and costs an object per row. Validate at the ingest boundary; work in primitives inside the loop.
• Screens that read across boundaries. A dashboard needing customer, orders, returns and shipping is not evidence that they belong in one aggregate. It is evidence you need a read model. Growing the aggregate to serve a query is the single most common way aggregates become contention points.
• CRUD with no rules. A settings form with twelve independent fields and no invariants gains nothing from a root that guards nothing. The ceremony is real; the protection is imaginary.
• Facts you do not own. If another system is authoritative for a value, your "aggregate" is holding a replica. Model it as a cached snapshot with an age, not as state you can enforce rules on (lesson 0020).

Skill: which container, and when?

Practice on your own code

Find a pair of values that travel together as primitives (a price and currency, a start and end, a unit and rate) — promote them to a value object. Then find a cluster that must change together and give it a root that refuses invalid edits.

In the lab: the phase-1 checkpoint ships a returns service that passes an amount and a currency code as two separate arguments through four layers, and a return whose line list is appended to from outside. You promote the pair into one value object and decide, with the contention argument above, where the aggregate boundary actually belongs.

# before: temperature and unit passed separately, revalidated everywhere
def display(temp: float, unit: str) -> str: ...

# after: Temperature can't be malformed, and unit conversions live inside it
@dataclass(frozen=True)
class Temperature:
    value: float
    unit: Unit

    def in_celsius(self) -> float: ...

Read and watch deeper

• Domain-Driven Design, Evans — ch. 5 "A Model Expressed in Software" (entities vs value objects) and ch. 6 (aggregates and invariants).
• Implementing Domain-Driven Design, Vernon — ch. 6 "Value Objects" and ch. 10 "Aggregates": the practical rules of thumb.
• Architecture Patterns with Python, Percival & Gregory — ch. 1–2: value objects and aggregates in working Python.
• Vernon, "Effective Aggregate Design" (three essays, dddcommunity.org) — the primary source for the rules used above: model true invariants inside a boundary, keep aggregates small, reference other aggregates by identity, and update one aggregate per transaction with eventual consistency between them.
• Watch: ArjanCodes YouTube — search "value objects" or "aggregate".
• Reference: Glossary — value object, entity, aggregate.

Bring a borderline case — entity or value object? — to your agent-teacher and argue both sides.