Schema Utility

The Schema utility provides a set of helper functions and predefined schemas for working with zod and @hono/zod-openapi. These utilities simplify the process of defining API request/response schemas and improve consistency in your API documentation.

jsonContent

The jsonContent function creates a standard OpenAPI content object for application/json payloads.

jsonContent(opts)

• opts (object):
  • schema (ZodType): The Zod schema describing the JSON payload.
  • description (string): A description of the content.
  • required (boolean, optional): Whether the content is required.

import { jsonContent, z } from '@venizia/ignis';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

const userResponse = {
  description: 'A single user object',
  ...jsonContent({ schema: UserSchema, description: 'User data' }),
};

jsonResponse

The jsonResponse function generates a standard OpenAPI response object that includes a success (200 OK) response and a default error response for 4xx | 5xx status codes. The error response uses the ErrorSchema.

jsonResponse(opts)

• opts (object):
  • schema (ZodType): The Zod schema for the success response body.
  • description (string, optional): A description for the success response. Defaults to 'Success Response'.
  • required (boolean, optional): Whether the content is required.
  • headers (Record<string, THeaderObject>, optional): Custom response headers to include in the success response.

import { jsonResponse, z } from '@venizia/ignis';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

this.defineRoute({
  configs: {
    path: '/',
    method: 'get',
    responses: jsonResponse({
      description: 'A single user object',
      schema: UserSchema,
    }),
  },
  // ...
});

// With custom headers
this.defineRoute({
  configs: {
    path: '/list',
    method: 'get',
    responses: jsonResponse({
      schema: z.array(UserSchema),
      description: 'User list',
      headers: {
        'x-total-count': {
          description: 'Total number of records',
          schema: { type: 'string', examples: ['100'] },
        },
      },
    }),
  },
  // ...
});

requiredString

This function creates a zod string schema that is non-empty (nonempty()) and can be further constrained by length.

requiredString(opts?)

• opts (object, optional):
  • min (number, optional): Minimum string length.
  • max (number, optional): Maximum string length.
  • fixed (number, optional): Exact string length (uses .length()).

import { requiredString } from '@venizia/ignis';

const schema = z.object({
  username: requiredString({ min: 3, max: 20 }),
  password: requiredString({ min: 8 }),
  countryCode: requiredString({ fixed: 2 }),
});

Predefined Schemas

• AnyObjectSchema: A flexible schema for any object (z.object().catchall(z.any())), with an OpenAPI description of 'Unknown schema'.

Type Utilities

import { TAnyObjectSchema, TInferSchema } from '@venizia/ignis';

// TAnyObjectSchema = z.ZodObject<z.ZodRawShape>
// TInferSchema<T> = z.infer<T> — infer TypeScript type from a Zod schema

type UserType = TInferSchema<typeof UserSchema>;

snakeToCamel

Transforms a Zod object shape from snake_case keys to camelCase. Uses .transform() and .pipe() to create a schema that accepts snake_case input but produces camelCase output.

import { snakeToCamel } from '@venizia/ignis';

const schema = snakeToCamel({
  first_name: z.string(),
  last_name: z.string(),
});

// Input: { first_name: 'John', last_name: 'Doe' }
// Output: { firstName: 'John', lastName: 'Doe' }

Custom ID Params

Use the idParamsSchema() helper to generate path parameter schemas for resource IDs:

idParamsSchema(opts?)

• opts (object, optional):
  • idType (string): 'number' (default) or 'string'.

import { idParamsSchema } from '@venizia/ignis';

this.defineRoute({
  configs: {
    path: '/{id}',
    method: 'get',
    request: {
      params: idParamsSchema({ idType: 'number' }),
    },
    // ...
  },
  handler: (c) => {
    const { id } = c.req.valid('param');
    // ...
  },
});