liveBook · Manning

Syntax validation

As explained in Clean Applications with Hexagonal Architecture

Validation that checks whether input has the required presence and format without evaluating its business meaning.

A create request can be structurally malformed, syntactically invalid, or violate a business rule. Syntax validation checks whether input is present and correctly shaped; it does not decide whether the input is meaningful in the domain. section 3.8 section 3.8.1

Place each check where its responsibility belongs:

  • Primary adapters check transport structure, such as whether a request body is parseable and required fields are present. section 3.8
  • Commands and queries check input shape, such as nonblank strings and correctly formatted UUIDs. section 3.8
  • Handlers orchestrate without repeating checks; domain entities, value objects, and services enforce business invariants. section 3.8

Validating a create command

A CreateArticleCommand can validate that title and content are nonblank and that article and author IDs have UUID format. Combining these checks can return all validation errors together. A valid command can then be trusted by its handler, while rules such as title uniqueness remain domain responsibilities. section 3.8.1 section 3.8

Table 3.2 Input validation vs business invariants
Aspect
Input validation
Business invariant
Where
Commands, queries, adapters
Domain entities, value objects, domain services
When
At the boundary, before entering the core
At construction time or during state transitions
Response to failure
Return all errors at once (user-friendly)
Reject invalid state; either fail fast or return accumulated domain errors, depending on the operation
Error type
Validation errors—expected, recoverable
Domain errors— business rule or state violations

Compare boundary input checks with domain invariants by location, timing, and failure response. section 3.8

Listing 3.17 Using validations for input data
@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
public class CreateArticleCommand {
  private final String id;
  private final String title;
  private final String content;
  private final String authorId;
 
  public static Validation<Seq<ValidationError>, #A
    CreateArticleCommand> validateThenCreate(
    final String id, final String title,
    final String content, final String authorId) {
      return Validation.combine(
        validateUUID(id, "Article ID"),
        validateNotBlank(title, "Title"),
        validateNotBlank(content, "Content"),
        validateUUID(authorId, "Author ID") #B
    ).ap(CreateArticleCommand::new); #C
  }
 
  private static Validation<ValidationError, String> 
    validateNotBlank(final String value, final String fieldName) {
      return (value == null || value.isBlank())
        ? Validation.invalid(new ValidationError(
            fieldName + " must not be blank"))
        : Validation.valid(value);
  }
 
  private static Validation<ValidationError, String> validateUUID(
    final String value, final String fieldName) {
      return Try.of(() -> UUID.fromString(value)) #D
        .map(uuid -> value)
        .toValidation(new ValidationError(
           fieldName + " must be a valid UUID"));
  }
}

See a Java command factory that combines field validations before constructing a command. section 3.8.1

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains layer placement, accumulated errors, and command construction, while reserving business-rule validation for the domain.
Examples
Checks article and author UUIDs and nonblank title and content in a create command.
What you can do after
Apply the Validation monad in command factories to collect syntactic errors before handing valid commands to handlers.
How it connects
Connects commands and queries, primary adapters, handlers, domain entities, value objects, and business invariants.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.