API Request Body Validation Using t.Object from Elysia in OpenCut: A Complete Guide

OpenCut leverages Elysia's t.Object type helper to declaratively define request schemas in apps/api/src/index.ts, automatically validating JSON payloads and returning structured 400 errors for malformed input without manual error handling.

OpenCut's backend API relies on the lightweight Elysia framework to enforce strict type safety at the edge. By utilizing API request body validation using t.Object from Elysia, the application automatically guards against malformed input, ensuring that only properly structured data reaches the business logic layer.

How Elysia's t.Object Enables Declarative Validation

In apps/api/src/index.ts, the OpenCut API initializes an Elysia server instance that handles all HTTP routes. The framework's t.Object type helper allows developers to define expected payload shapes directly alongside route definitions. When a client sends a request to an endpoint like /echo, Elysia parses the incoming JSON and validates it against the declared schema before executing the route handler.

Basic Schema Definition in OpenCut

The simplest validation pattern involves passing a t.Object schema to the route's body option. For example, the /echo endpoint expects an object with a single string property.

// apps/api/src/index.ts
import { Elysia, t } from 'elysia';

const app = new Elysia()
  .post('/echo', ({ body }) => body, {
    body: t.Object({
      message: t.String()
    })
  });

Automatic Validation and Error Responses

When validation fails, Elysia automatically rejects the request with a 400 Bad Request status before the handler executes. The response includes a detailed errors array specifying which fields failed validation and why. This eliminates the need for manual try-catch blocks or custom validation middleware.

Handling Complex Nested Schemas

The t.Object helper supports deep nesting and composition with other type helpers like t.Number(), t.Boolean(), and t.Optional(). This enables complex domain object validation while maintaining type safety across the OpenCut API surface.

const createProjectSchema = t.Object({
  title: t.String(),
  description: t.Optional(t.String()),
  settings: t.Object({
    resolution: t.String(),
    framerate: t.Number()
  })
});

app.post('/project/create', ({ body }) => createProject(body), {
  body: createProjectSchema
});

Client-Side Error Handling

Clients receive structured error objects that map directly to schema violations. Each error entry includes a path array indicating the location of the invalid field and a message describing the expected type.

// Valid request
await fetch('https://api.opencut.app/echo', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Hello OpenCut!' })
})
.then(res => res.json());
// → { message: 'Hello OpenCut!' }

// Invalid request missing required field
await fetch('https://api.opencut.app/echo', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ text: 'Oops' })
})
.then(res => res.json());
// → { errors: [ { path: ['message'], message: 'Expected string' } ] }

Summary

• OpenCut uses Elysia's t.Object in apps/api/src/index.ts to define strict request schemas declaratively
• Validation occurs automatically, returning 400 Bad Request for malformed payloads without manual error handling
• Error responses include structured errors arrays with path and message properties for precise client feedback
• Schemas support nesting and composition with helpers like t.Optional(), t.Number(), and t.String()

Frequently Asked Questions

What happens if a request body doesn't match the t.Object schema in OpenCut?

Elysia automatically intercepts the request and returns a 400 Bad Request response. The response body contains an errors field detailing which specific properties failed validation and what types were expected instead.

Can t.Object schemas be reused across multiple routes in the OpenCut API?

Yes, schema definitions can be extracted into constant variables and shared across multiple endpoints. This ensures consistent validation logic throughout the application and reduces code duplication in apps/api/src/index.ts.

Does Elysia's t.Object support optional fields in request bodies?

The validation system supports optional properties through the t.Optional() wrapper. This allows fields like description to be omitted without triggering validation errors, while required fields remain mandatory.

Where is the validation logic implemented in the OpenCut repository?

All request validation schemas are defined within apps/api/src/index.ts, where the Elysia server instance configures routes with their corresponding t.Object body schemas according to the OpenCut source code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}