Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Entity

Pattern

A reusable solution you can apply to your work.

An entity is a thing in your domain that has a distinct identity, persists through change, and can be told apart from every other thing of its kind.

“Many objects are not fundamentally defined by their attributes, but rather by a thread of continuity and identity.” — Eric Evans, Domain-Driven Design

Understand This First

  • Domain Model – the domain model identifies which concepts in your business deserve to be entities.
  • Ubiquitous Language – entities are named in the domain language so everyone refers to them the same way.
  • Data Model – a data model stores the attributes that entities carry, but the entity itself is a domain concept, not a row in a table.

Context

You have a domain model that names the concepts your software deals with. Some of those concepts are passive facts: a monetary amount, a date, a street address. Others are the protagonists of your business. Orders get placed, modified, cancelled, and shipped. Customers sign up, change their email, add credit cards, and eventually close their accounts. These things change, and your software has to keep track of which order or which customer is being changed, even as their details shift.

This operates at the architectural level. The decision to treat something as an entity shapes the database, the API, the code organization, and the way agents reason about the system. Entities are the nouns your system remembers individually. Everything else hangs off them.

The idea goes back to Eric Evans’s 2003 book Domain-Driven Design, where entities were defined by their “thread of continuity”: the sense that an object can change over time and still be the same object. That framing matters more now than ever. An AI agent working in a codebase needs to know which concepts have lives of their own and which are disposable values. Get this wrong and the agent will generate code that overwrites a customer record instead of updating it, or deduplicates orders that were supposed to remain distinct.

Problem

How do you decide which concepts in your system need their own identity, and how do you make that identity stable enough to survive changes to the data around it?

A team building an inventory system writes a Product class with fields for name, price, description, and stock count. Two weeks in, they hit a problem: the marketing team wants to rename a product and change its price, but existing orders need to remember what the product was called and what it cost at the time of purchase. If Product is just a bag of attributes, updating those fields silently corrupts the order history.

The team didn’t mean to build a history-rewriting system, but that’s what they got. They never decided whether a Product was a thing with identity that persists through change or a snapshot of information at a moment in time. Those are different concepts, and the code needs to treat them differently.

Forces

  • Some concepts are defined by what they contain: a color, a price, a coordinate. Others are defined by who they are: a specific customer, a specific invoice. The code has to distinguish these even though both look like objects with fields.
  • Identity must survive change. A customer who updates their email is still the same customer. If your code treats the new email as a new customer, history breaks.
  • Identity must survive across boundaries. The same customer appears in the billing database, the support system, and the analytics pipeline. Without a shared identifier, the three systems can’t agree they’re talking about one person.
  • Agents can’t infer which concepts carry identity. If the code doesn’t make the distinction explicit, the agent will guess, and the guess will sometimes be wrong in ways that look correct on review.

Solution

For each concept in your domain model, ask: if two instances have identical attributes, are they the same thing or different things? If the answer is “different” (two customers named Alice Smith are still two distinct customers), the concept is an entity and needs its own identity. If the answer is “same” (two instances of the amount $47.00 are interchangeable), it’s not an entity and should be modeled as a plain value.

Once you’ve identified an entity, give it a stable identifier that is independent of its attributes. A customer’s identity is not their email, because emails change. It’s not their name, because names change. It’s an ID (a UUID, a database key, a domain-specific number like a customer number) that you assign when the entity is created and never change for the rest of its life. This identifier is the thread that connects the customer as they existed yesterday to the customer as they exist today, even if every other field has been updated.

Write this decision down. In the code, an entity class exposes its identifier as a first-class property, compares equality by identifier (not by attribute values), and enforces the business rules that govern how its state can change. A BankAccount entity doesn’t just have a balance field; it has a deposit() method that prevents the balance from going negative. Shipping a pile of attributes without behavior gives you what Martin Fowler called an “anemic domain model”: a data structure wearing a class costume. Entities earn their keep by owning the rules that protect their consistency.

For agentic workflows, include the list of entities and their identifiers in the agent’s context. When you direct an agent to add a feature that touches customers or orders, tell it explicitly: “Customer identity is the customer_id field, not the email. Email changes must update the existing customer, not create a new one.” Agents follow the distinctions you make explicit. They invent the distinctions you leave implicit, and those inventions are where the subtle bugs live.

