ADR-0013: Value objects for domain primitives — self-validating, with a converter
Status: Accepted
Date: 2026-06-10
Scope: core (any backend with a domain layer)
Context
Some domain values are “just a String/BigDecimal” on the surface but actually
carry a canonical form and validity rules: an email (lower-cased, RFC-ish
shape), a phone number (E.164 digits), money, a CPF/CNPJ, a postal code. Modelling
them as raw primitives has three costs:
Normalization and validation scatter. Every use case and DTO that accepts the
value re-trims, re-lowercases, re-checks the format — or forgets to.
Invalid values can exist. A raw String email can hold " FOO"; nothing
stops it.
Nowhere to hang behavior. “Give me the email domain”, “give me the local
part”, “format this phone number for a given provider” have no home, so they leak
into services as static helpers.
This is the value-type counterpart to 0003-ddd-intent-methods (entities own entity invariants): a value should own its own validity and behavior.
Decision
Model such values as value objects in domain/vo/:
A record whose compact constructor normalizes, then validates — so an
invalid instance cannot be constructed. Fail fast at the boundary of the type,
not deep in a use case.
Value-specific behavior lives on the VO, not in services
(Email.getDomain(), Email.getLocalPart()).
Immutable, value-equality (records give both).
Persisted via a JPA AttributeConverter annotated @Converter(autoApply = true),
so entities declare the field as the VO type while the column stays a plain scalar.
Adopting a VO for an existing column needs no migration, and reads of legacy
rows are normalized on the way in.
Entities hold the VO, never the primitive — User.email is an Email.
Validation vs. user-facing errors
The VO constructor throws IllegalArgumentException — that is a structural
backstop, not the UX layer. Friendly 4xx messages are still produced at the
boundary: bean-validation annotations on the request DTO (@Email, @Pattern)
or a ValidationStrategy. The VO guarantees no invalid value reaches the domain
even if a boundary check is missing; the boundary guarantees a nice message.
Historical:PhoneNumber (E.164 normalization, waId() / waIdVariants() for Brazilian 9th-digit matching, PhoneNumberConverter) applied
the same pattern to the Expenses WhatsApp channel. It was deleted with that channel
(Expenses product ADR-0009, 2026-10-10); Email is the live reference.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
public record Email(String value) { private static final Pattern EMAIL_PATTERN = Pattern.compile( "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"); public Email { if (value == null || value.isBlank()) { throw new IllegalArgumentException("Email must not be blank"); } value = value.toLowerCase().trim(); // normalize FIRST if (!isValidFormat(value)) { // then validate throw new IllegalArgumentException("Invalid email format: " + value); } } public String getDomain() { return value.substring(value.indexOf('@') + 1); } public String getLocalPart() { return value.substring(0, value.indexOf('@')); }}
Normalization runs before validation, which is the whole trick: Gabriel@Example.COM
and gabriel@example.com become the same value, and an Email that exists is an Email
that is valid. No code path produces a malformed one, so nothing downstream re-checks.
getDomain() lives here rather than in a service — it is a question about the value, not
about a use case.
Because the column stays a plain varchar behind the converter, adopting this on an
existing field needed no migration, and legacy rows are normalized as they are read.
Source: expenses · domain/vo/Email.java
When to use / when not
Use a VO when the value has a canonical form, validity rules, or behavior, or
recurs across the domain. Do not wrap every string — a free-text name or description with no rules stays a String. A VO with an empty constructor and no
methods is a smell; that value didn’t need one.
Consequences
Normalization + validation are defined once, at the type.
“Impossible to hold an invalid value” — entire classes of guard code disappear.
A natural home for value behavior, keeping services about orchestration.
Zero-migration adoption and legacy-value healing via the converter.
Cost: a small class + converter per value; don’t over-apply (see above).
Related
0003-ddd-intent-methods — entities own entity invariants; VOs own value
invariants. The pair makes the domain layer self-protecting end to end.
0011-dto-design-rules — DTOs are wire contracts at the boundary; VOs are
domain types. A DTO field may be a primitive that maps to a VO in the entity.
Frontend ADR-0003 (masked inputs for formattable values) — the client-side analog:
the same “formattable value” gets a display mask in the UI and a VO in the domain.