senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/apps/web/docs/ZOD_SCHEMA_GENERATION_PLAN.md
senke 377009bea5 api-contracts: document Zod schema generation strategy 
- Completed Action 1.2.1.2: Documented strategy for generating Zod schemas
- Created ZOD_SCHEMA_GENERATION_PLAN.md with hybrid approach
- Identified challenge: Swagger 2.0 format limits automated generation
- Strategy: Keep existing manual schemas, generate missing schemas manually
- Identified 15+ missing request schemas (analytics, marketplace, webhooks, 2FA, upload chunking)
- Recommended: Short-term manual creation, medium-term generation script, long-term OpenAPI 3.0 migration
2026-01-11 16:37:55 +01:00

4.7 KiB
Raw Blame History

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