A command object like `TransferFunds(fromAccountId, toAccountId, amount)` passes through validation before its handler runs any business logic. What kinds of checks belong in that pre-dispatch validation step, versus what should be left for the handler to check against live state?

## Two layers, split by one question Command validation naturally splits into two layers that differ in one crucial way: whether the check needs to look at anything outside the command itself. - **Structural validation**, sometimes called syntactic validation, asks only 'is this message well-formed' — are all required fields present, is the amount a positive number, are the account IDs the right shape, is the currency code valid. None of these checks touch a database or any other service; they can be answered purely by looking at the command object's own fields. - **Domain validation**, by contrast, asks 'is this true about the world right now' — does the source account actually exist, does it have enough balance, is it frozen, would this transfer push the sender over a daily limit. Answering any of these requires reading current state, which means domain validation cannot be fully resolved until the moment the handler actually runs against a loaded aggregate. | Structural validation | Domain validation | |---|---| | asks whether this message is well-formed | asks whether this is true about the world right now | | answered purely by looking at the command object's own fields | requires reading current state | ## Why the layering exists This layering exists to fail fast and cheap. Rejecting a malformed command before it ever reaches a handler, a database connection, or a message bus saves real cost: no wasted transaction, no wasted lock, no noise in domain-level error logs for what is really just a client bug. - **Self-validating commands** push this further by making it structurally impossible to construct an invalid command object at all — if the constructor throws on a negative amount, no downstream code path can ever receive one. - **Keeping structural checks separate from domain checks** also keeps each concern testable in isolation: structural rules can be unit-tested against the command class with no infrastructure, while domain rules are tested against the aggregate's behavior. ## The trade-off is where the line gets drawn The trade-off is where the line gets drawn, and it is easy to draw it wrong in both directions. 1. **Push too much into structural validation** — for example, checking 'does this account exist' before dispatch, using a stale read from a cache — and you either reject valid commands based on outdated information or, worse, let commands through that will fail once real domain state is consulted, forcing the handler to redo the same check anyway. 2. **Push too little in**, skipping structural validation entirely and letting every check happen inside the handler, and you pay full transactional and aggregate-loading cost just to reject a command that was missing a required field, which is wasted work at scale and a worse failure experience for the caller, who gets a generic domain error instead of a precise 'amount must be positive.' ## The most dangerous failure mode The most dangerous production failure mode is treating a domain check as if it were structural and evaluating it too early, outside the transaction that will perform the write. If a pre-dispatch validator checks 'source account balance is at least $50' by reading the balance once, and the actual debit happens later in the handler, a second transfer can drain that same balance in between the two, and the earlier check's approval is now stale — the handler must **re-verify the balance atomically with the debit itself**, typically by re-reading it inside the same database transaction, or via optimistic locking with a version check on write. Skipping this re-check is exactly how systems end up allowing accounts to go negative under concurrent load, even though every individual request 'passed validation.' ## Walking one transfer through both layers A concrete example from a banking-style `TransferFunds` flow: the API gateway or the command's own constructor rejects a request with a missing `toAccountId` or a zero amount immediately, before any database call is made — pure structural validation, resolved in microseconds with no I/O. The command then reaches the `TransferFunds` handler, which loads the source account aggregate inside a database transaction, checks its current balance and frozen status against the requested amount — domain validation, resolved against live, locked data — and only then applies the debit and commits. If the balance check had instead been done as a separate pre-dispatch step five seconds earlier, a concurrent withdrawal in those five seconds could have already emptied the account, and the transfer would proceed on outdated information unless the handler independently re-validates at write time. ## What each rejection tells the caller A further wrinkle worth naming explicitly: structural validation errors and domain validation errors usually deserve different status codes and different retry advice to the caller. - **A missing field or a malformed ID is a client bug** — retrying the exact same command will fail identically every time, so the correct response tells the caller to fix its request, typically surfaced as a 400-class error listing every violated field at once rather than one at a time. - **A domain rejection like insufficient balance is not a client bug in the same sense**; the command was perfectly well-formed, it simply couldn't be honored given the current state of the world, and a caller might reasonably retry later if the state changes, for example after a deposit clears — so many teams surface these as a distinct error family, sometimes called business or domain errors, precisely so client code and monitoring dashboards can tell 'you sent garbage' apart from 'the world said no' without parsing free-text messages.