cli

TypeSpec Domain Modeling Guide

Complete guide to defining domain models using TypeSpec with code generation.

Philosophy

“Domain models are the single source of truth. TypeScript types are generated artifacts.”

TypeSpec-First Architecture ensures:

Type Safety - TypeScript types generated from canonical definitions
API Documentation - OpenAPI specs generated automatically
Contract Validation - JSON Schema for runtime validation
DRY Principle - Define once, use everywhere

TypeSpec Workflow

┌────────────────────────────────────────────────────────────────┐
│                                                                 │
│  1. Define TypeSpec models (tsp/*.tsp)                         │
│                                                                 │
│  2. Compile → Generate TypeScript + OpenAPI + JSON Schema      │
│     pnpm tsp:compile                                            │
│                                                                 │
│  3. Import generated types in application code                 │
│     import type { Settings } from '@/domain/generated/output'  │
│                                                                 │
│  4. Build TypeScript → Compile to JavaScript                   │
│     pnpm build                                                  │
│                                                                 │
│  5. Run tests → Verify types and behavior                      │
│     pnpm test                                                   │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

Project Structure

tsp/
├── main.tsp              # Entry point (imports all models)
├── common/               # Shared types
│   ├── base.tsp          # BaseEntity, SoftDeletableEntity, AuditableEntity
│   ├── scalars.tsp       # UUID scalar
│   ├── ask.tsp           # Askable interface pattern
│   └── enums/            # Shared enumerations
│       ├── lifecycle.tsp # SdlcLifecycle enum
│       ├── status.tsp    # TaskStatus enum
│       └── ...
├── domain/               # Domain layer models
│   ├── entities/         # One file per entity
│   │   ├── feature.tsp   # Feature entity
│   │   ├── task.tsp      # Task entity
│   │   ├── settings.tsp  # Settings entity
│   │   └── ...
│   └── value-objects/    # Embedded value objects
│       ├── gantt.tsp     # GanttChart value object
│       └── ...
├── agents/               # Agent system models
│   ├── analyze.tsp       # Analyze agent operations
│   ├── requirements.tsp  # Requirements agent operations
│   └── ...
└── deployment/           # Deployment configuration
    ├── target.tsp        # DeployTarget model
    ├── skill.tsp         # DeploySkill model
    └── ...

Generated Output

# After running: pnpm tsp:compile

apis/
├── openapi/
│   └── openapi.yaml      # OpenAPI 3.x spec (API documentation)
└── json-schema/          # JSON Schema files (one per model)
    ├── Feature.json
    ├── Task.json
    ├── Settings.json
    └── ...

src/domain/generated/
└── output.ts             # TypeScript types (DO NOT EDIT)

Creating a New Domain Model

Step 1: Define the TypeSpec Model

// tsp/domain/entities/settings.tsp
import "../common/base.tsp";
import "../common/enums/log-level.tsp";

/**
 * Global application settings (singleton).
 * Stored at ~/.shep/data as single SQLite record.
 */
model Settings extends BaseEntity {
  /** Singleton ID (always 'singleton') */
  id: "singleton";

  /** Model configuration for different agents */
  models: ModelConfiguration;

  /** User profile information (optional) */
  user: UserProfile;

  /** Environment configuration */
  environment: EnvironmentConfig;

  /** System configuration */
  system: SystemConfig;
}

/**
 * AI model configuration for different agents.
 */
model ModelConfiguration {
  /** Model for analyze agent (e.g., 'claude-opus-4') */
  analyze: string;

  /** Model for requirements agent */
  requirements: string;

  /** Model for plan agent */
  plan: string;

  /** Model for implementation agent */
  implement: string;
}

/**
 * User profile information.
 */
model UserProfile {
  /** User's full name */
  name?: string;

  /** User's email address */
  email?: string;

  /** GitHub username */
  githubUsername?: string;
}

/**
 * Environment configuration.
 */
model EnvironmentConfig {
  /** Default text editor (vim, nano, code, etc.) */
  defaultEditor: string;

  /** Preferred shell (bash, zsh, fish, etc.) */
  shellPreference: string;
}

/**
 * System configuration.
 */
model SystemConfig {
  /** Enable automatic updates */
  autoUpdate: boolean;

  /** Logging level */
  logLevel: LogLevel;
}

Step 2: Define Supporting Types

// tsp/common/enums/log-level.tsp

/**
 * Logging level for system output.
 */
enum LogLevel {
  /** Debug level logging (most verbose) */
  debug,

  /** Informational messages */
  info,

  /** Warning messages */
  warn,

  /** Error messages only */
  error,
}

Step 3: Extend Base Entity (if needed)

// tsp/common/base.tsp

/**
 * Base entity with ID and timestamps.
 * All entities should extend this model.
 */
model BaseEntity {
  /** Unique identifier */
  id: string;

  /** Creation timestamp */
  @encode(DateTimeKnownEncoding.rfc3339)
  createdAt: utcDateTime;

  /** Last update timestamp */
  @encode(DateTimeKnownEncoding.rfc3339)
  updatedAt: utcDateTime;
}

/**
 * Entity with soft delete support.
 */
model SoftDeletableEntity extends BaseEntity {
  /** Soft delete flag */
  isDeleted: boolean = false;

  /** Deletion timestamp (null if not deleted) */
  @encode(DateTimeKnownEncoding.rfc3339)
  deletedAt?: utcDateTime;
}

Step 4: Import in main.tsp

// tsp/main.tsp
import "@typespec/http";
import "@typespec/openapi3";

import "./common/base.tsp";
import "./common/scalars.tsp";
import "./common/ask.tsp";
import "./common/enums/lifecycle.tsp";
import "./common/enums/status.tsp";
import "./common/enums/log-level.tsp";

import "./domain/entities/feature.tsp";
import "./domain/entities/task.tsp";
import "./domain/entities/settings.tsp"; // NEW

import "./agents/analyze.tsp";
import "./agents/requirements.tsp";

@service({
  title: "Shep AI CLI - Domain Models",
})
namespace ShepAI;

Step 5: Compile and Generate Types

# Compile TypeSpec → Generate TypeScript + OpenAPI + JSON Schema
pnpm tsp:compile

# Verify generated output
cat src/domain/generated/output.ts | grep "export interface Settings"

Step 6: Use Generated Types in Code

// src/application/use-cases/settings/initialize-settings.use-case.ts
import type { Settings } from '@/domain/generated/output';
import type { ISettingsRepository } from '@/application/ports/output/settings.repository.interface';

export class InitializeSettingsUseCase {
  constructor(private readonly settingsRepository: ISettingsRepository) {}

  async execute(): Promise<Settings> {
    // Check if settings already exist
    const existing = await this.settingsRepository.load();
    if (existing !== null) {
      return existing;
    }

    // Create default settings (using generated type)
    const defaults: Settings = {
      id: 'singleton',
      createdAt: new Date(),
      updatedAt: new Date(),
      models: {
        analyze: 'claude-opus-4',
        requirements: 'claude-sonnet-4',
        plan: 'claude-sonnet-4',
        implement: 'claude-sonnet-4',
      },
      user: {},
      environment: {
        defaultEditor: 'vim',
        shellPreference: 'bash',
      },
      system: {
        autoUpdate: true,
        logLevel: 'info',
      },
    };

    // Initialize in repository
    await this.settingsRepository.initialize(defaults);

    return defaults;
  }
}

TypeSpec Best Practices

1. One Model Per File (SRP)

✅ Good: tsp/domain/entities/feature.tsp (one model)
✅ Good: tsp/domain/entities/task.tsp (one model)
❌ Bad:  tsp/domain/entities.tsp (all models in one file)

2. Use JSDoc Comments

/**
 * Feature entity tracking work through SDLC lifecycle.
 * Represents a unit of work from requirements to deployment.
 */
model Feature extends BaseEntity {
  /** Human-readable feature name */
  name: string;

  /** Detailed feature description */
  description: string;

  /** Current SDLC lifecycle phase */
  lifecycle: SdlcLifecycle;

  /** Repository path this feature belongs to */
  repoPath: string;
}

3. Use Enums for Fixed Sets

// Good: Enum for fixed set of values
enum SdlcLifecycle {
  Requirements,
  Plan,
  Implementation,
  Test,
  Deploy,
  Maintenance,
}

// Bad: String with no validation
model Feature {
  lifecycle: string; // Could be anything!
}

4. Use Optional Fields Appropriately

model UserProfile {
  // Optional fields with ?
  name?: string;
  email?: string;

  // Required field (no ?)
  createdAt: utcDateTime;
}

5. Extend Base Entities

// Good: Extend BaseEntity for consistency
model Settings extends BaseEntity {
  // Inherits: id, createdAt, updatedAt
  models: ModelConfiguration;
}

// Bad: Duplicate fields
model Settings {
  id: string;
  createdAt: utcDateTime; // Duplicate!
  updatedAt: utcDateTime; // Duplicate!
  models: ModelConfiguration;
}

TypeSpec Annotations

@encode - Date/Time Formatting

model BaseEntity {
  /** Creation timestamp (RFC 3339 format) */
  @encode(DateTimeKnownEncoding.rfc3339)
  createdAt: utcDateTime;
}

// Generated TypeScript:
// createdAt: string; (ISO 8601 string)

@deprecated - Mark Obsolete Fields

model LegacyFeature {
  name: string;

  /** @deprecated Use 'description' instead */
  @deprecated("Use 'description' instead")
  summary: string;

  description: string;
}

@example - Provide Examples

model Settings {
  /** Default text editor
   * @example "vim"
   * @example "code"
   */
  defaultEditor: string;
}

Modifying Existing Models

Adding a Field

// tsp/domain/entities/settings.tsp

model Settings extends BaseEntity {
  // ... existing fields ...

  /** NEW: Telemetry opt-out flag */
  telemetryEnabled: boolean = true; // Default value
}

Workflow:

Modify .tsp file
Run pnpm tsp:compile → Regenerate TypeScript
Update database migration (add column)
Update repository mapper (add field mapping)
Run tests → Fix compile errors
Commit both .tsp and generated files

Removing a Field (Breaking Change)

// tsp/domain/entities/settings.tsp

model Settings extends BaseEntity {
  // ... existing fields ...

  // REMOVED: oldField: string; ← Delete this line
}

Workflow:

Remove field from .tsp file
Run pnpm tsp:compile → TypeScript compile errors appear
Fix all references to removed field
Update database migration (remove column or mark deprecated)
Run tests → Ensure no broken references
Commit changes

Renaming a Field

// Before
model Settings {
  editorPreference: string;
}

// After
model Settings {
  defaultEditor: string;
}

Workflow:

Add new field with new name
Mark old field as @deprecated
Run pnpm tsp:compile
Migrate code to use new field
Create database migration (rename column or dual-write)
After migration period, remove deprecated field
Run pnpm tsp:compile again

TypeSpec Commands

# Compile TypeSpec → Generate TypeScript + OpenAPI + JSON Schema
pnpm tsp:compile

# Format TypeSpec files with Prettier
pnpm tsp:format

# Watch mode (recompile on changes)
pnpm tsp:watch

# Validate without generating (dry run)
pnpm tsp:compile --no-emit

# Generate only OpenAPI (skip TypeScript)
pnpm tsp:compile --emit @typespec/openapi3

# Validate TypeSpec + Lint + Format (full check)
pnpm validate

Troubleshooting

Error: “Duplicate identifier”

Cause: Model name conflicts with existing type.

Solution: Rename the model or use namespace:

namespace Settings {
  model Configuration {
    // ...
  }
}

Error: “Cannot find ‘@typespec/http’”

Cause: Missing TypeSpec dependencies.

Solution:

pnpm install @typespec/compiler @typespec/http @typespec/openapi3 --save-dev

Generated TypeScript Types Don’t Update

Cause: Cached compilation output.

Solution:

# Clear generated output
rm -rf apis/ src/domain/generated/

# Recompile
pnpm tsp:compile

TypeScript Compile Errors After TypeSpec Change

Cause: Breaking change in domain model (expected behavior).

Solution:

Let TypeScript show all compile errors
Fix each reference to match new type
Update tests to match new structure
This is intentional - type safety catches issues early!

Integration with CI/CD

TypeSpec compilation runs in CI pipeline:

# .github/workflows/ci.yml
jobs:
  lint:
    steps:
      - name: Compile TypeSpec
        run: pnpm tsp:compile

      - name: Check for uncommitted changes
        run: |
          git diff --exit-code src/domain/generated/

IMPORTANT: Always commit generated files (src/domain/generated/output.ts) to version control. This ensures:

CI can detect if someone manually edited generated files
Code reviews show generated type changes
Deployments don’t require TypeSpec toolchain

CLAUDE.md - TypeSpec architecture overview
tdd-guide.md - Testing TypeSpec-generated code
TypeSpec Official Docs - Language reference

Maintaining This Document

Update when:

New TypeSpec features are adopted
Generated output structure changes
New emitters are added (e.g., JSON Schema, Protobuf)

Related files:

tsp/ - TypeSpec source files
tspconfig.yaml - TypeSpec configuration
package.json - TypeSpec dependencies and scripts

This site is open source. Improve this page.

cli

TypeSpec Domain Modeling Guide

Philosophy

TypeSpec Workflow

Project Structure

Generated Output

Creating a New Domain Model

Step 1: Define the TypeSpec Model

Step 2: Define Supporting Types

Step 3: Extend Base Entity (if needed)

Step 4: Import in main.tsp

Step 5: Compile and Generate Types

Step 6: Use Generated Types in Code

TypeSpec Best Practices

1. One Model Per File (SRP)

2. Use JSDoc Comments

3. Use Enums for Fixed Sets

4. Use Optional Fields Appropriately

5. Extend Base Entities

TypeSpec Annotations

@encode - Date/Time Formatting

@deprecated - Mark Obsolete Fields

@example - Provide Examples

Modifying Existing Models

Adding a Field

Removing a Field (Breaking Change)

Renaming a Field

TypeSpec Commands

Troubleshooting

Error: “Duplicate identifier”

Error: “Cannot find ‘@typespec/http’”

Generated TypeScript Types Don’t Update

TypeScript Compile Errors After TypeSpec Change

Integration with CI/CD

Related Documentation

Maintaining This Document