Accumulating Assembly

Building a record from N validated fields: every error reported at once.

What You'll Learn

  • 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, ValidationPath or EitherOrBoth, and say what each does with a failed field
  • Choose between the builder, @GenerateAssembly, zipWithAccum and the mapN family

See Example Code

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 NonEmptyList concatenation.
  • Errors are located. field("email", ...) prepends "email" onto each error's path via FieldError.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 RuntimeException counts, 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 null it returns still throws, as it does from apply; only what the function itself throws is a refusal.
  • Every labelled builder has it: Validated.fields(), Path.fields(), and EitherOrBoth.fields(). On the tolerant carrier a failed field still short-circuits the function, while a Both field's warning does not, so a refusal there comes back as a Left carrying those warnings and the refusal. The generic accumulate() builders have no FieldError to build, so they end in apply only.

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():

Two inference notes

  • 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"))) infers Object and the compile error surfaces later, at apply. Write Validated.<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 returns Validated<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:

CarrierEntriesResultBehaviour
ValidatedValidated.fields() / Validated.accumulate()Validated<NonEmptyList<E>, R>strict: any invalid field fails the assembly, all errors kept
ValidationPathPath.fields() / Path.accumulate()ValidationPath<NonEmptyList<E>, R>the railway flavour; composes onward with via, zipWithAccum, recover
EitherOrBothEitherOrBoth.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 recordfields() / 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 neededzipWithAccum / zipWith3Accum on the Path types, or EitherOrBoth.zipWithAccum
Values inside generic Kind-polymorphic codethe Applicative mapN family
Steps where later ones depend on earlier resultsflatMap / via (short-circuiting, by design)

Testing located errors

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");

Key Takeaways

  • fields() assembles a record from N validated fields with located errors; accumulate() is the generic-payload twin.
  • No Semigroup argument and no Kind. apply takes 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; apply does not.
  • The same shape exists on Validated, ValidationPath (via Path), and EitherOrBoth (tolerant).

See Also

  • 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: pass vp.parse(raw) to field(label, ...). (fields() accumulates siblings; a prism's andThen short-circuits nesting.)
  • Applicative: the mapN family for Kind-generic code
  • Many Edits at Once: the same all-errors-at-once model for updating existing values

Previous: Validated Next: Try