Create Schema

Creates Zod schemas with TypeScript type inference for new entities in this backend template.

Quick Reference

Location: src/schemas/{entity-name}.schema.ts Naming: Singular, kebab-case (e.g., note.schema.ts, course-registration.schema.ts)

Instructions

Step 1: Create the Schema File

Create a new file at src/schemas/{entity-name}.schema.ts

Step 2: Define the Entity ID Schema

Always start with a dedicated ID schema:

import { z } from "zod";

export const {entity}IdSchema = z.string();
export type {Entity}IdType = z.infer<typeof {entity}IdSchema>;

Step 3: Define the Base Entity Schema

export const {entity}Schema = z.object({
  id: {entity}IdSchema,                    // Primary key
  // ... entity-specific fields ...
  createdBy: userIdSchema,                 // If entity is user-owned (import from user.schemas)
  createdAt: z.date().optional(),          // Set by DB/service
  updatedAt: z.date().optional(),          // Set by DB/service
});

export type {Entity}Type = z.infer<typeof {entity}Schema>;

Step 4: Define Create DTO Schema

Omit system-managed fields and add validation:

export const create{Entity}Schema = {entity}Schema
  .omit({
    id: true,           // Generated by service/system
    createdBy: true,    // Set from authenticated user context
    createdAt: true,    // Set by service/database
    updatedAt: true,    // Set by service/database
  })
  .extend({
    // Add stricter validation for required fields
    fieldName: z.string().min(1, "{Entity} field is required for creation."),
  });
export type Create{Entity}Type = z.infer<typeof create{Entity}Schema>;

Step 5: Define Update DTO Schema

Make all mutable fields optional:

export const update{Entity}Schema = {entity}Schema
  .omit({
    id: true,           // Part of URL, not body
    createdBy: true,    // Immutable
    createdAt: true,    // Immutable
    updatedAt: true,    // Set by service/database
  })
  .partial();           // All fields optional for updates
export type Update{Entity}Type = z.infer<typeof update{Entity}Schema>;

Step 6: Define Query Parameters Schema (if needed)

Extend the base query params for filtering:

import { queryParamsSchema } from "./shared.schema";

export const {entity}QueryParamsSchema = queryParamsSchema.extend({
  // Entity-specific filters
  createdBy: userIdSchema.optional(),
  status: z.enum(["active", "inactive"]).optional(),
});
export type {Entity}QueryParamsType = z.infer<typeof {entity}QueryParamsSchema>;

Patterns & Rules

Naming Conventions

• File name: {entity-name}.schema.ts (singular, kebab-case)
• Schema variables: {entity}Schema, create{Entity}Schema (camelCase)
• Type names: {Entity}Type, Create{Entity}Type (PascalCase)

Import Rules

• Always use path aliases: import { x } from "@/schemas/..."
• Import shared schemas from ./shared.schema
• Import user-related schemas from ./user.schemas when needed

Schema Design Rules

1. Always export both schema and type for each definition
2. ID schemas are separate - allows reuse and type narrowing
3. Timestamps are optional on the base schema (not present on creation)
4. Create schemas omit system-managed fields (id, createdBy, timestamps)
5. Update schemas are partial - all fields optional
6. Extend base queryParamsSchema for entity-specific filters

Validation Guidelines

• Add .min(1) for required string fields in create schemas
• Use .optional() for truly optional fields
• Use z.coerce.number() for numeric query params (they come as strings)
• Add descriptive error messages: z.string().min(1, "Field is required")

Cross-Reference Pattern

When referencing other entities:

import { userIdSchema } from "./user.schemas";
import { otherEntityIdSchema } from "./other-entity.schema";

export const myEntitySchema = z.object({
  id: myEntityIdSchema,
  ownerId: userIdSchema, // Reference to user
  relatedId: otherEntityIdSchema, // Reference to another entity
});

Complete Example

See src/schemas/note.schema.ts for a complete reference implementation.

import { z } from "zod";
import { queryParamsSchema } from "./shared.schema";
import { userIdSchema } from "./user.schemas";

// ID Schema
export const noteIdSchema = z.string();
export type NoteIdType = z.infer<typeof noteIdSchema>;

// Base Entity Schema
export const noteSchema = z.object({
  id: noteIdSchema,
  content: z.string(),
  createdBy: userIdSchema,
  createdAt: z.date().optional(),
  updatedAt: z.date().optional(),
});
export type NoteType = z.infer<typeof noteSchema>;

// Create DTO
export const createNoteSchema = noteSchema
  .omit({
    id: true,
    createdBy: true,
    createdAt: true,
    updatedAt: true,
  })
  .extend({
    content: z.string().min(1, "Note content is required for creation."),
  });
export type CreateNoteType = z.infer<typeof createNoteSchema>;

// Update DTO
export const updateNoteSchema = noteSchema
  .omit({
    id: true,
    createdBy: true,
    createdAt: true,
    updatedAt: true,
  })
  .partial();
export type UpdateNoteType = z.infer<typeof updateNoteSchema>;

// Query Parameters
export const noteQueryParamsSchema = queryParamsSchema.extend({
  createdBy: userIdSchema.optional(),
});
export type NoteQueryParamsType = z.infer<typeof noteQueryParamsSchema>;

Shared Schemas Reference

The following are available from @/schemas/shared.schema:

• queryParamsSchema - Base pagination/sorting params (search, sortBy, sortOrder, page, limit)
• paginatedResultsSchema(dataSchema) - Generic paginated response wrapper
• entityIdParamSchema(paramName) - URL path parameter validation
• DEFAULT_PAGE, DEFAULT_LIMIT - Pagination defaults

What NOT to Do

• Do NOT use process.env - environment config belongs in src/env.ts
• Do NOT create barrel exports (index.ts) - use explicit imports
• Do NOT use plural names (notes.schema.ts) - use singular (note.schema.ts)
• Do NOT define business logic in schemas - schemas are for structure/validation only
• Do NOT skip type exports - always export both schema and inferred type