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

Spec-driven development

Build features by writing specifications first, then generate type-safe implementations.

Why Spec-driven?

  • Feature requirements are ambiguous
  • Frontend and backend implementations diverge
  • Testing lacks clear contract definitions
  • Code reviews focus on style instead of behavior

Benefits

  • Executable specifications as single source of truth
  • Generate type-safe clients from specs
  • Automated contract testing
  • Clear behavior contracts for teams

Feature Specification Example

Define a complete feature with operations, events, and data models.

src/contracts/user-management.feature.ts
import { defineFeature } from '@contractspec/lib.contracts-spec/features';
import { defineOperation } from '@contractspec/lib.contracts-spec/operations';
import { defineEvent } from '@contractspec/lib.contracts-spec/events';
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';

export const UserManagementFeature = defineFeature({
  goal: 'Complete user management system with CRUD operations',
  context: 'Handles user lifecycle from creation to deletion with proper authorization',
  operations: {
    createUser: defineOperation({
      goal: 'Create a new user account',
      input: new SchemaModel({
        type: 'object',
        properties: {
          email: { type: 'string', format: 'email', required: true },
          name: { type: 'string', minLength: 1, required: true },
        },
      }),
      output: new SchemaModel({
        type: 'object',
        properties: {
          id: { type: 'string', required: true },
          email: { type: 'string', required: true },
          name: { type: 'string', required: true },
        },
      }),
    }),
    updateUser: defineOperation({
      goal: 'Update existing user information',
      input: new SchemaModel({
        type: 'object',
        properties: {
          name: { type: 'string', minLength: 1 },
        },
      }),
      output: new SchemaModel({
        type: 'object',
        properties: {
          id: { type: 'string', required: true },
          email: { type: 'string', required: true },
          name: { type: 'string', required: true },
        },
      }),
    }),
  },
  events: {
    userCreated: defineEvent({
      goal: 'Emit when a new user is created',
      payload: new SchemaModel({
        type: 'object',
        properties: {
          userId: { type: 'string', required: true },
          email: { type: 'string', required: true },
        },
      }),
    }),
    userUpdated: defineEvent({
      goal: 'Emit when user information changes',
      payload: new SchemaModel({
        type: 'object',
        properties: {
          userId: { type: 'string', required: true },
          changes: { type: 'array', items: { type: 'string' }, required: true },
        },
      }),
    }),
  },
  metadata: {
    name: 'user-management',
    version: '1.0.0',
    description: 'Complete user management with operations and events',
  },
});

Generate Type-safe Implementations

Generate validation, types, and API handlers from your feature.

generate-from-feature
contractspec generate \
  --input ./src/contracts/user-management.feature.ts \
  --output ./generated/user-management
Type Safety Guide Deterministic Codegen
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