| name | update-data-model |
| description | Add or modify domain entities in the data model using Zod schemas. Use when creating new entities, adding fields, changing relationships, or updating the domain model structure. |
Skill: Updating the Data Model
How to work with the domain model using Zod for schema validation and TypeScript for type definitions.
Model Architecture
One entity per file with Zod schemas:
model/
├── index.ts
├── enums.ts
├── User.ts
├── Job.ts
└── Site.ts
Key Principles
- Zod for validation (base schemas, no relationships)
- TypeScript interfaces for relationships (extend base types)
- Foreign keys end with
Id suffix
- Navigation properties use full entity names
- Circular references use
import() types
When to Use
- Adding new entities, fields, relationships
- Changing enums or validation rules
- Renaming fields or entities
Adding a New Entity
- Create
model/YourEntity.ts with BaseSchema, Schema, types, and interface with navigation properties
- Add enum to
model/enums.ts if needed
- Update
model/index.ts with exports
- Update related entities with inverse navigation properties
- Update
model/README.md Mermaid diagram
Adding a Field to an Existing Entity
- Update Base Schema
- TypeScript types auto-update
- Update mock data in handlers
- Update Storybook stories
Field Naming Conventions
| Type | Convention | Example |
|---|
| Foreign Key | entityNameId | userId, siteId |
| Navigation (1:1/many:1) | entityName | user, site |
| Navigation (1:many) | entityNames | jobs, submittedJobs |
| Enum | PascalCase | UserRole, JobStatus |
| Enum Values | SCREAMING_SNAKE_CASE | IN_PROGRESS |
Common Validation Patterns
z.string().email()
z.string().url()
z.string().min(1).max(255)
z.number().int().positive()
z.enum(['ACTIVE', 'INACTIVE'])
z.string().datetime()
z.array(z.string())
Common Mistakes
- ❌ Don't mix FK and navigation property names
- ❌ Don't add relationships to Zod schemas (use TS interfaces)
- ❌ Don't forget to update index.ts
- ❌ Don't forget to update mock data
Summary
- One entity per file, Zod for base fields, TS interfaces for relationships
- FK fields end with
Id, always update index.ts
- Update mock data and stories after changes
