Entities & Value Objects

DDD divides domain objects into two fundamental kinds, and getting the distinction right is the difference between a clean model and a tangle of primitives. An entity has an identity that persists through change; a value object is defined purely by its attributes and is immutable. Most bugs in modeling come from treating a value as an entity, or - far more commonly - not modeling values at all and drowning in raw Strings and BigDecimals.

Entities: identity that outlives change

An entity is something the business tracks as the same thing over time, even as its attributes change. A Transaction in ledger-legacy is an entity: its amount might be corrected, its status moves from pending to settled, but it's still the same transaction, identified by its id.

class Transaction {                        // an ENTITY - has identity
    private final TransactionId id;        // identity, set once, never changes
    private Money amount;                  // attributes CAN change over time
    private TransactionStatus status;

    // equality is by IDENTITY, not attributes
    public boolean equals(Object o) {
        return o instanceof Transaction t && this.id.equals(t.id);
    }
    public int hashCode() { return id.hashCode(); }
}

The defining traits: a stable identity (an id assigned at creation), equality by that identity (two transactions are "the same" iff same id, regardless of current attributes), and a lifecycle (created, modified, archived). Ask: if all its attributes changed, would the business still call it the same thing? If yes, it's an entity.

Value objects: defined by what they are

A value object has no identity - it's entirely described by its attributes, and two with equal attributes are interchangeable. Money, a DateRange, an Address - $50 USD is $50 USD; there's no "which fifty dollars." Value objects are immutable and compared by value:

record Money(BigDecimal amount, Currency currency) {   // a VALUE OBJECT
    Money {                                             // validate invariants at creation
        if (amount.scale() > currency.getDefaultFractionDigits())
            throw new IllegalArgumentException("too many decimal places");
    }
    Money add(Money other) {                            // operations return NEW instances
        requireSameCurrency(other);
        return new Money(amount.add(other.amount), currency);   // no mutation
    }
}
// equality is automatic and by-value for records: Money(50,USD).equals(Money(50,USD)) == true

Java records are the perfect fit: immutable, value-based equals/hashCode for free. Operations don't mutate; they return new instances (like String or LocalDate).

Why value objects matter so much

The most impactful DDD-lite habit is replacing primitives with value objects - the cure for "primitive obsession." Compare:

void transfer(BigDecimal amount, String currency, String fromAccount, String toAccount)  // 🚩 all primitives
void transfer(Money amount, AccountId from, AccountId to)                                 // ✅ typed values

The second version:

• Can't be called wrong - you can't accidentally swap from and to if they're both raw Strings... but with AccountId types plus clear names, and impossible to pass a currency where an account goes.
• Centralizes validation - Money's constructor rejects negative or over-precise amounts once, so no caller can construct an invalid one.
• Carries behavior - money.add(other) enforces currency-matching; scattered BigDecimal arithmetic doesn't.
• Makes illegal states unrepresentable - a DateRange that guarantees start ≤ end can't express an inverted range.