veza/apps/web/docs/ZOD_SCHEMA_AUDIT.md

Zod Schema Audit Report

Date: 2025-01-27
Action: 1.2.1.1 - Audit existing Zod schemas
Status: ✅ Complete

Overview

This document audits existing Zod schemas and identifies gaps compared to the OpenAPI specification.

Existing Schema Files

1. apps/web/src/schemas/apiSchemas.ts - Response schemas (399 lines)
2. apps/web/src/schemas/apiRequestSchemas.ts - Request schemas (290 lines)
3. apps/web/src/schemas/validation.ts - General validation utilities
4. apps/web/src/features/profile/schemas/profileSchema.ts - Profile-specific schemas
5. apps/web/src/features/settings/schemas/settingsSchema.ts - Settings-specific schemas

Response Schemas Found

Core Types:

• ✅ userSchema - User object schema
• ✅ trackSchema - Track object schema
• ✅ playlistSchema - Playlist object schema
• ✅ messageSchema - Chat message schema
• ✅ conversationSchema - Conversation schema
• ✅ commentSchema - Comment schema
• ✅ paginatedResponseSchema - Pagination wrapper

API Response Wrappers:

• ✅ apiResponseSchema - Base API response wrapper { success, data, error }
• ✅ errorResponseSchema - Error response schema

Request Schemas Found

Authentication:

• ✅ loginRequestSchema - Login credentials
• ✅ registerRequestSchema - User registration
• ✅ refreshRequestSchema - Token refresh

User Management:

• ✅ createUserRequestSchema - Create user
• ✅ updateUserRequestSchema - Update user
• ✅ updateProfileRequestSchema - Update profile

Chat:

• ✅ sendMessageRequestSchema - Send chat message
• ✅ createConversationRequestSchema - Create conversation

Tracks:

• ✅ createTrackRequestSchema - Create track
• ✅ updateTrackRequestSchema - Update track
• ✅ uploadTrackRequestSchema - Upload track file

Playlists:

• ✅ createPlaylistRequestSchema - Create playlist
• ✅ updatePlaylistRequestSchema - Update playlist
• ✅ addTrackToPlaylistRequestSchema - Add track to playlist

Comments:

• ✅ createCommentRequestSchema - Create comment
• ✅ updateCommentRequestSchema - Update comment

OpenAPI Endpoints Coverage

Total endpoints in OpenAPI spec: 56 endpoints

Endpoints with Schemas:

• ✅ /auth/login - loginRequestSchema
• ✅ /auth/register - registerRequestSchema
• ✅ /auth/refresh - refreshRequestSchema
• ✅ /tracks (POST) - createTrackRequestSchema
• ✅ /tracks/{id} (PUT) - updateTrackRequestSchema
• ✅ /playlists (POST) - createPlaylistRequestSchema
• ✅ /playlists/{id} (PUT) - updatePlaylistRequestSchema
• ✅ /tracks/{id}/comments (POST) - createCommentRequestSchema
• ✅ /comments/{id} (PUT) - updateCommentRequestSchema

Endpoints Missing Request Schemas:

• ⚠️ /analytics/events (POST) - RecordEventRequest
• ⚠️ /analytics/tracks/{id} (GET) - No request schema needed
• ⚠️ /analytics/tracks/top (GET) - Query params schema needed
• ⚠️ /tracks/batch/delete (POST) - BatchDeleteRequest
• ⚠️ /tracks/chunk (POST) - Chunk upload request
• ⚠️ /tracks/complete (POST) - Complete upload request
• ⚠️ /tracks/initiate (POST) - Initiate upload request
• ⚠️ /tracks/resume/{uploadId} (GET) - No request schema needed
• ⚠️ /tracks/quota/{id} (GET) - No request schema needed
• ⚠️ /playlists/{id}/tracks (POST) - addTrackToPlaylistRequestSchema exists
• ⚠️ /playlists/{id}/tracks/reorder (POST) - ReorderTracksRequest
• ⚠️ /webhooks (POST) - Webhook registration request
• ⚠️ /webhooks/{id}/regenerate-key (POST) - No request schema needed
• ⚠️ /webhooks/{id}/test (POST) - No request schema needed
• ⚠️ /auth/2fa/setup (POST) - Two-factor setup request
• ⚠️ /auth/2fa/verify (POST) - Two-factor verification request
• ⚠️ /auth/2fa/disable (POST) - Two-factor disable request
• ⚠️ /marketplace/products (POST) - CreateProductRequest
• ⚠️ /marketplace/products/{id} (PUT) - UpdateProductRequest
• ⚠️ /marketplace/orders (POST) - CreateOrderRequest
• ⚠️ /api/v1/logs/frontend (POST) - FrontendLogRequest

Response Schema Coverage

Response Types Covered:

• ✅ User responses - userSchema
• ✅ Track responses - trackSchema
• ✅ Playlist responses - playlistSchema
• ✅ Comment responses - commentSchema
• ✅ Paginated responses - paginatedResponseSchema
• ✅ API response wrapper - apiResponseSchema

Response Types Missing:

• ⚠️ Analytics responses - Analytics data structures
• ⚠️ Webhook responses - Webhook registration/management
• ⚠️ Marketplace responses - Product and Order types
• ⚠️ Two-factor responses - 2FA setup/verification responses
• ⚠️ Upload status responses - Track upload status types
• ⚠️ Search responses - Search result types

Schema Quality Assessment

Strengths:

1. ✅ Core types (User, Track, Playlist) are well-defined
2. ✅ Base schemas (UUID, dates) are reusable
3. ✅ Request validation covers main CRUD operations
4. ✅ Response wrapper schema exists

Gaps:

1. ⚠️ Missing schemas for analytics endpoints
2. ⚠️ Missing schemas for marketplace endpoints
3. ⚠️ Missing schemas for webhook endpoints
4. ⚠️ Missing schemas for 2FA endpoints
5. ⚠️ Missing schemas for upload chunking endpoints
6. ⚠️ Missing query parameter schemas for GET endpoints
7. ⚠️ Missing response schemas for specialized endpoints

Recommendations

Priority 1 (High):

1. Add request schemas for batch operations (batch delete, reorder)
2. Add request schemas for upload operations (initiate, chunk, complete)
3. Add request schemas for 2FA operations

Priority 2 (Medium):

1. Add request schemas for analytics endpoints
2. Add request schemas for marketplace endpoints
3. Add request schemas for webhook endpoints

Priority 3 (Low):

1. Add query parameter schemas for GET endpoints with filters
2. Add response schemas for specialized endpoints
3. Generate schemas automatically from OpenAPI spec

Next Steps

1. ✅ Action 1.2.1.1: Audit complete - This document
2. ⏭️ Action 1.2.1.2: Generate Zod schemas from OpenAPI spec (or manually add missing schemas)
3. ⏭️ Action 1.2.1.3: Audit all API endpoints for request schemas
4. ⏭️ Action 1.2.1.4: Add missing request validation schemas

Validation

✅ Audit complete - Found 20+ existing schemas, identified 15+ missing request schemas
✅ Core types well-covered (User, Track, Playlist)
⚠️ Specialized endpoints need schema coverage