Entities & Value Objects
Entities are distinguished by their identity and their life cycle. Value Objects are fully described by their business values.
- EntityThe same identifier means the same object.
- Value ObjectThe same values mean the same.
- Comparison ofEntity over identifier, value over all values.
Context
Why this is important
Those who confuse identity and value receive false equality behavior: orders are compared by fields, amounts such as individual objects are tracked. This includes primitive obsession: an amount as a nude number knows no currency, and money never belongs in a floating point number. The consistency boundary of several objects is handled by the building block aggregates.
This building block explains identity and value equality. For the common consistency boundary of multiple objects see aggregates.
At a glance · Identity versus values
Is that the same thing?
Order B-1042 Despite the change of status, the same order remains. Two sums of money from 49,90 EUR are technically the same as soon as the amount and currency match.
This is how you read the picture
- Entity Order B-1042 Before and after: identifier the same, status different, yet the same.
- Value Object Amount of money 49,90 EUR: Amount and currency highlighted, both sides equal.
- Comparison of The highlighted fields show for each pair what is compared.
Order
NumberB-1042 (comparison field)StatusDesigned forPositions2 Cups
Order
NumberB-1042 (comparison field)StatusacknowledgedPositions2 Cups
same orderComparison of Identification code. The identifier is the same. The status may change in the life cycle, the order remains the same.
Entity and Value Object in Comparison
| Character | Entity | Value Object |
|---|---|---|
| Shop example | Order B-1042 | Amount of money 49,90 EUR |
| Equality | Same order identification code | Equal amount and currency |
| Changes | Status changes over life cycle | New value replaces old value |
| Significance | Track the same order | Expressing business value |
Benefits & limitations
Helps if:
- Primitive fields allow invalid or conflicting combinations.
- Multiple values are validated, compared or calculated together.
Boundaries
- Not every number needs a value object. Too many small values inflate the code. It is worthwhile where rules, validation or calculations depend on value, for example in the case of money with currency.
- Persistence requires work: values need a mapping, such as embedded columns, and many ORMs expect object identifiers. Plan this mapping in Persistence from the outset.
In practice
- Identify the domain meaning and components. Group values that together form a rule or unit. Replace ambiguous primitive fields with a named concept.
- Define validation and equality. Specify valid combinations and when two values are equal in the domain. Use DDD Modelling to agree that meaning with domain experts.
- Safeguard operations on the value. Offer only calculations and comparisons that make sense for valid values. Check how the Value Object contributes to invariants within an Aggregate.
- Replace Primitive Obsession. Replace amount: number with Money(4990 cents, EUR) and validate it at creation. Store money in the smallest unit rather than as a floating-point number to avoid floating-point rounding errors.
Read the detailed explanation
A Value Object groups properties that together express a domain concept. Equality is determined by those components; changes are commonly represented by a new value. Validation at creation prevents invalid states. Entities are distinguished by stable identity; Aggregates use values to express invariants within a boundary. Domain-Driven Design places both concepts within a domain model.
Value Objects suit immutable concepts with well-defined operations. Equality must follow clear domain rules; reference equality alone is insufficient. Values should not share mutable internal state, so equality and validation remain valid throughout their lifetime.
An immutable interface is insufficient when internal references remain mutable. Values must not share mutable state, or a value could change without being replaced.
Check your understanding
Test yourself in three stages
ReadingCheck in the picture
Why apply 49,90 EUR; and 49,90 USD as different values, even though the amount is the same?
View the solution with justification
The amount and currency are compared together. If one of the two fields deviates, it is a different value.
ApplyingTransferred to a new situation
A position over 49,90 EUR shall be: 44,90 EUR discounted. What happens to the value?
View the solution with justification
The old value is not changed, but by a new amount of money from 44,90 EUR replaced.
EvaluateWeighing an alternative
Is an address a value object or an entity?
View the solution with justification
It depends on the context. In the order, only the information counts, i.e. a value. A customer management with an address book can keep it as an entity. Which context applies, clarifies the bounded context.
Explore further
These building blocks continue the thoughts of this page.
References
- Martin Fowler · Value Object (opens in new tab)Differentiates value-based equality of object identity.
- Microsoft · Implement Value Objects (opens in new tab)Shows equality, immutability and practical implementation of value objects.
- Microsoft Domain Model (opens in new tab)Explains entities, aggregates and business invariants based on an implementation.