Contracts and JSON validation
Understand what TypeScript inference proves, what runtime validation checks and which values are portable.
Keep types and validation distinct
TypeScript types describe authored code; they do not validate network input or database records. Use a supported runtime schema at every untrusted boundary. Share the contract value rather than manually repeating DTO types.
Service's Zod authoring infers DTOs and projects portable JSON Schema. Tool and Worker contracts accept supported Standard JSON Schema providers. Plain JSON schemas remain available, but separate generic DTO annotations are application assertions.
import { zodStandardJsonSchema } from "@smoothie-framework/foundation/zod";
import { defineZodEndpointContract } from "@smoothie-framework/service/zod";Stay inside the JSON boundary
Portable values are JSON-shaped: finite numbers, strings, booleans, null, arrays and supported plain objects. Cycles, functions, class instances, bigints and non-finite numbers cannot cross these boundaries.
Foundation supplies bounded snapshots, limited JSON Schema validation, canonical serialization and digests. It is not a complete JSON Schema engine. Consult supported keywords/formats when designing a public contract.
Do not hide behavior in projection
Transforms, defaults, coercion, custom refinements and flagged regular expressions cannot be silently preserved in portable JSON Schema. Projection rejects unsupported behavior. Normalize explicitly and perform business validation at its owner.
A Service body schema requires a body unless bodyRequired is false; optional object fields do not make the whole body optional. OpenAPI export requires the narrower status-specific JSON profile.
See Service contract authoring for the executable path and browser projection and OpenAPI for build-specific constraints.