OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

Schema validation TypeScript

Generate TypeScript types from contracts and validate data at runtime with zero overhead.

Validation Pain Points

  • Runtime type validation is boilerplate-heavy
  • Type definitions drift from schemas
  • Validation logic scattered across codebase
  • Poor error messages for invalid data

Type-safe Solutions

  • Auto-generated TypeScript from contracts
  • Zod schemas for runtime validation
  • Type-safe validation with clear errors
  • Single source of schema truth

Contract Schema

Define data models with automatic TypeScript generation.

src/contracts/user.schema.ts
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';

export const UserSchema = new SchemaModel({
  type: 'object',
  properties: {
    id: {
      type: 'string',
      format: 'uuid',
      required: true,
      description: 'Unique user identifier',
    },
    email: {
      type: 'string',
      format: 'email',
      required: true,
      description: 'User email address',
    },
    name: {
      type: 'string',
      minLength: 1,
      maxLength: 100,
      required: true,
      description: 'Display name for the user',
    },
    role: {
      type: 'string',
      enum: ['user', 'admin', 'moderator'],
      default: 'user',
      description: 'User role in the system',
    },
    createdAt: {
      type: 'string',
      format: 'date-time',
      required: true,
      description: 'Account creation timestamp',
    },
  },
  required: ['id', 'email', 'name', 'createdAt'],
  metadata: {
    name: 'User',
    description: 'User account information',
  },
});

Generated Types

TypeScript types are automatically generated with proper validation.

generated/types/user.ts
// Auto-generated from UserSchema
export interface User {
  id: string;
  email: string;
  name: string;
  role: 'user' | 'admin' | 'moderator';
  createdAt: string;
}

// Auto-generated Zod schema for runtime validation
export const UserSchemaZod = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1).max(100),
  role: z.enum(['user', 'admin', 'moderator']).default('user'),
  createdAt: z.string().datetime(),
});

// Generated validation utilities
export function validateUser(data: unknown): User {
  return UserSchemaZod.parse(data);
}

export function isUser(data: unknown): data is User {
  return UserSchemaZod.safeParse(data).success;
}

Runtime Validation

Use generated validation in your API handlers with zero boilerplate.

src/handlers/user-handler.ts
import { validateUser } from '../generated/types/user';

export async function createUserHandler(request: Request) {
  try {
    const input = validateUser(await request.json());
    
    // input is now fully typed as User
    const user = await db.users.create({
      data: {
        ...input,
        createdAt: new Date().toISOString(),
      },
    });
    
    return Response.json({ user });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return Response.json(
        { 
          error: 'Validation failed',
          details: error.errors 
        },
        { status: 400 }
      );
    }
    
    throw error;
  }
}
Type Safety Guide Client Generation
OSS docsStart with OSS. Adopt Studio when you want the operating layer.

Why ContractSpec

Keep educational and comparison content reachable without letting it define the primary OSS learning path.

ManifestoContract-first APISpec-driven development