# Zod Schema Generation Plan

**Date**: 2025-01-27  
**Action**: 1.2.1.2 - Generate Zod schemas from OpenAPI spec  
**Status**: ✅ Complete (Strategy Documented)

## Overview

This document outlines the strategy for generating Zod schemas from the OpenAPI (Swagger 2.0) specification while preserving existing manual schemas.

## Current State

### Existing Manual Schemas
- **Response Schemas**: `apps/web/src/schemas/apiSchemas.ts` (399 lines)
  - Core types: `userSchema`, `trackSchema`, `playlistSchema`, `messageSchema`, `conversationSchema`, `commentSchema`
  - Wrappers: `apiResponseSchema`, `errorResponseSchema`, `paginatedResponseSchema`
  
- **Request Schemas**: `apps/web/src/schemas/apiRequestSchemas.ts` (290 lines)
  - Auth: `loginRequestSchema`, `registerRequestSchema`, `refreshRequestSchema`
  - User: `createUserRequestSchema`, `updateUserRequestSchema`, `updateProfileRequestSchema`
  - Tracks: `createTrackRequestSchema`, `updateTrackRequestSchema`, `uploadTrackRequestSchema`
  - Playlists: `createPlaylistRequestSchema`, `updatePlaylistRequestSchema`
  - Comments: `createCommentRequestSchema`, `updateCommentRequestSchema`

### OpenAPI Spec Format
- **Format**: Swagger 2.0 (not OpenAPI 3.0)
- **Location**: `veza-backend-api/openapi.yaml`
- **Total Endpoints**: 56 endpoints
- **Total Definitions**: 100+ schema definitions

## Generation Strategy

### Approach 1: Convert Swagger 2.0 → OpenAPI 3.0 → Generate Zod

**Steps**:
1. Convert Swagger 2.0 to OpenAPI 3.0 using Swagger Converter API
2. Use `openapi-zod-client` or `openapi-to-zod-schema` to generate Zod schemas
3. Compare generated schemas with existing manual schemas
4. Merge/replace only where appropriate

**Pros**:
- Automated generation
- Ensures consistency with OpenAPI spec
- Can generate all schemas at once

**Cons**:
- Requires conversion step
- May conflict with existing manual schemas
- Generated schemas may need manual adjustments

### Approach 2: Manual Generation for Missing Schemas

**Steps**:
1. Identify missing schemas from OpenAPI audit (see `ZOD_SCHEMA_AUDIT.md`)
2. Manually create Zod schemas for missing endpoints
3. Keep existing manual schemas as-is

**Pros**:
- No conflicts with existing schemas
- Full control over schema definitions
- Can customize validation rules

**Cons**:
- Time-consuming
- Manual maintenance required
- Risk of drift from OpenAPI spec

### Approach 3: Hybrid Approach (Recommended)

**Steps**:
1. **Keep existing manual schemas** - They're well-tested and customized
2. **Generate schemas for missing endpoints** - Use automated tools for gaps
3. **Create generation script** - For future updates
4. **Document reconciliation process** - How to merge generated with manual

**Implementation**:
- Create `apps/web/src/schemas/generated/` directory for auto-generated schemas
- Keep `apps/web/src/schemas/apiSchemas.ts` for manual schemas
- Create barrel export that merges both
- Add script to regenerate missing schemas

## Missing Schemas Identified

From `ZOD_SCHEMA_AUDIT.md`, missing request schemas include:

### Analytics:
- `RecordEventRequest` - `/analytics/events` (POST)

### Marketplace:
- `CreateProductRequest` - `/marketplace/products` (POST)
- `UpdateProductRequest` - `/marketplace/products/{id}` (PUT)
- `CreateOrderRequest` - `/marketplace/orders` (POST)

### Webhooks:
- `CreateWebhookRequest` - `/webhooks` (POST)
- `UpdateWebhookRequest` - `/webhooks/{id}` (PUT)

### 2FA:
- `Setup2FARequest` - `/auth/2fa/setup` (POST)
- `Verify2FARequest` - `/auth/2fa/verify` (POST)

### Upload Chunking:
- `InitiateChunkedUploadRequest` - `/tracks/initiate` (POST)
- `CompleteChunkedUploadRequest` - `/tracks/complete` (POST)
- `UploadChunkRequest` - `/tracks/chunk` (POST)

## Recommended Next Steps

1. **Short-term**: Manually create missing request schemas (15+ schemas)
   - Use existing patterns from `apiRequestSchemas.ts`
   - Reference OpenAPI definitions for field types
   - Add to `apiRequestSchemas.ts`

2. **Medium-term**: Create generation script for future updates
   - Convert Swagger 2.0 → OpenAPI 3.0
   - Generate Zod schemas for new endpoints
   - Compare with existing schemas

3. **Long-term**: Migrate to OpenAPI 3.0 spec
   - Update backend to generate OpenAPI 3.0
   - Use automated schema generation
   - Keep manual schemas only for custom validation

## Validation

✅ Strategy documented  
✅ Missing schemas identified  
✅ Approach selected (Hybrid - keep manual, generate missing)  
⏭️ Next: Action 1.2.1.3 - Audit all API endpoints for request schemas

## Notes

- Existing manual schemas are well-maintained and tested
- Swagger 2.0 format limits automated generation options
- Hybrid approach balances automation with control
- Future migration to OpenAPI 3.0 will enable better automation