Validation at Trust Boundaries

01 / Start here

Follow one request

Validation is easier to understand when every rule answers a question about the same payload.

Imagine an API that creates a document. The client sends the request below. It looks reasonable, but five details need a decision: extra spaces, uppercase letters, duplicate tags, a numeric string, and a tenant chosen by the client.

{
  "title": "  API Design  ",
  "slug": "API-Design",
  "tags": ["Backend", "backend"],
  "visibility": "tenant",
  "retentionDays": "30",
  "tenantId": "tenant-b"
}

02 / Parse

Parsing only means “I can read it”

Valid JSON can still be the wrong value for your API.

A parser recognizes JSON syntax. It can return an object, array, string, number, Boolean, or null. It does not know that this endpoint expects a document command.

Keep the parsed result as unknown. Writing JSON.parse(text) as DocumentInput changes TypeScript's belief; it does not inspect the value that arrived.

03 / Rules

Check type, syntax, then meaning

These checks sound similar, but they answer different questions.

Run cheap checks first. There is no reason to test a slug pattern until you know the value is a string. There is no reason to query slug availability until the string has the right format.

• Type: string, number, Boolean, array, object, or null.
• Syntax: length, pattern, range, and collection size.
• Meaning: cross-field rules, current state, and domain policy.

04 / Transform

Transform only with a reason

A transformation is part of the contract because it changes what the client sent.

For this API, trimming the title and lowercasing the slug are documented choices. Converting the string "30" into the number 30 is not. Silent coercion makes mistakes look valid.

Validate again after normalization. The two tags in our request become the same value after lowercasing, so the request must report a duplicate instead of silently dropping one.

05 / Authority

Let the client control less

A write contract should list the fields a client may propose—not mirror the database model.

tenantId is well-formed in the example request, but the client is not allowed to choose it. Read tenant, owner, identifiers, and timestamps from trusted server context.

Reject unknown keys and build a fresh command from named properties. Object spread or a recursive merge can accidentally accept server-owned fields and dangerous keys such as __proto__.

06 / Limits

Stop oversized work early

Field rules cannot help after the service has already exhausted memory or CPU.

Choose the parser from an allowlist. Reject an unsupported media type with 415 and content beyond the endpoint budget with 413. Content-Length is only a hint; count the bytes actually received.

Compressed bodies need a limit after decompression. Parsers also need limits for nesting depth, field count, array length, string length, numeric range, and processing time.

• Allowlist request media types.
• Count received and decompressed bytes.
• Bound depth, fields, arrays, strings, and parse time.
• Stop reading after rejection and release buffers.

07 / Ownership

Put each rule where the evidence exists

The edge can check a payload. It cannot know every fact required to accept the operation.

A validator can require retentionDays when visibility is tenant. Authorization must decide whether this principal may create tenant-visible documents. The database must preserve slug uniqueness when two requests race.

Validate early for useful feedback, but keep authorization and datastore constraints. Passing one boundary never proves the next one.

08 / Errors

Return an error the client can act on

A good 4xx response says which input failed without exposing sensitive internals.

Use stable machine-readable codes and field paths. Human messages may improve later, so clients should not parse them for control flow.

Do not echo the whole payload, secrets, database details, or authorization reasoning. Log a safe boundary name, issue code, endpoint, and correlation identifier instead.

{
  "type": "https://backend.therakibul.me/problems/validation",
  "title": "Request validation failed",
  "status": 422,
  "issues": [
    { "path": "$.retentionDays", "code": "invalid-type" },
    { "path": "$.tags[1]", "code": "normalization-conflict" },
    { "path": "$["tenantId"]", "code": "unknown-field" }
  ]
}

09 / Pipeline

Build one narrow transition at a time

Each function should accept the last proven type and return the next one.

The runtime boundary starts with unknown. Structural validation returns a DTO. Normalization returns a canonical command. Authorization then combines that command with trusted principal and tenant context.

export function validateDocumentCommand(
  input: unknown,
): ValidationResult<DocumentCommand> {
  const structural = validateDocumentInput(input);
  if (!structural.ok) return structural;

  return normalizeDocumentInput(structural.value);
}

10 / Verify

Test the edges, not only the happy path

Boundary tests should show what passes, what fails, and which layer owns the failure.

For every limit, test the minimum, maximum, and one value beyond. Include wrong root values, missing and unknown keys, type mismatches, normalization collisions, inherited properties, and server-owned field attempts.

Use integration tests for byte limits, decompression, parser depth, authorization, and database races. Pure validator tests cannot prove behavior owned by those adapters.

• Accepted output never aliases the caller's arrays or objects.
• Normalization is idempotent: running it twice gives the same result.
• Unknown and inherited keys never reach the domain command.
• Issue order and machine-readable codes stay deterministic.
• Public errors contain no raw body, secret, or authorization detail.