Architecture

Use Value Objects for Validated Domain Concepts

Represent concepts such as money, email addresses, and date ranges as immutable values with explicit validation.

Value objects represent concepts defined by their values rather than by a unique identity. They can centralize validation and prevent invalid combinations from spreading through an application.

Choose meaningful concepts

Money, percentage, email address, postal address, and date range are common examples. A value object should enforce rules that belong to the concept, such as currency compatibility or a start date not occurring after an end date.

Prefer immutability

An immutable value object is created in a valid state and cannot later be changed into an invalid one. Operations return new values. This makes behavior easier to test and reason about.

Avoid primitive obsession

Do not create a wrapper around every string or integer without a domain reason. A value object is useful when it adds validation, behavior, formatting rules, or semantic clarity.

Persistence and serialization

Map value objects to database columns or structured representations at the persistence boundary. Keep serialization formats explicit and stable for APIs.

Checklist

  • Model concepts with meaningful invariants.
  • Validate at construction boundaries.
  • Prefer immutable behavior.
  • Avoid wrappers without domain value.
  • Map values explicitly to persistence and APIs.
Share this page Help other developers discover this resource.