What Is a DDD Aggregate? A Complete Guide to Aggregate Roots, Invariants, and Transaction Boundaries

A thorough, source-grounded guide to the DDD Aggregate: what it is, the role of the aggregate root, why invariants (not transactions) define its boundary, Vernon's four rules of aggregate design, ID references, eventual consistency, and a full TypeScript/zod implementation.

7 min read

Anyone learning DDD (Domain-Driven Design) eventually runs into the concept of the Aggregate. Yet many developers keep designing with lingering questions: “What exactly is an aggregate root?” “How do I draw the boundary?” “How is this different from a transaction?”

This article works through the definition of an aggregate, the aggregate root, invariants, transaction boundaries, eventual consistency, and a TypeScript implementation pattern, grounded in primary sources: Eric Evans’s original book Domain-Driven Design, Vaughn Vernon’s “Effective Aggregate Design” paper series, Martin Fowler’s bliki, and Implementing Domain-Driven Design.

What Is an Aggregate?

Eric Evans, the originator of DDD, defined an aggregate as a cluster of associated objects that are treated as a unit for the purpose of data changes ( Evans, Domain-Driven Design, 2003 ; Martin Fowler, DDD_Aggregate ).

Why is such a “unit” necessary in the first place? The reason is simple: if every domain object can be modified independently, no one can guarantee business rules that span multiple objects.

Consider an order in an e-commerce system. An Order has several OrderLine items hanging off it. If you exposed an API that let OrderLine be created or deleted independently, you would have to re-check the rule “the order total must match the sum of its lines” somewhere else in the application every single time. Miss one check, and an inconsistent order ends up persisted to the database.

An aggregate encloses rules that must always hold inside a single unit, and prevents anything outside that unit from reaching in and mutating its internals directly — so the domain model itself enforces the rule. It is not merely a convenient grouping of related objects; it is more accurate to think of it as a unit of responsibility for guaranteeing consistency.

The Aggregate Root and Its Boundary

Among the objects that make up an aggregate, only one — the Aggregate Root — may be referenced from outside. Any internal object (an internal entity or value object) must never be read or modified directly from outside; every access must go through the aggregate root ( Martin Fowler, DDD_Aggregate ).

In our example, Order is the aggregate root and OrderLine is an internal object. The application layer and repository can only add or change OrderLine items through Order; there is no API for reading or updating an OrderLine on its own.

This constraint carries two implications.

  1. Reference discipline: objects outside the aggregate may hold a reference only to the aggregate root. Because references to internal objects are never handed out, the aggregate root always knows exactly who changed its internal state and when.
  2. Unit of persistence: repositories load and save aggregates as a whole. Loading and saving the entire aggregate as a single unit is one of the fundamental design principles of aggregates ( Martin Fowler, DDD_Aggregate ). There is no repository method that persists a single OrderLine in isolation.

The structure looks like this:

Structure of the Order aggregate Figure 1: All external operations on the Order aggregate go through the aggregate root, Order. Direct access to the internal OrderLine objects is disallowed. A different aggregate, Customer, is referenced by ID (customerId), never by object reference.

References to other aggregates — Customer in this example — should stay at the level of an ID reference rather than an object reference. This, too, is a consequence of treating the aggregate root as the sole gateway, and it connects directly to the discussion of invariants in the next section.

Invariants Are What Define the Aggregate Boundary

This is the point this article wants to emphasize most. The aggregate boundary is not decided by transactional convenience. It is decided by the business rules that must always hold — invariants.

An invariant is a property that must hold the instant a state change completes, no matter how the object’s state evolves. Unlike a simple input validation (a format check on a single field, say, “the string must not be empty”), an invariant is very often a rule about the relationship among multiple objects. “The order total must equal the sum of its line items” and “a placed order must have at least one line item” are both examples.

Vaughn Vernon captures this idea with the phrase true invariants in his “Effective Aggregate Design” papers. The criterion for deciding whether a rule belongs inside the same aggregate is whether that rule must hold atomically the instant a transaction completes ( Vaughn Vernon, Effective Aggregate Design Part I: Modeling a Single Aggregate ). Only rules that require this kind of immediate consistency belong inside the aggregate; everything else lives outside it and is reconciled through eventual consistency (discussed later). This is Vernon’s consistent thesis throughout the series.

In other words, the first question a designer should ask is not “I want to save this cluster of objects together in one transaction, so let’s make it one aggregate,” but rather “is this rule a true invariant that must always hold?” The transaction boundary is a consequence of the aggregate boundary determined this way — never the other way around.

The decision flow looks like this:

Decision flow for invariant-driven boundaries Figure 3: If a candidate rule must always and immediately hold — a true invariant — it belongs in the same aggregate. Otherwise, model it as a separate aggregate, connected by an ID reference and eventual consistency.