How It Plays Out

An online bookstore treats Book and Copy as two different things. A book is the published work: its title, author, and ISBN don’t change. Two paperback copies of the same novel on the warehouse shelf look identical, but each has its own condition, location, and history of loans. The team models Book as an entity identified by ISBN and Copy as a separate entity identified by an internal barcode. When a customer buys a specific used copy, the system knows which physical object left the warehouse. A year later, when that same customer complains the pages were damaged, the support team can look up exactly which copy they received.

A small SaaS team builds a project management tool and directs an agent to add a team-renaming feature. Without explicit guidance, the agent considers two approaches: update the existing team’s name field, or create a new team with the new name and migrate everything over. It picks the second approach because it produces cleaner audit logs. The team discovers this during testing, when renaming a team breaks every integration that stored the old team ID.

The fix: tell the agent (and write it into the project glossary) that teams are entities identified by team_id, and that renaming is an attribute change on the existing entity, not a replacement. The agent regenerates the feature correctly once the rule is explicit.

Example Prompt

“In this codebase, Order is an entity identified by order_id. Orders are immutable once placed: you cannot change their line items or total. Instead, add an OrderAmendment entity that references the original order_id and records the change. The customer’s order history should show the original order plus any amendments, not a rewritten version of the original.”

Consequences

Distinguishing entities from non-entities gives you a clear map of what your system remembers individually. The database schema falls out of the entity list: each entity type gets its own table with a primary key that matches its identifier. APIs become predictable because endpoints are organized around entities (/customers/{id}, /orders/{id}) rather than ad-hoc operations. Agents generate more coherent code because they can see which concepts are first-class citizens and which are supporting values.

The cost is upfront thought. Deciding whether a concept is an entity takes a real conversation with domain experts. Getting it wrong early is expensive: promoting a value to an entity later means adding an identifier, migrating existing data, and updating every place the concept appears. Teams sometimes overcorrect by making everything an entity, which drowns the model in bookkeeping. A good test: if you never need to reference a particular instance later, or if two instances with identical attributes are interchangeable, don’t give it identity.

Don’t confuse identity with uniqueness. A phone number is unique, but it’s not an entity. It’s an attribute of a customer. The question isn’t “is this value unique?” but “does this thing have a life of its own?” Phone numbers don’t; customers do. If you’re not sure, ask what happens when the attribute changes. If the thing keeps existing with a new value, it has identity. If replacing the value means you’re talking about a different thing, it doesn’t.

  • Uses / Depends on: Domain Model – the domain model identifies which concepts deserve to be entities.
  • Uses / Depends on: Ubiquitous Language – entities are named in the domain language so everyone refers to them consistently.
  • Enables: Data Model – entities become the tables, primary keys, and foreign key relationships in the data model.
  • Enables: Source of Truth – each entity has one authoritative place where its current state lives.
  • Enables: Consistency – entities enforce their own invariants through the methods that modify them.
  • Enables: CRUD – create, read, update, and delete operations are organized around entities.
  • Contrasts with: Data Structure – data structures are implementation-level containers; an entity is a domain concept with identity and behavior.
  • Refined by: Bounded Context – the same real-world thing may be a different entity in different bounded contexts, each with its own identifier and rules.

Sources

  • Eric Evans introduced the entity as a core building block of domain-driven design in Domain-Driven Design: Tackling Complexity in the Heart of Software (2003). The epigraph and the “thread of continuity” framing both come from his treatment in Chapter 5, where entities are distinguished from value objects by whether their identity matters independently of their attributes.
  • Martin Fowler cataloged the entity pattern in Patterns of Enterprise Application Architecture (2002) as part of the Domain Model pattern, and later coined the term “anemic domain model” in a 2003 bliki entry to name the failure mode of entities that carry data without enforcing rules. Both ideas shape this article’s guidance that entities should own the behavior that protects their invariants.
  • Vaughn Vernon, in Implementing Domain-Driven Design (2013), offered the concrete test used in the Solution section: two instances with identical attributes are the same thing if they are values, and different things if they are entities. His treatment also influenced the warning against treating uniqueness as a proxy for identity.

Further Reading

  • Vaughn Vernon, Domain-Driven Design Distilled (2016) – a short, accessible introduction that covers entities and value objects without requiring the full weight of Evans’s original book.