ddd-value-object

One-line summary

A value object is a concept defined entirely by its attributes — no identity, immutable, equal by value.

When to use this skill

• Modeling Money, Address, DateRange, EmailAddress, ProductCode, Percentage, PhoneNumber.
• Replacing a primitive (String, Long, BigDecimal) that carries invariants the type system doesn't enforce.
• Distinguishing two concepts that share an underlying primitive type (CustomerId vs OrderId — both UUIDs, never interchangeable).
• Encapsulating domain operations that belong with a concept: Money.add(Money), Address.normalize(), DateRange.contains(Instant).

When NOT to use this skill

• The concept has a lifecycle or identity → use ddd-entity.
• The wrap would add neither invariants nor behavior — wrapping for the sake of wrapping is ceremony.
• A primitive is used in only one place and never crosses boundaries — the cost of the wrap may exceed the benefit.

Core content