Data Validation Schemas (Zod)
Relevant source files
The following files were used as context for generating this wiki page:
This project utilizes Zod as its primary data validation and type inference library. Schemas are centrally defined in the src/schemas/ directory and are used across the system to validate task payloads, API responses, and inter-service communication. By leveraging Zod, the project ensures type safety and runtime validation, particularly when dealing with background workers and AI agent interactions.
The primary architectural principle is the use of schemaTask from the Trigger.dev SDK, which enforces that incoming task payloads strictly adhere to the defined Zod schemas before execution. This prevents malformed data from entering the task pipeline and provides automatic TypeScript type inference for the payload object within task logic.
Sources: AGENTS.md:31, src/schemas/contentCreationSchema.ts:21, src/tasks/createContentTask.ts:38-40
Content Creation Schemas
The content creation module relies on a comprehensive schema to validate the parameters required for the social-ready video generation pipeline. This includes account identifiers, artist metadata, and media processing instructions such as upscaling and lipsyncing.
createContentPayloadSchema
This schema defines the input for the create-content task. It includes constraints on strings (minimum lengths) and URLs to ensure valid GitHub repository paths and image/audio source locations.
| Field | Type | Description | Constraints/Defaults |
|---|---|---|---|
accountId | string | Unique identifier for the account | min(1) |
artistSlug | string | URL-friendly identifier for the artist | min(1) |
template | string | Template used for video generation | min(1) |
lipsync | boolean | Whether to enable audio-to-video lipsyncing | default: false |
captionLength | enum | Controls generated text length: "short", "medium", "long" | default: "short" |
upscale | boolean | Enables 2x detail enhancement for media | default: false |
githubRepo | url | Repository for artist files (face-guide, songs) | Valid URL required |
songs | array<string> | Optional list of song slugs or public URLs | optional |
images | array<string> | Optional list of public image URLs for face guides | optional, must be URLs |
The diagram shows the structure of the content creation payload and its relationship with the CaptionLength enumeration.
Sources: src/schemas/contentCreationSchema.ts:3-21
AI Agent and Sandbox Schemas
Validation schemas for AI agents and sandbox environments ensure that commands executed in isolated Linux microVMs and feedback loops for coding agents are structured correctly.
Sandbox Execution Schemas
These schemas manage the execution of commands within Vercel Sandboxes and the resulting snapshots.
- runSandboxCommandPayloadSchema: Validates requests to run shell commands, including the working directory (
cwd) and arguments. - sandboxResultSchema: Captures the standard output, error, exit code, and the snapshot generated after execution.
Sources: src/schemas/sandboxSchema.ts:3-28
Coding Agent Feedback
The updatePRPayloadSchema is used when a human or system provides feedback to a coding agent regarding a specific Pull Request. It requires a snapshotId and branch to ensure the agent acts on the correct state of the codebase.
Sources: src/schemas/updatePRSchema.ts:3-9
This diagram illustrates the flow from request validation using Zod to the structured output of a sandbox execution.
Sources: src/schemas/sandboxSchema.ts:21-28, src/tasks/createContentTask.ts:38-42
Audio and Chat Configurations
Specialized schemas handle configuration for chat interactions and the structured output of AI-driven audio analysis.
Chat Schema
The chatSchema provides a consistent structure for tasks requiring LLM interactions. It includes optional fields for roomId, artistId, and specific model selection to allow for flexible but type-safe configurations.
Sources: src/schemas/chatSchema.ts:6-12
Audio Clip Analysis
The project uses structured AI outputs for analyzing song clips. The songClipSchema validates data identifying "best moments" in a song for social media content.
| Field | Type | Description |
|---|---|---|
startSeconds | number | The timestamp where the clip begins. |
lyrics | string | The text of the lyrics in the clip. |
mood | string | The emotional tone of the segment. |
relatability | number | A score from 1-10 indicating universal appeal. |
Sources: src/agents/createClipAnalysisAgent.ts:4-11
Conclusion
Data validation schemas in this project serve as the foundational contract between the Recoup API and its background tasks. By centralizing these definitions using Zod, the project achieves robust error handling, strictly typed development through z.infer, and reliable integration with external AI providers and sandbox environments.
Sources: README.md:50, AGENTS.md:31