Agent Skills: TypeBox Schema Conventions

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. Use Value.Decode (not Value.Parse) to get the full pipeline: Default -> Convert -> Clean -> Assert. Value.Parse in TypeBox 1.1+ is strict and does not apply defaults or type coercion.

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.Decode(EnvSchema, {
  NODE_ENV: process.env.NODE_ENV,
  PORT: process.env.PORT,
  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