TypeBox Schema Conventions

This skill provides patterns for using TypeBox schemas in this repository.

Route Schemas (Fastify Context)

Use FastifyPluginAsyncTypebox for route plugins to get automatic TypeBox type inference:

import { type FastifyPluginAsyncTypebox, Type } from "@fastify/type-provider-typebox";

const routes: FastifyPluginAsyncTypebox = async (fastify) => {
  fastify.get(
    "/endpoint",
    {
      schema: {
        description: "Endpoint description",
        tags: ["tag-name"],
        summary: "Short summary",
        querystring: Type.Object({
          page: Type.Number({ minimum: 1, default: 1 }),
          limit: Type.Number({ minimum: 1, maximum: 100, default: 10 }),
        }),
        params: Type.Object({
          id: Type.String({ format: "uuid" }),
        }),
        body: Type.Object({
          name: Type.String({ minLength: 1, maxLength: 255 }),
          email: Type.String({ format: "email" }),
        }),
        response: {
          200: Type.Object({
            status: Type.Literal("ok"),
            data: Type.Array(Type.Object({
              id: Type.String(),
              name: Type.String(),
            })),
          }),
          400: Type.Object({
            message: Type.String(),
          }),
          404: Type.Object({
            message: Type.String(),
          }),
        },
      },
    },
    async (request, reply) => {
      return { status: "ok", data: [] };
    },
  );
};

export default routes;

Environment Validation (Pre-Fastify)

Use TypeBox standalone for environment validation before Fastify instance creation:

import Type from "typebox";
import Value from "typebox/value";

const EnvSchema = Type.Object({
  NODE_ENV: Type.Union(
    [
      Type.Literal("development"),
      Type.Literal("production"),
      Type.Literal("test"),
    ],
    { default: "development" },
  ),
  PORT: Type.Number({ default: 3000 }),
  HOST: Type.String({ default: "0.0.0.0" }),
  LOG_LEVEL: Type.Union(
    [
      Type.Literal("trace"),
      Type.Literal("debug"),
      Type.Literal("info"),
      Type.Literal("warn"),
      Type.Literal("error"),
      Type.Literal("fatal"),
    ],
    { default: "info" },
  ),
});

export const env = Value.Parse(EnvSchema, {
  NODE_ENV: process.env.NODE_ENV ?? "development",
  PORT: process.env.PORT ? Number(process.env.PORT) : undefined,
  HOST: process.env.HOST,
  LOG_LEVEL: process.env.LOG_LEVEL,
});

Import Conventions

// Route plugins - use FastifyPluginAsyncTypebox for automatic type inference
import { type FastifyPluginAsyncTypebox, Type } from "@fastify/type-provider-typebox";

// Environment validation - use standalone typebox package
import Type from "typebox";
import Value from "typebox/value";

// Do not use the direct @sinclair/typebox import
// import { Type } from "@sinclair/typebox";  // Do not use

Common Type Patterns

String Types

Type.String()                           // Any string
Type.String({ minLength: 1 })          // Non-empty string
Type.String({ format: "email" })       // Email format
Type.String({ format: "uuid" })        // UUID format
Type.String({ pattern: "^[a-z]+$" })   // Regex pattern
Type.Literal("value")                  // Exact string value

Number Types

Type.Number()                          // Any number
Type.Number({ minimum: 0 })            // Non-negative
Type.Number({ minimum: 1, maximum: 100 }) // Range
Type.Integer()                         // Integer only

Object Types

Type.Object({
  required: Type.String(),
  optional: Type.Optional(Type.String()),
})

Array Types

Type.Array(Type.String())              // Array of strings
Type.Array(Type.Object({ id: Type.String() })) // Array of objects
Type.Array(Type.String(), { minItems: 1 })     // Non-empty array

Union Types

Type.Union([
  Type.Literal("option1"),
  Type.Literal("option2"),
  Type.Literal("option3"),
])

With Defaults

Type.String({ default: "default-value" })
Type.Number({ default: 10 })
Type.Boolean({ default: false })

OpenAPI Integration

TypeBox schemas automatically generate OpenAPI documentation. Include:

• description on schema properties for documentation
• Appropriate format hints (email, uuid, date-time)
• Valid default values
• Proper constraints (minLength, maximum, etc.)

Type.Object({
  email: Type.String({
    format: "email",
    description: "User email address",
  }),
  createdAt: Type.String({
    format: "date-time",
    description: "ISO 8601 timestamp",
  }),
})

Testing TypeBox Schemas

Verify response shapes match schemas in tests:

it("should return response matching schema", async () => {
  const response = await fastify.inject({
    method: "GET",
    url: "/endpoint",
  });

  expect(response.statusCode).toBe(200);
  const body = response.json();

  // Verify structure matches schema
  expect(body).toHaveProperty("status", "ok");
  expect(body).toHaveProperty("data");
  expect(Array.isArray(body.data)).toBe(true);
});

Commands

cd app
npm run build       # TypeScript will validate schema types
npm run check       # Run Biome linter
npm run test        # Run tests

Boundaries

• Always use TypeBox for route schemas (not plain JSON Schema)
• Use the correct import for context (Fastify vs standalone)
• Do not use @sinclair/typebox directly