A raw String used as a title leaves every caller to decide what a valid title means. A value object replaces that primitive with a small, immutable domain type that owns its constraints. Once constructed, it carries a valid value rather than a validation obligation. section 3.4
A value object has no identity: its attributes determine equality. Two titles with the same text are equal, even when used by different articles. Unlike an entity, a value object does not retain a distinct identity across state changes. It belongs in the framework-free domain core, where it can be used alongside entities and aggregates. section 3.1 section 3.4
Enforce constraints at construction. A Java record can validate a small value locally in its canonical constructor; the Title below rejects blank text and text longer than 500 characters. Explicit parameter types then communicate meaning and prevent callers from accidentally passing one domain concept in place of another. section 3.4
Listing 3.9 Examples of value objects
public record Title(String value) {
public Title { #A
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("Title must not be blank");
}
if (value.length() > 500) {
throw new IllegalArgumentException(
"Title must not exceed 500 characters");
}
}
}
public record ArticleId(UUID value) {
public ArticleId {
Objects.requireNonNull(value, "ArticleId must not be null");
} #B
}
public record Content(String value) {
public Content {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("Content must not be blank");
}
}
}
These Java records put each value's checks at its construction boundary. section 3.4
A value object can also combine related attributes and provide behavior. PublicationPeriod checks that its end is not before its start, then answers whether a date falls within the period. Callers do not need to repeat the date-ordering rule. section 3.4
Listing 3.11 Example of value object encapsulating multiple related attributes
public record PublicationPeriod(LocalDate from, LocalDate to) {
public PublicationPeriod { #A
Objects.requireNonNull(from,
"Publication start date must not be null");
Objects.requireNonNull(to,
"Publication end date must not be null");
if (to.isBefore(from)) { #B
throw new IllegalArgumentException(
"Publication end date must not be before start date");
}
}
public boolean isActiveOn(final LocalDate date) { #C
return !date.isBefore(from) && !date.isAfter(to);
}
}
The period validates both dates and keeps its activity check with the values. section 3.4
A private constructor and validateThenCreate factory offer another construction path when failures should be returned as values. In the Either-based implementation, ArticleId uses a single UUID check; Title runs both its mandatory-text and length checks, accumulates failures, and creates an instance only when the error list is empty. section 9.2.1
Listing 9.2 Title: Accumulating two field rules before deciding
@Getter
@Accessors(fluent = true)
@EqualsAndHashCode(onlyExplicitlyIncluded = true)
@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
public class Title {
private static final int MAX_LENGTH = 500;
@EqualsAndHashCode.Include
private final String value;
public static Either<Error, Title>
validateThenCreate(final String title) {
final List<ValidationError> errors =
new ArrayList<>(); #A
Validations.mandatoryText(title, "title")
.peekLeft(errors::add); #B
Validations.maxLength(title, MAX_LENGTH,"title")
.peekLeft(errors::add);
return errors.isEmpty() #C
? Either.right(new Title(title))
: Either.left(new Error.ValidationErrors(
List.copyOf(errors)));
}
}
The Title factory returns either all accumulated validation errors or a valid object. section 9.2.1
Use a value object when a value expresses a distinct domain concept or has constraints of its own. At an application boundary, convert primitive command fields into value objects before assembling the aggregate; a failed conversion stops the creation chain. section 9.2.5 section 9.4.1