Take a concrete example. “The order total must equal the sum of its line items” must hold the instant an order is placed, so it is a true invariant, and Order and OrderLine belong to the same aggregate. On the other hand, “when a customer’s name or address changes, must it be reflected in past orders immediately?” is, in most domains, not a true invariant. A snapshot of the customer’s information at order time is usually enough, so Customer can be a separate aggregate from Order.

Vernon’s Four Rules of Aggregate Design

In “Effective Aggregate Design,” Vernon offers four rules of thumb for keeping aggregates small and loosely coupled ( InfoQ, Designing and Storing Aggregates in Domain-Driven Design ; dddcommunity.org, Vernon 2011 ).

  1. Protect true invariants inside consistency boundaries: only one aggregate should be modified within a single transaction.
  2. Design small aggregates: the smallest possible aggregate is a single root entity. Start from the premise that every entity is its own aggregate, and add only what is strictly necessary to protect a true invariant.
  3. Reference other aggregates by identity only: never hold a direct object reference from one aggregate to another; always go through an identifier (ID).
  4. Use eventual consistency outside the boundary: consistency with anything outside the aggregate boundary is achieved not through a synchronous transaction but through mechanisms like domain events — eventual consistency.

These same four rules are introduced consistently in Implementing Domain-Driven Design, Chapter 10, “Aggregates” — as designing small, favoring composition from value objects, modeling true invariants within the consistency boundary, and referencing other aggregates by identity ( codezine.jp, Chapter 10 of Implementing DDD: Aggregates ).

Rule 2, “design small,” is not merely a performance tip. As an aggregate grows, concurrent operations against it collide more often (optimistic-lock conflicts), more data must be loaded, and tests become harder to write. Narrowing an aggregate down to exactly what a true invariant requires pays off both in scalability and in the simplicity of the model.

A TypeScript Implementation Pattern

Let’s put these principles into practice with a TypeScript example built around an e-commerce order (Order/OrderLine). The earlier version of this article expressed a balance-non-negative invariant using only zod’s refine; here we build on that same idea and extend it into a more realistic example that ties together the aggregate root class, its factory methods, invariant checks, and a repository.

First, the value objects and the internal entity OrderLine. Since OrderLine is an internal object of the aggregate, it should never be instantiated directly from outside — only through Order.

import { z } from "zod";

// ---- Value objects ----
const MoneySchema = z.number().int().nonnegative(); // stored in the smallest currency unit (e.g. cents/yen)
type Money = z.infer<typeof MoneySchema>;

const ProductIdSchema = z.string().uuid();
type ProductId = z.infer<typeof ProductIdSchema>;

const CustomerIdSchema = z.string().uuid();
type CustomerId = z.infer<typeof CustomerIdSchema>;

// OrderLine is an internal entity of the aggregate. Never construct it directly from outside.
const OrderLineSchema = z.object({
  productId: ProductIdSchema,
  unitPrice: MoneySchema,
  quantity: z.number().int().positive(),
});
type OrderLineProps = z.infer<typeof OrderLineSchema>;

class OrderLine {
  private constructor(private readonly props: OrderLineProps) {}

  static create(props: OrderLineProps): OrderLine {
    OrderLineSchema.parse(props); // validation for a single line item
    return new OrderLine(props);
  }

  get productId() {
    return this.props.productId;
  }
  get quantity() {
    return this.props.quantity;
  }
  get subtotal(): Money {
    return this.props.unitPrice * this.props.quantity;
  }
  get snapshot(): Readonly<OrderLineProps> {
    return this.props;
  }

  withQuantity(quantity: number): OrderLine {
    return OrderLine.create({ ...this.props, quantity });
  }
}

Next, the aggregate root Order. Three points matter here.

  • The total is never stored as a dedicated field: total is always computed from lines. This makes the invariant “the total equals the sum of the lines” structurally guaranteed, with nothing left to check.
  • assertInvariants() runs after every state change: every method that mutates state — adding a line, placing the order — ends by validating all invariants together.
  • Other aggregates are held only by ID: customerId is just a string (an ID); the class never holds a reference to a Customer object.
type OrderStatus = "Draft" | "Placed";

// The aggregate-wide invariants, expressed together with zod's refine
const OrderInvariants = z
  .object({
    status: z.enum(["Draft", "Placed"]),
    lineCount: z.number().int().nonnegative(),
    total: MoneySchema,
  })
  .refine((s) => s.status !== "Placed" || s.lineCount > 0, {
    message: "A placed order must have at least one line item",
  })
  .refine((s) => s.status !== "Placed" || s.total > 0, {
    message: "A placed order's total must be greater than zero",
  });

class DomainError extends Error {}

class Order {
  private lines: OrderLine[] = [];
  private status: OrderStatus = "Draft";
  private domainEvents: Array<{ type: string; [k: string]: unknown }> = [];

