Accumulating Assembly
Building a record from N validated fields: every error reported at once.
- Build a record from independently validated fields with
Validated.fields(), and report every bad field by name - Read where each error belongs from its path, nested records included (
address.zip) - Guard a record whose constructor can refuse its fields, with
construct - Run the same assembly on
Validated,ValidationPathorEitherOrBoth, and say what each does with a failed field - Choose between the builder,
@GenerateAssembly,zipWithAccumand themapNfamily
The code on this page is ValidatedAssemblyBook.java: the page includes it, so the build compiles and runs it. ValidatedAssemblyBookTest.java holds the errors it reports.
ValidatedAssemblyExample.java is a longer, standalone example.
Which field was wrong?
Validated checks fields independently and keeps every error. Unless a message spells out its field, as street is required does, a list such as [not an email address, not a number] names no field, and no code can read one back out. Whoever sent the request usually needs to know: a form shows each error beside its field, and an HTTP 422 body names the field it rejects. A request DTO becoming a domain record, or raw configuration becoming a settings object, needs every error and its field.
Validated.fields() gives each field a label as it joins the assembly, and every error that field reports carries the label.
The front door: fields()
Validated.fields() opens a labelled assembly over NonEmptyList<FieldError>. A FieldError is a small record, path segments plus a message, with a pathString() such as "address.zip". Each field(label, value) adds one validated field; apply(...) completes the assembly with a constructor reference or lambda of exactly the accumulated arity:
Validated<NonEmptyList<FieldError>, User> assembled =
Validated.fields()
.field("name", parseName(dto.name())) // Validated<NonEmptyList<FieldError>, Name>
.field("email", parseEmail(dto.email()))
.field("age", parseAge(dto.age()))
.apply(User::new); // (Name, Email, Age) -> User
// Invalid(NonEmptyList[email: not an email address, age: not a number]) - name was fine.
Three guarantees, all by construction:
- Every bad field is reported at once. Nothing short-circuits; accumulation is
NonEmptyListconcatenation. - Errors are located.
field("email", ...)prepends"email"onto each error's path viaFieldError.at, so consumers can render"email: not an email address"or map errors onto form fields. - Errors emerge in field-declaration order. The order of
field(...)calls is the order of the errors, which makes downstream output (an HTTP 422 body, a CLI report) deterministic.
A leaf validator creates unlabelled errors with FieldError.of("message"); the assembly attaches the location.
When the record refuses: construct
A record often guards itself: a compact constructor that throws when its fields disagree. apply runs whatever function you hand it, so that exception escapes the assembly. It takes with it whatever an enclosing assembly had collected around it, and, on EitherOrBoth, the tolerant carrier, the warnings this one had. construct completes the assembly the same way but guards the call. Once every field is valid, a RuntimeException the function throws becomes an unlabelled FieldError carrying the exception's message, or the fallback you pass when the message is missing or blank:
// The record guards itself: a window must close after it opens.
record Window(LocalDate opens, LocalDate closes) {
Window {
if (!closes.isAfter(opens)) {
throw new IllegalArgumentException("closes must be after opens");
}
}
}
Validated<NonEmptyList<FieldError>, Window> window =
Validated.fields()
.field("opens", parseDate("2026-03-09"))
.field("closes", parseDate("2026-03-07"))
.construct(Window::new, "not a valid Window"); // apply(Window::new) would throw
// Invalid(NonEmptyList[closes must be after opens]) - unlabelled: the whole window is refused
The rules are the generated mappings' own (a record's own invariants):
- The function runs last. It needs every field, so it runs only once all of them are valid, and a record reports either its fields' errors or its refusal, never both.
- The refusal is unlabelled, so the
field(label, ...)that nests the assembly locates it:window: closes must be after opens. - Any
RuntimeExceptioncounts, so a bug in the function reaches the caller as its message, with its stack trace dropped. Keep the function to checks on its arguments, with messages written for whoever reads the errors. - Only the function is guarded. A
nullit returns still throws, as it does fromapply; only what the function itself throws is a refusal. - Every labelled builder has it:
Validated.fields(),Path.fields(), andEitherOrBoth.fields(). On the tolerant carrier a failed field still short-circuits the function, while aBothfield's warning does not, so a refusal there comes back as aLeftcarrying those warnings and the refusal. The genericaccumulate()builders have noFieldErrorto build, so they end inapplyonly.
Nesting composes
Because at() prepends, assembling a sub-record under an outer label prefixes all its inner paths:
Validated<NonEmptyList<FieldError>, Address> address =
Validated.fields()
.field("street", parseStreet(raw.street()))
.field("zip", parseZip(raw.zip())) // fails: "zip: not a postcode"
.apply(Address::new);
Validated<NonEmptyList<FieldError>, Customer> customer =
Validated.fields()
.field("name", parseName(raw.name()))
.field("address", address) // prefixes: "address.zip: not a postcode"
.apply(Customer::new);
Nesting is also the way past the builder's limit. apply takes a function of at most 16 fields, matching the shipped Function3 to Function16, so a record with more fields nests a sub-record per group. That usually improves the domain model anyway, and @GenerateAssembly has no limit of its own.
The generic flavour: accumulate()
When your error type is not FieldError, Validated.accumulate() assembles the same way over NonEmptyList<X> for any payload X, joining fields with and(value). Validated shows it. It takes no Semigroup, the object that says how to join two errors, because the errors are always a NonEmptyList, joined by appending. The first of these trips up both builders, and the second only accumulate():
- Inline literals need explicit type arguments. A chained stage receives no target typing, so an inline factory call such as
.field("age", Validated.invalidNel(FieldError.of("bad")))infersObjectand the compile error surfaces later, atapply. WriteValidated.<FieldError, Integer>invalidNel(...)for inline literals; values with declared types (the results of leaf validators) need none. - Error payloads are invariant. Suppose an assembly collects a sealed
ConfigError, and a leaf returnsValidated<NonEmptyList<PortError>, A>for one of its subtypes,PortError. The leaf does not widen to the assembly's payload. Widen at the leaf:parsePort(raw).mapError(nel -> nel.map(e -> (ConfigError) e)), or have leaf validators return the hierarchy's root type directly.
One shape, three carriers
The same two entry points exist on each carrier, so the assembly reads identically whichever error strategy the surrounding code uses:
| Carrier | Entries | Result | Behaviour |
|---|---|---|---|
Validated | Validated.fields() / Validated.accumulate() | Validated<NonEmptyList<E>, R> | strict: any invalid field fails the assembly, all errors kept |
ValidationPath | Path.fields() / Path.accumulate() | ValidationPath<NonEmptyList<E>, R> | the railway flavour; composes onward with via, zipWithAccum, recover |
EitherOrBoth | EitherOrBoth.fields() / EitherOrBoth.accumulate() | EitherOrBoth<NonEmptyList<E>, R> | tolerant: warnings accumulate (Both) while the value keeps flowing; any Left dominates, still keeping every warning |
The tolerant flavour is the natural fit for lenient config parsing:
EitherOrBoth<NonEmptyList<String>, Config> cfg =
EitherOrBoth.accumulate()
.and(parsePortLenient(rawConfig.port())) // Both(NonEmptyList[port defaulted], 8080)
.and(parseTimeoutLenient(rawConfig.timeout())) // Right(30)
.apply(Config::new);
// Both(NonEmptyList[port defaulted], Config[port=8080, timeout=30])
Under the hood every stage transition delegates to the existing accumulation primitives: Validated.ap with NonEmptyList.semigroup(), ValidationPath.zipWithAccum, and EitherOrBoth.zipWithAccum. The builder introduces no second accumulation mechanism.
Generating the companion: @GenerateAssembly
For a record you own, the annotation processor generates a companion that removes three ways the hand-written chain can go wrong:
- Labels come from the component names, so a typo or a rename cannot break them.
- Field order cannot be wrong: the stage methods are named, and must be called in order.
- The generator sets no limit on the number of fields of its own: it emits the exact arity, even past 16.
@GenerateAssembly
record User(Name name, Email email, Age age) {}
Validated<NonEmptyList<FieldError>, User> generated =
UserAssembly.fields()
.name(parseName(dto.name())) // label "name" attached automatically
.email(parseEmail(dto.email()))
.age(parseAge(dto.age()))
.assemble(); // canonical constructor baked in
A component whose type is itself annotated accepts its sub-companion's result directly, and the outer component name prefixes the inner paths (address.zip). The companion lives in the record's package, named <Record>Assembly; for a nested record the enclosing simple names are joined (Outer.Inner gives OuterInnerAssembly). Under the hood the companion merges through the same Validated.ap / NonEmptyList.semigroup() primitives as the builder, so the two agree on every input the record's constructor accepts. Where the constructor throws, they part. The builder's apply lets the exception propagate, while assemble() reports it as an unlabelled FieldError carrying the exception's message. That is the same invariant guard the generated mappings use. End the builder with construct instead of apply and the two agree again. Generic records are not supported yet; use the hand-written fields() builder for records you cannot annotate. The companion names the record and each component's type from the record's package, so the processor refuses one that is private, or nested in a private class, naming the class to change (Compiler Messages).
Choosing the right tool
| You are combining... | Reach for |
|---|---|
| N independent fields into a record | fields() / accumulate() |
N validated fields into an existing value (sparse update / PATCH) | Edits.accumulate |
| A record you own, assembled in many places | @GenerateAssembly |
| Two or three values, inline, no labels needed | zipWithAccum / zipWith3Accum on the Path types, or EitherOrBoth.zipWithAccum |
Values inside generic Kind-polymorphic code | the Applicative mapN family |
| Steps where later ones depend on earlier results | flatMap / via (short-circuiting, by design) |
hkj-test asserts a whole accumulation as rendered "path: message" lines with assertThatValidated(result).hasFieldErrors(...), and takes a single error apart with assertThatFieldError:
assertThatFieldError(FieldError.of("not a postcode").at("zip").at("address"))
.hasPath("address.zip")
.hasSegments("address", "zip")
.hasMessageContaining("postcode");
fields()assembles a record from N validated fields with located errors;accumulate()is the generic-payload twin.- No
Semigroupargument and noKind.applytakes up to 16 fields; a wider record nests sub-records, or uses@GenerateAssembly. - Errors always emerge in field-declaration order.
- Nesting prepends the outer label:
"address.zip". construct(Record::new, "not a valid Record")guards a constructor that may refuse the fields;applydoes not.- The same shape exists on
Validated,ValidationPath(viaPath), andEitherOrBoth(tolerant).
- Validated: the underlying strict accumulating type
- NonEmptyList: the error carrier the builder is fixed to
- EitherOrBoth: the tolerant carrier
- ValidationPath: the railway validation API
- Validated Prisms: a leaf parser with a faithful render-back is a
ValidatedPrism: passvp.parse(raw)tofield(label, ...). (fields()accumulates siblings; a prism'sandThenshort-circuits nesting.) - Applicative: the
mapNfamily forKind-generic code - Many Edits at Once: the same all-errors-at-once model for updating existing values