Validation at the Boundary

The bytes that arrive on the socket are not a request. They are a claim, made by a client the service does not control, that a request is inside them. The boundary is where that claim is parsed into typed values or rejected, exactly once, and everything inside the boundary then deals in a SeatLabel and a HoldRequest, never in strings that might be anything. Stagedoor's first version checked the seat label in four handlers with four slightly different regular expressions and in a fifth handler not at all, and the fifth is the one that wrote 14c into a hold that no scanner could ever match.

The rule has a name, "parse, don't validate," and the difference between the two words carries the topic. A function that validates looks at the data and says yes or no, and the caller is left holding the same untyped data it had before. A function that parses hands back a value that cannot be wrong, and the caller holds a type that is the proof. Every later chapter assumes the second: Chapter 4's domain layer takes typed values, Chapter 5 authenticates a parsed token, Chapter 6 binds a SeatLabel to a query parameter and never re-checks it.

Parse, Don't Validate

validate(body) returns true, and the handler still holds a dictionary. Two lines later it reads body["seat_label"], which is a string, and passes it to a function that has to decide whether to trust it. parse(body) returns a HoldRequest or raises, and the handler holds a value whose seat_label is a SeatLabel that already matched one to three digits followed by one capital letter. No later function checks again, because the type is the record that the check happened. The difference shows up in the code that comes after: with validation, the same regular expression appears in every function that touches the label, because none of them can tell whether the caller ran it; with parsing, it appears once, in the constructor of the type, and every function that takes a SeatLabel is written as if the label is correct, because it is.

The Request Model as the Contract

One request model per endpoint, with types, constraints and defaults, is both the parser and the documentation. FastAPI builds the OpenAPI document of Chapter 10 from the model, so the shape a client reads in the docs is the shape the boundary enforces, by construction rather than by discipline. The demonstrated model is HoldRequest: an event id, a seat label, and nothing else.

SeatLabel = Annotated[str, StringConstraints(pattern=r"^[0-9]{1,3}[A-Z]$")]
EventId   = Annotated[int, Field(gt=0)]

class HoldRequest(BaseModel):
    model_config = ConfigDict(extra="forbid")   # seat_lable is a 422, not a silent no-op
    event_id: EventId
    seat_label: SeatLabel

async def create_hold(req: HoldRequest, user: CurrentUser) -> HoldResponse:
    # req.seat_label is a str that matched the pattern; nothing below re-checks it
    hold = await holds.create(user.id, req.event_id, req.seat_label)
    return HoldResponse.from_hold(hold)

The model says three things and each one is enforced before the handler runs. The seat label must be one to three digits and a capital letter, so 14c and a label with a trailing space are rejected at the edge. The event id must be a positive integer, so "abc" and 0 never reach a query. And unknown fields are forbidden, which is the line most models leave out: a client that sends seat_lable with a typo would otherwise be told 201 Created for a hold with no seat, silently, and would find out at the door. With extra="forbid" the typo is a 422 naming the unexpected field, and the client's developer fixes it in the first minute of integration instead of the last hour of the on-sale.

What Belongs at the Edge and What Does Not

Shape, type, range, format and required-ness are the edge's. Is it JSON, is event_id an integer, is it positive, does the label match the pattern, is the field present at all. Every one of those can be answered from the bytes alone, in microseconds, before any identity is known and before any connection is taken from the pool. "Is this seat available" and "does this user own this order" are different in kind: they need the database, they depend on who is asking, and their answer can change between the check and the write. They belong in the domain layer of Chapter 4, and they return different codes. A malformed label is a 422 for the client to fix. A seat that is held is a 409 for the client to route around, and Chapter 2 drew that line for exactly this reason.

The request model that queries the database is the tempting mistake. A validator on seat_label that checks availability runs before authentication, because parsing happens first, so an anonymous client can probe which seats are free at zero cost. It holds a pooled connection during parsing, which is the wrong place to hold one under 3,000 requests a second. And it answers a state question with a shape code, a 422 for "seat taken," so the client shows a form error for a fact about the world. Keep the edge to what the bytes can answer.

400 vs 422 and the Error Body

Unparseable bytes are a 400: the body is not JSON, the content type is wrong, the encoding is broken. Parseable bytes that fail the model are a 422: the JSON is fine and the request is not. FastAPI answers a body that is not JSON with a 422 out of the box, so Stagedoor registers one handler that maps the decode failure to 400, because the split is the part a client acts on. The distinction lets a client tell "my serializer is broken" from "my user typed something wrong," and it matters because the two are fixed by different people. The 422 carries a Problem Details body in the shape of Topic 15, with one entry per failing field: the field's path, the constraint it broke, and the value's type if that is the problem. All of the failures at once, not the first one found, so a form with three bad fields round-trips once, and the client highlights three fields instead of showing "invalid request" and guessing.

Trusting the Inside

Once parsed, a value is passed by type through every layer, and no layer checks it again. A SeatLabel is never re-matched against the pattern in the domain layer. A Money is never re-rounded in the storage layer. The boundary is the one place where the outside vocabulary, strings and numbers that might be anything, is translated into the inside vocabulary, types that carry their own proof. A second check deeper in is not defensive programming; it is a sign that the boundary leaked, that somewhere a raw string got in without passing through the parser, and the fix is to find the leak, not to add the check.

The discipline has a cost that is worth naming. Every type is a small class, and a codebase that takes it seriously has forty of them where a loose one has none. The forty are the reason the domain layer can be read without wondering what is in each variable, and the reason the seat label was checked in one place in the redesign instead of four and a half.

The Other Boundaries

HTTP is the obvious edge and not the only one. Payrail's webhook body arrives as bytes from a network Stagedoor does not own, and Chapter 10 parses it with a model and a signature check before anything reads a field. The job payload from the Redis stream was written by the service's own api process, which is why the first worker trusted it as if it were a local function call, and why one job with a malformed order id crashed every worker that claimed it in turn, which is Chapter 8's poison message. The environment at startup is bytes from the shell, and Chapter 4 parses it into a typed config object before the first request. Every place bytes enter the process is a boundary with its own parser, and the one that gets skipped is the one that hurts, because it is the one nobody thought was outside.