  private constructor(
    public readonly id: string,
    public readonly customerId: CustomerId, // reference the Customer aggregate by ID only
  ) {}

  // ---- Factory: create a new order ----
  static create(id: string, customerId: string): Order {
    CustomerIdSchema.parse(customerId);
    return new Order(id, customerId);
  }

  // ---- Factory: reconstruct from persistence ----
  static reconstruct(
    id: string,
    customerId: string,
    lines: OrderLineProps[],
    status: OrderStatus,
  ): Order {
    const order = new Order(id, customerId);
    order.lines = lines.map(OrderLine.create);
    order.status = status;
    return order;
  }

  get total(): Money {
    return this.lines.reduce((sum, l) => sum + l.subtotal, 0);
  }

  addLine(productId: string, unitPrice: number, quantity: number): void {
    if (this.status !== "Draft") {
      throw new DomainError(
        "Cannot add a line to an order that is already placed",
      );
    }
    const existing = this.lines.find((l) => l.productId === productId);
    this.lines = existing
      ? this.lines.map((l) =>
          l.productId === productId ? l.withQuantity(l.quantity + quantity) : l,
        )
      : [...this.lines, OrderLine.create({ productId, unitPrice, quantity })];

    this.assertInvariants();
  }

  place(): void {
    if (this.status !== "Draft") {
      throw new DomainError("Only a draft order can be placed");
    }
    this.status = "Placed";
    this.assertInvariants();
    this.domainEvents.push({
      type: "OrderPlaced",
      orderId: this.id,
      total: this.total,
    });
  }

  pullDomainEvents() {
    const events = this.domainEvents;
    this.domainEvents = [];
    return events;
  }

  toSnapshot() {
    return {
      id: this.id,
      customerId: this.customerId,
      status: this.status,
      lines: this.lines.map((l) => l.snapshot),
    };
  }

  private assertInvariants(): void {
    OrderInvariants.parse({
      status: this.status,
      lineCount: this.lines.length,
      total: this.total,
    });
  }
}

Finally, a repository that persists the aggregate as a single unit. It exposes only save and findById — there is no method for reading or writing an individual OrderLine.

interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | undefined>;
}

class InMemoryOrderRepository implements OrderRepository {
  private store = new Map<string, ReturnType<Order["toSnapshot"]>>();

  async save(order: Order): Promise<void> {
    // The aggregate is always saved as one whole unit.
    this.store.set(order.id, order.toSnapshot());
  }

  async findById(id: string): Promise<Order | undefined> {
    const snapshot = this.store.get(id);
    if (!snapshot) return undefined;
    return Order.reconstruct(
      snapshot.id,
      snapshot.customerId,
      snapshot.lines as OrderLineProps[],
      snapshot.status as OrderStatus,
    );
  }
}

Here is a usage example. An operation that would violate an invariant is rejected with an exception.

const repo = new InMemoryOrderRepository();
const customerId = crypto.randomUUID();

const order = Order.create(crypto.randomUUID(), customerId);
order.addLine(crypto.randomUUID(), 1200, 2);
order.addLine(crypto.randomUUID(), 3000, 1);
order.place(); // fires the OrderPlaced event

await repo.save(order);

const reloaded = await repo.findById(order.id);
console.log(reloaded?.total); // 5400

// Example: violating an invariant by placing an order with no lines
const empty = Order.create(crypto.randomUUID(), customerId);
try {
  empty.place();
} catch (e) {
  console.error((e as Error).message); // "A placed order must have at least one line item"
}

zod’s refine is a good fit for expressing cross-cutting rules over a snapshot of the whole aggregate declaratively, so they can be checked after every state change. Meanwhile, an invariant like “total equals the sum of the lines,” which can be guaranteed structurally, is more robust when it is never stored as a redundant field in the first place. Combining the two is the practical balance to strike.

Common Design Failures

Four patterns tend to trip up aggregate design.

The Giant Aggregate (God Aggregate)

This happens when everything that “seems related” gets stuffed into the same aggregate, on the theory that it’s safer that way. Vernon warns against exactly this: as an aggregate grows, the cost of loading and saving it rises, concurrent-update conflicts become frequent, and testing becomes difficult ( Vaughn Vernon, Effective Aggregate Design Part I ). “Being related” and “being bound together by a true invariant” are different things, and only the latter is grounds for merging objects into one aggregate.

Direct References Between Aggregates

This happens when an entity in one aggregate holds a direct object reference (a pointer) to an object in a different aggregate. As noted earlier, other aggregates should always be referenced by ID. Allowing object references invites unintended loading of an entire object graph via ORM lazy loading, and creates implicit dependencies that cross aggregate boundaries.

Updating Multiple Aggregates in One Transaction

