From as MyType to Real API Contracts.

01

What a type assertion actually promises

TypeScript’s as Invoice is an assertion to the compiler. It doesn’t parse, convert, or validate incoming JSON. Assertions disappear during compilation. A generic helper such as fetchJson<Invoice>() has the same limitation unless its implementation performs a real runtime check.^S1

Type assertions aren’t inherently wrong. They can express knowledge the compiler can’t infer. The problem is using them as evidence about bytes that came from somewhere else.

Treat external data as unknown until you have checked it. That includes network responses, webhook bodies, queue messages, environment variables, and data returned through loosely typed database or plugin adapters.

Static types help you use known values consistently while writing code. Runtime validation establishes whether a particular value meets a contract when the program actually runs.

02

Schema-first means the contract can execute

Suppose your API lets an authorized support agent submit a refund request. The contract includes an invoice ID, an amount in minor currency units, and a short reason. Assume this example supports only currencies with two decimal places, so 4900 means 49.00.

In Zod, the runtime schema can also supply the TypeScript type. safeParse returns a success or failure result; z.infer derives the type of successfully parsed output.^S2

import { z } from "zod";

export const RefundRequest = z.strictObject({
  invoiceId: z.string().uuid(),
  amountMinor: z.number().int().positive().max(1_000_000),
  reason: z.string().trim().min(10).max(500),
});

export type RefundRequest = z.infer<typeof RefundRequest>;

Here, z.strictObject rejects unknown fields. The numeric rules reject a string, fraction, non-positive number, or value above the example’s per-request ceiling. Trimming happens before the length checks on the reason.^S3

Those choices are policy decisions encoded into the contract. If a browser form provides a string, deliberately convert its input before submission. Don’t silently coerce every public API input and hope that empty strings, unexpected formats, or accidental units work out.

The ceiling above is only an illustrative request bound. Whether this invoice has enough refundable balance is a separate question that requires current business state.

03

Put checks at the boundaries that need them

The browser can use a shared request schema to show immediate feedback. The server must still validate the request because callers can bypass the browser. The client should also validate external responses before treating them as application data.

Avoid importing your whole server into the frontend just to share a type. A small contract package should contain portable schemas and inferred types, with no database client, environment secrets, or server-only dependencies.

Once you’ve parsed an input into a well-defined internal representation, ordinary functions inside the same trusted process can use the inferred type. You don’t need to reparse the same value at every function call. Validate again when it crosses a real trust or serialization boundary, or when assumptions about it change.

On the server, keep the first steps explicit. This is a framework-neutral handler sketch: requirePrincipal, badRequest, and validationError are application adapters, not library functions.

const principal = await requirePrincipal(request);

let raw: unknown;
try {
  raw = await request.json();
} catch {
  return badRequest("invalid_json");
}

const parsed = RefundRequest.safeParse(raw);
if (!parsed.success) {
  return validationError(parsed.error.issues);
}

const command = parsed.data;
// Next: authorize the operation and invoice, then transact.

Enforce body-size and content-type limits before parsing. Return a documented validation error with safe field paths and error codes; don’t echo arbitrary request bodies or internal diagnostics. Keep malformed JSON separate from a valid JSON object that fails the schema.^S4

Also keep working with parsed.data. If a schema trims, transforms, or strips anything, checking the input and then continuing with the original object throws away the parser’s result.

04

A valid object can still be an unauthorized request

The refund request doesn’t contain tenantId, role, or approvedBy. Those values belong to trusted server context. Letting a caller supply them would invite the caller to describe the authority they’d like to have.

First check whether the principal may request refunds. Then load the invoice within the principal’s authorized tenant scope. Then apply any object-specific restrictions and the relevant business rules.

This is the difference between authentication (who is calling), authorization (what that caller may do to this object), and validation (whether the input meets the contract). A valid UUID proves none of the first two. OWASP describes missing object-level checks as Broken Object Level Authorization.^S5

If the invoice is outside the caller’s scope, follow a consistent denial policy. Some applications return a not-found response to avoid revealing that another tenant’s object exists. Whatever the policy, don’t first return the record and hope the frontend hides it.

This is where the phrase “zero trust” needs a little discipline. NIST’s model rejects implicit trust based solely on network location or ownership. An internal request still needs an appropriate identity and authorization decision. Schema validation supports that design, but it doesn’t establish a complete zero-trust architecture.^S6

A perfectly validated request over a trusted network can still be an attempt to refund someone else’s invoice.

05

The database must hold the line during a race

Imagine an invoice with 6000 minor units left to refund. Two requests for 4000 arrive at almost the same time. Both pass the input schema. Both read the same available balance. Both decide the refund is allowed.

If the writes aren’t coordinated, you’ve accepted 8000 against 6000.

Use a transaction and a concurrency strategy that makes the invariant hold when requests overlap. For example, lock the tenant-scoped invoice row, check the remaining balance, reserve the amount, and record the refund operation before committing. Every path that changes that balance must follow the same invariant-preserving strategy.

Use a client-supplied idempotency key, scoped to the tenant and operation, to recognize retries. Store a fingerprint of the request payload with it. Reusing the key with a different payload should be a conflict, rather than a second interpretation of the same operation.

