Documentation

Everything you need to get started with schema-cast.

Installation

Install schema-cast globally to use the CLI from anywhere:

npm install -g schema-cast

Or add it as a dev dependency in your project:

npm install --save-dev schema-cast

Quick Start

1. Create a schema file in your project root:

user.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "type": "object",
  "x-schema-cast": {
    "tableName": "users"
  },
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "x-schema-cast": { "primaryKey": true }
    },
    "email": {
      "type": "string",
      "format": "email",
      "x-schema-cast": { "unique": true }
    },
    "role": {
      "type": "string",
      "enum": ["ADMIN", "USER"],
      "default": "USER"
    },
    "profile": {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" },
        "lastName": { "type": "string" }
      }
    }
  },
  "required": ["id", "email"]
}

2. Run the generate command:

schema-cast generate --input ./user.schema.json --out ./generated

3. That's it! You now have TypeScript types, Zod validators, a Mongoose model, and PostgreSQL DDL in your ./generated directory.

Schema Format

schema-cast accepts both JSON and YAML formats. Each schema file defines a single model:

schema.yaml

$schema: "https://json-schema.org/draft/2020-12/schema"
title: Product
type: object
x-schema-cast:
  tableName: products
properties:
  id:
    type: string
    format: uuid
    x-schema-cast:
      primaryKey: true
  title:
    type: string
  price:
    type: number
    minimum: 0
  tags:
    type: array
    items: 
      type: string
  status:
    type: string
    enum: [DRAFT, PUBLISHED, ARCHIVED]
required:
  - id
  - title

Supported Types

Type	Description	Options
string	Text field	min, max, regex, email, url
number	Numeric field	min, max, integer
boolean	True/false	—
uuid	Unique identifier	primary
enum	Fixed set of values	values: [...]
object	Nested structure	fields: {...}
array	List of items	items: {...}, min, max
date	ISO date/timestamp	default: "now"

CLI Reference

Generate

Generate all outputs from your schema files:

schema-cast generate --input ./schemas --out ./generated

Watch Mode

Auto-regenerate when schema files change:

schema-cast generate --input ./schemas --out ./generated --watch

Options

Flag	Description
--input, -i	Path to schema file or directory
--out, -o	Output directory for generated files
--watch, -w	Watch for file changes and regenerate
--format	Output format: ts, zod, mongoose, sql, all (default: all)
--dry-run	Preview output without writing files

Output Formats

Each schema generates four files. Here's what you get for a User schema:

User.types.tsTypeScript interface with full type safety

User.schema.tsZod validation schema for runtime checks

User.model.tsMongoose model with proper schema config

User.sqlPostgreSQL CREATE TABLE with constraints

Configuration

Create a schema-cast.config.json in your project root for persistent settings:

schema-cast.config.json

{
  "input": "./schemas",
  "output": "./src/generated",
  "formats": ["ts", "zod", "mongoose", "sql"],
  "watch": false,
  "typescript": {
    "exportType": "interface"
  },
  "sql": {
    "dialect": "postgresql",
    "snake_case": true
  }
}