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

OpenAPI alternative

A spec-first approach that goes beyond OpenAPI with executable contracts and code generation.

OpenAPI Limitations

  • OpenAPI is documentation-only

  • No type safety from OpenAPI specs

  • Manual SDK generation is complex

  • Cannot validate implementations against OpenAPI

ContractSpec Advantages

  • Executable contracts with validation

  • Generate multiple outputs from one spec

  • Type-safe by default

  • Built-in testing and validation

Comparison: OpenAPI vs ContractSpec

Key differences between OpenAPI documentation and ContractSpec executable contracts.

OpenAPI

  • • Documentation specification only

  • • No runtime validation

  • • Manual code generation

  • • Type safety requires tools

  • • Separate schemas from documentation

ContractSpec

  • • Executable contracts

  • • Built-in runtime validation

  • • Automatic code generation

  • • Type-safe by default

  • • Unified spec and implementation

Export from Contracts

Generate OpenAPI documentation from ContractSpec for existing tooling.

# From ContractSpec contracts
contractspec openapi export \
  --registry ./src/contracts/registry.ts \
  --format yaml \
  --out ./openapi.yaml

# Compare: Manual OpenAPI vs Generated
# Manual: Write OpenAPI by hand, maintain separately
# Generated: Single source of truth, always in sync

Beyond Documentation

ContractSpec provides more than just API documentation.

// One contract, multiple outputs
import { UserApiContract } from './contracts/user-api.contract';

// Generated outputs
export const outputs = {
  // API documentation (OpenAPI)
  openapi: UserApiContract.toOpenAPI(),
  
  // Client SDKs (TypeScript, Python, etc.)
  clients: UserApiContract.generateClients({
    languages: ['typescript', 'python', 'go'],
  }),
  
  // Database schemas (Prisma, Drizzle)
  database: UserApiContract.toDatabase({
    adapter: 'prisma',
  }),
  
  // API handlers (Express, Fastify, Next.js)
  handlers: UserApiContract.toHandlers({
    framework: 'express',
  }),
  
  // Validation middleware
  validation: UserApiContract.toValidation({
    library: 'zod',
  }),
  
  // Type definitions
  types: UserApiContract.toTypescript(),
};
Generate from Contracts 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