Shared Schemas & Boundary Design When to share validation, why transport schemas are not Prisma models, and avoiding premature packages
Phase 12 - DTOs, Zod & Input Validation Volume 04 - Professional Backend
Architecture milestone API transport contract
↓
application/domain rules
↓
persistence model
Phase 12 introduces an explicit runtime validation boundary before controller and service logic.
Should Zod schemas be shared with Next.js now? Zod can run in both Node.js and browsers, so it is tempting to immediately move every schema into packages/validators. That may eventually be useful, but Phase 12 does not create a shared package merely because sharing is possible.
Question If yes...
Does the frontend need exactly the same request contract? A shared schema may reduce drift.
Does moving the schema create package/build complexity now? Keep it API-local until the benefit is concrete.
Does the backend schema import server-only generated Prisma Avoid shipping server coupling into a browser package. code?
Would a shared transport schema be stable across clients? Shared validation may become valuable.
Our current task schemas import generated Prisma enums. That is convenient inside the API but is also a signal that blindly exporting the file to a browser package could couple frontend code to backend persistence generation.
A future shared-contract direction Figure 1 - Possible later evolution packages/validators: transport-only schemas
↓
apps/web imports browser-safe request schema↓
apps/api imports same transport schema↓
Share a contract because multiple consumers genuinely need it, not because the monorepo has a packages folder.
Validation schema is not your database model A transport schema describes what an API caller may send. Prisma schema describes durable relational structure. They overlap, but they should not be treated as identical artifacts.
title max length policy column type / persisted value
unknown request keys not applicable to row schema
projectId must be UUID text foreign key relation must reference existing Project
Do not make the frontend speak Prisma. Do not make Prisma schema the HTTP API. Let each boundary have the representation that matches its responsibility.
Avoid validation duplication inside service methods Once a service is only callable through validated controllers, it can often assume transport shape correctness. But service methods may later be reused by jobs, CLI tools, tests, or internal workflows. At that point, decide whether those callers need their own validated boundary or a stronger domain-level invariant. Do not simply sprinkle schema.parse() everywhere.
Authentication answers who the request represents. Treating decoded or client-supplied identity as trusted is a security boundary failure.
Restate the goal of “Shared Schemas and Boundary Design” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: credentials/session → token → verification → trusted identity → protected operation. Mark the one boundary this lesson changes.
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
Connect the slice to TaskFlow’s phase artifact: Reusable create/update/query schemas integrated into NestJS request handling with useful validation errors.. Verify behavior from the outside as a user or API client would.
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.
const token = readBearerToken(request);
const claims = await verifier.verify(token);
request.user = {
id: claims.sub,
email: claims.email,
};Do not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.
Inspect whether a token exists, whether it is expired, which issuer/audience signed it, and what the API verifier expects.
Trust only verified server claims; never repair identity by accepting a client-sent user id.
Without copying the final source, create a second small scenario that applies “Shared Schemas and Boundary Design” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Integrate validation at the NestJS boundary before the service receives data.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Assuming TypeScript validates runtime JSON
Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?
If your explanation is vague, repeat the boundary trace before moving on.Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.