Skip to content
Software Architecture Guide

Value Object

Explanation

Section titled “Explanation”

A value object is a small object such as a date, an amount of money, a point or a range. It has no identity. Its attribute values define it. Two value objects with the same values for all attributes count as equal.

An entity is different. An entity keeps its identity over time (see the article “Entity”). Entities tend to be big. Values tend to be little things. For the comparison, see “Entity and Value Object”.

Change means replace. You do not alter a value object. You replace it with a new one. Your height is not edited in place. You swap the old height object for a new one. The same holds for a party date: you create a new date object.

Why immutability matters. A shared mutable value can cause an aliasing bug. You change a date in one place, and the change has effects elsewhere that you did not expect. Making value objects immutable avoids this kind of bug.

Equality. Value objects compare by value, so the code must define equality that way. In languages such as Java, that means defining equals and hashCode from the attribute values.

Prefer value objects over primitives. A bare string is rarely a good domain type. Replacing common primitives, such as strings, with fitting value objects is often a good idea. A string that holds an amount becomes a money object. Two loose dates become a date range.

Context decides. Whether a concept is a value or a reference object depends on your context. Check which one fits your situation (see “Bounded Context”).

Example

Section titled “Example”

A shop stores a delivery period as two plain date fields on each order. Someone changes a shared date, and other orders shift unexpectedly.

The team introduces a DateRange value object with a start and an end. It cannot be changed after creation. To move the delivery, the code creates a new DateRange and puts it on the order. Two ranges with the same start and end are equal, so the code needs no ID to compare them.

Trade-offs

Section titled “Trade-offs”

Replacing a value means creating a new object each time, instead of editing one field. In return, you avoid aliasing bugs. Wrapping primitives in value objects adds more types to the model. The facts here suggest this is usually worth it for concepts such as money or ranges. Deciding whether a concept is a value or a reference object takes thought, because the answer changes with context.

Checks

Section titled “Checks”
  • Value objects in the model are immutable, and changes create a new object.
  • Equality of value objects is defined by comparing all attribute values.
  • Concepts like money, ranges or points are modeled as value objects rather than bare primitives.
  • The document states in which context each concept is treated as a value or as a reference object.
Section titled “Related”

Sources

Section titled “Sources”