Validate a command

Goal: stop bad input from ever becoming an event. A blank name, a negative quantity, a duplicate email — you want the command rejected, with a clear reason, before Handle() runs.

Validation runs before the handler

Arc runs validators before it invokes Handle(). A command that fails validation never appends anything and returns a CommandResult carrying the errors — and because the rules are extracted into the generated proxy, they also run on the client for instant feedback. There are three places a rule can live; reach for the narrowest one that fits.

Do it

1. A rule that’s true of a value everywhere → validate the value type. Write a ConceptValidator<T> and it applies to every command carrying that concept:

   public class AuthorNameValidator : ConceptValidator<AuthorName>
   {
       public AuthorNameValidator() =>
           RuleFor(x => x.Value).NotEmpty().WithMessage("An author needs a name.");
   }

2. A rule specific to one command → validate the command. Use a CommandValidator<TCommand> (FluentValidation) for cross-field or command-only rules:

   public class RegisterAuthorValidator : CommandValidator<RegisterAuthor>
   {
       public RegisterAuthorValidator() =>
           RuleFor(c => c.Name).NotEmpty().MaximumLength(200);
   }

   For lightweight cases, data annotations like [Required] on the command record work too.

3. A rule that depends on existing state → decide inside Handle(). Uniqueness can’t be checked against an eventually-consistent read model without a race. Instead, inject the read model Arc resolves for this command’s key and return a typed error:

   public Result<ValidationResult, AuthorRegistered> Handle(RegisteredAuthorName? existing) =>
       existing is not null && existing.Name != AuthorName.NotSet
           ? ValidationResult.Error("An author with that name is already registered.")
           : new AuthorRegistered(Name);

Validators are discovered by convention — you never register them. The frontend surfaces the messages automatically; see Run a command from React.

See also

• Command Validation and Validation — the full validation model.
• Make it trustworthy — the same ideas, taught step by step.
• Return a result or an error — the Result<,> return shape used above.