gs-zod-validation_skill

Overview

This skill guides building Zod validation schemas within a Clean Architecture setup. It clarifies that Zod should validate input shape, format, and basic constraints in the Presentation layer, while business rules belong in Entity.validate() or the Use Case layer. It also shows schema placement, common validators, error handling, and detection commands for anti-patterns.

How this skill works

The guide defines a clear separation of concerns: Zod schemas live in feature-specific schemas files and only assert shape, types, and simple constraints. Business invariants and domain rules are implemented inside domain entities or use cases. It includes examples for schema structure, common validators, server-action usage, and patterns to avoid (like .refine for business logic).

When to use it

• When creating input schemas for server actions or API endpoints
• When you need to enforce input shape, formats, and basic constraints
• When organizing feature code under src/features/<feature>/schemas/
• When you want consistent client-side and server-side input validation
• When separating domain rules from presentation concerns

Best practices

• Keep Zod schemas limited to shape, format, and simple constraints (min/max, email, IDs)
• Implement business rules and invariants inside Entity.validate() or domain services
• Put cross-entity or async checks in Use Case layer, not in Zod (no DB calls in schemas)
• Store schemas in src/features/<feature>/schemas/ and export input types with z.infer
• Use detection grep commands to find .refine/.superRefine and move logic to domain

Example use cases

• CreateCategorySchema to validate name and description shape before use case execution
• ListCategoriesSchema to coerce and constrain pagination and filters
• Server action that calls .input(CreateSchema) to validate shape before handler
• Entity.validate() that enforces unique-name or status-transition rules
• Use Case that performs cross-entity or database existence checks