TypeBox, a JSON schema type builder

#opensource #pimono #json #typescript

In this article, we review TypeBox. You will learn:

What is TypeBox?
TypeBox usage in pi-mono codebase

What is TypeBox?

TypeBox is a JSON schema type builder with static type resolution for TypeScript. Below is an usage example:

import Type from 'typebox'

const T = Type.Object({                     // const T = {
  x: Type.Number(),                         //   type: 'object',
  y: Type.Number(),                         //   properties: {
  z: Type.Number()                          //     x: { type: 'number' },
})                                          //     y: { type: 'number' },
                                            //     z: { type: 'number' }
                                            //   },
                                            //   required: ['x', 'y', 'z']
                                            // }

type T = Type.Static<typeof T>              // type T = {
                                            //   x: number,
                                            //   y: number,
                                            //   z: number
                                            // }

TypeBox is a runtime type system that creates in-memory JSON Schema objects that infer as TypeScript types. The schematics produced by this library are designed to match the static type checking rules of the TypeScript compiler. TypeBox offers a unified type system that can be statically checked by TypeScript and validated at runtime using standard JSON Schema.

This library is designed to allow JSON Schema to compose similar to how types compose within TypeScript’s type system. It can be used as a simple tool to build up complex schematics or integrated into REST and RPC services to help validate data received over the wire.

Learn more about TypeBox.

TypeBox usage in pi-mono codebase

I found TypeBox references in pi-mono codebase. pi-mono is an AI agent toolkit providing coding agent CLI, unified LLM API, TUI & web UI libraries, Slack bot, vLLM pods

agent/types

In the agent/types.ts, I found some references:

...
import type { Static, TSchema } from "@sinclair/typebox";
...
/** Tool definition used by the agent runtime. */
export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
 /** Human-readable label for UI display. */
 label: string;
 /**
  * Optional compatibility shim for raw tool-call arguments before schema validation.
  * Must return an object that matches `TParameters`.
  */
 prepareArguments?: (args: unknown) => Static<TParameters>;
 /** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
 execute: (
  toolCallId: string,
  params: Static<TParameters>,
  signal?: AbortSignal,
  onUpdate?: AgentToolUpdateCallback<TDetails>,
 ) => Promise<AgentToolResult<TDetails>>;
}

coding-agent/core/extensions/types.ts

/**
 * Tool definition for registerTool().
 */
export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = any> {
 /** Tool name (used in LLM tool calls) */
 name: string;
 /** Human-readable label for UI */
 label: string;
 /** Description for LLM */
 description: string;
 /** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */
 promptSnippet?: string;
 /** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
 promptGuidelines?: string[];
 /** Parameter schema (TypeBox) */
 parameters: TParams;

 /** Optional compatibility shim to prepare raw tool call arguments before schema validation. Must return an object conforming to TParams. */
 prepareArguments?: (args: unknown) => Static<TParams>;

 /** Execute the tool. */
 execute(
  toolCallId: string,
  params: Static<TParams>,
  signal: AbortSignal | undefined,
  onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
  ctx: ExtensionContext,
 ): Promise<AgentToolResult<TDetails>>;

 /** Custom rendering for tool call display */
 renderCall?: (args: Static<TParams>, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>) => Component;

 /** Custom rendering for tool result display */
 renderResult?: (
  result: AgentToolResult<TDetails>,
  options: ToolRenderResultOptions,
  theme: Theme,
  context: ToolRenderContext<TState, Static<TParams>>,
 ) => Component;
}

TSchema here is a generic type.

About me:

Hey, my name is Ramu Narasinga. Email: ramu.narasinga@gmail.com

Tired of AI slop?

I spent 3+ years studying OSS codebases and wrote 350+ articles on what makes them production-grade. I built an open source tool that reviews your PR against your existing codebase patterns.

Your codebase. Your patterns. Enforced.

Get started for free — thinkthroo.com

DEV Community