Value Objects

A Value Object represents an immutable concept defined entirely by its values.

Characteristics

• Immutable
• Equality by value
• Hashable
• No independent identity

Value Objects model concepts such as identifiers, measurements, or descriptive values where identity is not meaningful.

When to use

Inherit from ValueObject when you need immutability, value-based equality, and hashing in one base class. Validate in the constructor — a Money(amount=-5) should never exist. This keeps constraints local and testable.

Avoiding Primitive Obsession

Value Objects prevent domain rules from being scattered across the codebase. Wrapping meaning in explicit types makes constraints visible, reusable, and testable.

Where the implementation lives

The ValueObject base class lives in the Foundation block because value-based equality and immutability are reusable outside the Domain block.