A supporting table might include these constraints:

CREATE TABLE refund_requests (
  id uuid PRIMARY KEY,
  tenant_id uuid NOT NULL,
  invoice_id uuid NOT NULL,
  idempotency_key text NOT NULL,
  payload_fingerprint text NOT NULL,
  amount_minor bigint NOT NULL CHECK (amount_minor > 0),
  UNIQUE (tenant_id, idempotency_key),
  FOREIGN KEY (tenant_id, invoice_id)
    REFERENCES invoices (tenant_id, id)
);

This illustrative DDL assumes invoices has a unique constraint on (tenant_id, id). The composite foreign key prevents linking the refund to an invoice under a different tenant. NOT NULL, uniqueness, checks, and foreign keys enforce specific storage invariants even if another writer bypasses the HTTP handler.^S7

If an external payment service is involved, don’t pretend a database transaction makes that remote side effect atomic. Commit the local intent and an outbox event together; have a worker send the request using a stable provider idempotency key where supported, then record or reconcile the outcome.

06

Give each layer a small, clear responsibility

The code is easier to reason about when the boundaries are visible in its structure. A practical arrangement:

The transport layer turns bytes into a validated command and an authenticated principal. The application layer decides whether that principal can execute the use case. The domain rules define the valid state change. Persistence makes the change safe under concurrent access. Integration adapters translate and validate the external systems’ contracts.

Keep transport details out of the domain. Your refund rule should not need to know whether a command came from HTTP, a queue, or an MCP tool. Each entry point must establish the same required identity, contract, and policy before invoking it.

07

Generated clients help when the source of truth is clear

Sharing a Zod contract works well when both sides use TypeScript and can coordinate package versions. Other systems need a language-neutral contract.

OpenAPI describes HTTP APIs, including operations and schemas. Tooling can use that description to generate clients, server interfaces, or documentation.^S8 gRPC commonly starts from protocol buffer service and message definitions and generates client and server code for supported languages.^S9

Choose a contract authority for each boundary. You might author OpenAPI and generate types, or author a supported schema subset and generate OpenAPI from it. The important property is a repeatable direction of generation. Hand-editing three competing descriptions creates drift.

Inspect what the generator actually produces. A typed client that deserializes JSON and asserts the expected type still needs runtime validation. A protobuf decoder can check the wire representation, but a positive refund limit, object ownership, and a permitted state transition remain application rules unless you explicitly implement additional validation and policy.

Not every schema feature translates cleanly. A custom Zod refinement that queries a database won’t become a portable OpenAPI constraint. Separate portable structural rules from business rules, and test the boundary where generated code meets actual payloads.

08

Validate what leaves the service, too

Returning an ORM entity directly is a quick way to expose fields you never intended to publish. Build an explicit response object, then validate it against a response schema. That catches accidental contract drift and makes the public shape reviewable.

Use a response projection that lists allowed fields. Don’t rely on a strict parser alone to remove secrets: a strict parser rejects extras; it doesn’t silently clean them. Choose response parsing behavior deliberately, including whether clients tolerate additive fields for compatibility.

On the browser side, check the HTTP status, parse the body as unknown, and validate the appropriate success or error schema. A server error page is not an invoice, even if a type assertion says otherwise. ApiError, ApiErrorBody, and ContractError below are application definitions.

// Responses tolerate additive fields (z.object strips unknown keys),
// so the server can add data without breaking older clients.
const Invoice = z.object({
  id: z.string().uuid(),
  amountMinor: z.number().int(),
  status: z.enum(["open", "paid", "refunded"]),
});

export async function getInvoice(id: string) {
  const response = await fetch(`/api/invoices/${encodeURIComponent(id)}`);
  const body: unknown = await response.json().catch(() => null);

  if (!response.ok) {
    throw new ApiError(response.status, ApiErrorBody.safeParse(body).data);
  }

  const parsed = Invoice.safeParse(body);
  if (!parsed.success) {
    throw new ContractError("invoice", parsed.error.issues);
  }
  return parsed.data; // typed by the schema, checked at runtime
}

Version changes deserve the same care. New required fields break old clients. An added enum value may break exhaustive client logic. Define compatibility rules, pin generation tooling, and run contract checks against representative old and new payloads.

09

Prove the failures are contained

Good boundary tests look slightly rude. Send a string where a number belongs. Add an unexpected role field. Use a valid invoice ID from another tenant. Repeat an idempotency key with a changed amount. Race two refund requests against the same balance. Simulate a provider timeout after it accepted an operation.

Check the observable result: denied access, unchanged unauthorized records, preserved balance, stable retry behavior, and a response that matches the public contract. Passing the schema’s happy path is only the beginning.

You still need ordinary API controls: protected transport, rate limits, parameterized queries, safe secret handling, and monitoring. A schema can’t replace those controls. What it can do is make the data contract explicit and executable, so the rest of the system starts from something firmer than a cast.

The next time you’re about to write as MyType after a network call, pause at that boundary. Define what the value must contain, validate it, establish who may use it, and protect the state it can change. Your editor will still be happy. This time, the running system has reasons to be happy too.