This happens when, “since we’re already in here,” multiple aggregates get updated together inside a single transaction. It violates Vernon’s Rule 1. As the next section explains in more detail, consistency across aggregates is a problem to be solved with eventual consistency driven by domain events.

The Anemic Domain Model

This happens when the aggregate root class becomes a bag of getters and setters, with all the business logic and invariant checks pushed out into a service layer. Martin Fowler calls this the Anemic Domain Model and describes it as an anti-pattern that forfeits the basic benefits of object-oriented design ( Martin Fowler, AnemicDomainModel ). The responsibility for protecting invariants belongs to the aggregate root’s own methods, not to some external service — which is exactly why addLine and place are methods on Order itself in the code above.

Transactions and Eventual Consistency

As Vernon’s Rule 1 states, as a rule, only one aggregate should be updated within a single transaction. This is less a constraint than a natural consequence of drawing the aggregate boundary correctly. If an aggregate is exactly the set of objects bound together by a true invariant, and everything inside it stays consistent within one transaction, there is simply no need to update multiple aggregates together in the same transaction.

So how is consistency across aggregates achieved? The answer is eventual consistency, driven by domain events.

One transaction per aggregate, and eventual consistency Figure 2: Placing an Order completes within transaction 1 and publishes an OrderPlaced domain event. The Inventory aggregate, which manages stock, is updated asynchronously in a separate transaction 2 in response to that event. The two aggregates cooperate through eventual consistency.

Suppose that placing an order (OrderPlaced) should reserve inventory. It’s tempting to perform “place the order” and “reserve the inventory” synchronously in one transaction — but that means updating two aggregates, Order and Inventory, in a single transaction, which violates Vernon’s rule.

Instead, the Order aggregate completes the placement within its own transaction and simply publishes an OrderPlaced domain event. The Inventory aggregate subscribes to that event and reserves stock inside a separate transaction. A small time lag can occur between the two steps, but they eventually converge on a consistent state. That is the essence of eventual consistency.

Adopting eventual consistency means dealing with retries when event processing fails and with idempotency to guard against double-processing — more design overhead than a single synchronous update. But paying that cost in exchange for keeping aggregates small is exactly the trade-off Vernon argues for throughout his work.

Summary

  • An aggregate is a cluster of related objects treated as a unit for data changes — not merely a grouping, but a unit of responsibility for guaranteeing consistency.
  • The aggregate root is the sole external gateway; internal objects can never be accessed directly.
  • The aggregate boundary is determined not by transactional convenience but by the true invariants that must always hold.
  • Vernon’s four rules — protect true invariants within the boundary, design small, reference other aggregates by ID, and use eventual consistency outside the boundary — are practical guidance for keeping aggregates small and loosely coupled.
  • In a TypeScript implementation, invariants that can be guaranteed structurally (like “total equals the sum of the lines”) should not be duplicated as stored fields, while invariants spanning multiple fields are conveniently validated together with zod’s refine — striking a practical balance.
  • Giant aggregates, direct references between aggregates, updating multiple aggregates in one transaction, and anemic domain models are classic failure patterns, and every one of them arises from straying off the principle of “let invariants draw the boundary.”
  • Consistency across aggregates is resolved through eventual consistency driven by domain events. Keeping to one aggregate per transaction is the foundation of a scalable domain model.

Frequently Asked Questions

Q. What is the difference between an aggregate and an entity?

An entity is a single domain object whose identity is defined by an ID. An aggregate is a consistency unit that bundles one or more entities and value objects together under a true invariant, and it always contains exactly one aggregate root (an entity). When an aggregate consists of a single entity, that entity is itself the aggregate root. Not every entity is an aggregate — many entities exist as internal objects subordinate to another aggregate’s root.

Q. How large should an aggregate be?

As small as possible, per Vernon’s Rule 2. The smallest configuration is an aggregate made of just the root entity, to which you add only the elements without which a true invariant could not be protected. Adding elements just because they “seem related” or “might be useful later” is exactly how giant (god) aggregates happen.

Q. What if I find myself wanting to update multiple aggregates in one transaction?

First, question whether the requirement is really a true invariant — something that must hold immediately. In most cases it isn’t, and eventual consistency via domain events is sufficient. If, after careful consideration, synchronous consistency truly is required, that’s a signal to revisit the modeling itself and reconsider whether the aggregate boundary has been drawn correctly.

Q. Why is it forbidden to update anything other than the aggregate root directly?

Because the aggregate root is the gatekeeper responsible for protecting the aggregate’s invariants. If internal objects could be modified directly from outside, state could change without the aggregate root’s knowledge, and the very invariants the root is supposed to enforce would slip through unchecked. Only by routing every change through the aggregate root’s methods can the invariants be guaranteed to hold at all times.

References

この記事に関連する無料ツール

DevToolBox JSON Formatter JSONを整形・圧縮・バリデーション

関連記事