Table of Contents
8. Entities & Value Objects — Two Roles, One Model
When people first encounter “entities” and “value objects”,
the terms often feel mismatched
— as if we're comparing two different species.
But they're not different species.
They're not even opposites.
They are simply two different roles a class can play in our domain.
Everything becomes clearer once we see that.
1. The Unifying Idea
Classes give us a way to create objects.
But the objects we create don’t all represent the same kind of concept.
Some objects represent meaning — the value itself is the thing.
Some objects represent identity — the thing exists as itself over time, even if its data changes.
That's the whole distinction.
We're not comparing two different kinds of programming constructs.
We're looking at two different roles an object can play in a domain:
- Value Objects express meaning.
- Entities express identity.
Both are just objects.
Both come from classes.
They differ only in the purpose they serve.
2. Value Objects — When Meaning Is the Identity
A value object represents a small piece of meaning in our domain
— something where the value itself defines what the thing is.
Examples:
- Money
- Email
- Temperature
- Coordinates
- Percentage
- DateRange
If two value objects contain the same data, they represent the same concept.
We can create multiple identical instances, but they don't carry separate meaning
— they are interchangeable.
new Money(10) === new Money(10)
There is no “Money #42”.
There is only “ten dollars”.
Does a value object need an ID property?
A value object doesn't need an identifier because its meaning is its identity.
Nothing about it needs to be tracked over time.
About immutability
Value objects are often immutable because meaning shouldn't shift unexpectedly.
But immutability is a technique, not the definition.
A value object is a value object because of what it represents,
not because of how it behaves.
3. Entities — When Identity Matters Over Time
An entity represents something that exists as a unique object in our domain
— something that continues to be itself even if its data changes.
Examples:
- User
- Order
- Ticket
- BlogPost
- Product
Two entities can have identical data and still be different things.
User #1 and User #2 may both be named "Alex", but they are not the same person.
Key idea:
An entity needs an ID because its identity is not defined by its data.
About mutability
Entities are often mutable because they change over time:
- a ticket gets assigned
- a post gets edited
- an order gets shipped
But mutability is a consequence,
not the definition.
An entity is an entity because it has identity.
It's data may or may not change, but the identity remains constant.
4. The Question Everyone Asks
“If something can change, should it be an entity?”
No.
Change does not make something an entity.
Identity does.
A value object can “change” too
— but when it changes, we get a new value.
$price = new Money(10); $newPrice = $price->add(5); // 15 dollars, a new value
The original value didn't mutate.
We simply created a new meaning.
5. "Should I add an ID to make it an entity?"
Only if the concept we're modeling has identity in the real world.
We don't “upgrade” a value object into an entity by adding an ID.
We choose the role based on the nature of the concept, not the code.
Use an Entity when the concept:
- persists over time
- can be referenced
- has a lifecycle
- is unique even if its data matches another
Use a Value Object when the concept:
- represents meaning
- is interchangeable with another of the same value
- doesn't need to be tracked
- doesn't have a lifecycle
6. Why the Names Feel Confusing
Because the terms come from domain modeling,
not programming.
“Entity” means “a thing that exists as itself over time”.
“Value Object” means “a piece of meaning”.
They are both objects in code.
They differ only in the role they play in our domain.
This is why comparing them as if they were two programming paradigms feels wrong
— because they're not paradigms.
They're purposes.
7. A Calm, Unified Mental Model
Here is the simplest way to hold the whole idea:
All classes are objects.
Some objects represent meaning → Value Objects.
Some objects represent identity → Entities.
Two roles.
One model.
No hierarchy.
No conflict.
Once we see this, the entire domain layer becomes easier to design.
8. How This Description May Help
This framing dissolves the false dichotomy that confuses us:
- It's not “immutable vs mutable”.
- It's not “simple vs complex”.
- It's not “data vs object”.
- It's not “apples vs oranges”.
It's simply:
- What role does this concept play in the domain?
Meaning → Value Object
Identity → Entity
Everything else flows naturally from that.
Summary
This page introduces two roles that objects can play in our domain.
If the distinction feels abstract at first,
that's normal — it becomes clearer each time we model a real concept.
Let the definitions settle, revisit them when needed,
and the domain will gradually reveal its shape.
Tony de Araujo —New York