Entities and value objects matter because identity and meaning are not the same thing, and a healthy model treats them differently.

Why it matters in real Java systems

If a shipping address is treated like an entity when it should be a value object, the model becomes awkward. If an order is treated like just a value bag when it has identity and lifecycle, the model becomes brittle. This distinction affects almost every important modeling decision.

The main design idea

An entity is defined by continuity and identity. A value object is defined by attributes and meaning. Value objects are often immutable and easier to reason about. Entities usually own lifecycle and state transitions over time.

DDD makes this distinction especially useful because rich domain models often improve when more concepts become value objects and fewer concepts are treated as generic entities by default.

Key ideas to keep in mind

Example distinction

Java example in the Order Management domain

package org.javaomnibus.ecommerce.domain;

public record Money(java.math.BigDecimal amount, String currency) {}

public final class Order {
    private final OrderId id;
    private Money total;

    public Order(OrderId id, Money total) {
        this.id = id;
        this.total = total;
    }

    public OrderId id() {
        return id;
    }
}

Step by step

1. Money is a value object because its meaning comes from its amount and currency.
2. Order is an entity because its identity persists even as its state changes.
3. That distinction changes how equality and behavior are designed.
4. DDD becomes clearer when this decision is intentional rather than accidental.

Where this helps in practice

• Modeling money, addresses, ranges, and policy parameters as value objects
• Keeping orders, payments, and shipments as lifecycle-bearing entities
• Reducing primitive obsession and improving model meaning

Trade-offs and when to be careful

• Value objects improve clarity, but inventing too many tiny ones without clear meaning can hurt readability.
• Entities need discipline so identity does not become an excuse for weak modeling.

Frequent mistakes to watch for

• Treating every domain concept as an entity by default
• Using primitive types where a value object would express intent better
• Making value objects mutable without a clear reason
• Confusing database identifiers with the whole meaning of an entity

Related concepts