Documentation

SchemaShift is a TypeScript CLI tool that migrates schemas between validation libraries using AST-based transformations. It preserves code structure, formatting, and comments while converting your schemas.

Getting Started

Installation

Install SchemaShift globally via npm:

npm install -g schemashift-cli

Or use npx to run without installing:

npx schemashift --help

Quick Start

Analyze your project to see what schemas you have:

schemashift analyze ./src

Preview migration changes with dry-run:

schemashift migrate ./src --from yup --to zod --dry-run

Run the migration:

schemashift migrate ./src --from yup --to zod

analyze

Scan your project and detect schema definitions across all supported libraries.

schemashift analyze <path> [options]

Example output:

Schema Analysis

Total files: 47
Files with schemas: 12
Total schemas: 34

Schemas by library:

  yup: 28
  zod: 6

migrate

Transform schemas from one library to another.

schemashift migrate <path> --from <library> --to <library> [options]

Examples:

# Basic migration
schemashift migrate ./src --from yup --to zod

# With HTML report
schemashift migrate ./src --from joi --to zod --report html

# Chain migration: Yup → Zod → Valibot
schemashift migrate ./src --chain yup->zod->valibot

# Cross-file with compatibility check
schemashift migrate ./src --from yup --to zod --cross-file --compat-check

# CI mode with risk threshold
schemashift migrate ./src --from yup --to zod --ci --fail-on-warnings --max-risk-score 50

watch

Watch files and automatically migrate on save. Requires Pro or Team license.

schemashift watch <path> --from <library> --to <library>

Press Ctrl+C to stop watching.

rollback

Restore files from a backup created during migration.

schemashift rollback [backupId] [options]

Examples:

# List all backups
schemashift rollback --list

# Restore most recent backup
schemashift rollback

# Restore specific backup
schemashift rollback backup-1706123456789

# Clean old backups
schemashift rollback --clean

license

Manage your license activation.

schemashift license [options]

Examples:

# Check current license status
schemashift license

# Activate a license
schemashift license --activate SCHEMASHIFT_PRO_xxxx-xxxx-xxxx

# Deactivate to move to another device
schemashift license --deactivate

pricing

Display pricing information and available tier features.

schemashift pricing

Shows a summary of all tiers, their prices, supported migrations, and key features.

init

Create a .schemashiftrc.json configuration file.

schemashift init [options]

compat

Check schema library compatibility before migration. Pro+

schemashift compat <path> [--json]

Detects installed library versions from package.json and reports known version-specific issues. For example, Zod v3's .errors property was renamed to .issues in v4, and z.record() now requires a key type argument.

# Check compatibility
schemashift compat ./src

# Machine-readable output
schemashift compat ./src --json

governance

Run schema governance checks against configurable rules. Team

schemashift governance <path> [options]

Enforces naming conventions, complexity limits, required validations, and more. See Governance Configuration for setup.

# Run governance checks
schemashift governance ./src

# Auto-fix violations
schemashift governance ./src --fix

# Preview auto-fixes without applying
schemashift governance ./src --fix-dry-run

# With custom config
schemashift governance ./src -c .schemashiftrc.json

graph

Export schema dependency graph in DOT or Mermaid format. Pro+

schemashift graph <path> [options]

Examples:

# Export Mermaid diagram to stdout
schemashift graph ./src

# Export DOT format to file
schemashift graph ./src --format dot --output schema-deps.dot

# Highlight circular dependencies with colors
schemashift graph ./src --highlight-circular --color

presets

List available migration presets for common scenarios. Individual+

schemashift presets [options]

Built-in Presets

Use a preset with the migrate command:

schemashift migrate ./src --preset react-hook-form-yup-to-zod

approvals

Manage migration approval workflows for shared codebases. Team

schemashift approvals [path] [options]

Examples:

# Create a migration request
schemashift approvals ./src --create --from yup --to zod

# List pending requests
schemashift approvals --list --status pending

# Approve a request
schemashift approvals --approve req-1706123456 --reviewer "Jane" --reason "LGTM"

# Reject a request
schemashift approvals --reject req-1706123456 --reviewer "Jane" --reason "Needs tests first"

doctor

Diagnose project health and suggest migrations. Free

schemashift doctor [path] [options]

The doctor command performs several health checks:

• Schema library detection — identifies Zod, Yup, Joi, Valibot, io-ts, and their versions from package.json
• Outdated version detection — flags Zod v3 when v4 is available, suggests Yup/Joi→Zod migration
• Form library compatibility — detects react-hook-form + yup and suggests resolver migration
• Ecosystem dependency checks — identifies drizzle-zod, tRPC, and other packages that may need updating
• Config validation — checks .schemashiftrc.json for issues
• Actionable suggestions — provides runnable SchemaShift commands based on detected state

Example output:

schemashift doctor

✓ package.json found
! Zod v3.22.0 detected — v4 available
✓ No form library issues
i Suggestion: schemashift migrate . -f zod-v3 -t v4

verify

Contract testing — verify migrated schemas match originals. Pro+

schemashift verify <path> -f <library> -t <library> [options]

The verify command:

1. Extracts schema names from source files (supports Zod, Yup, Joi, Valibot patterns)
2. Generates test samples (valid + invalid boundary data) based on schema structure
3. Validates samples through both source and target schemas
4. Reports parity score with detailed mismatch information

schemashift verify ./src -f yup -t zod --samples 100

compare

Side-by-side schema comparison showing how source maps to target. Individual+

schemashift compare <path> -f <library> -t <library> [--json]

hooks

Manage pre-commit hook integration for governance checks. Pro+

schemashift hooks <install|uninstall|status>

policy

Policy-as-code management for schema governance. Team

schemashift policy <init|check|list> [path]

Examples:

# Initialize policies from templates
schemashift policy init

# Check project against policies
schemashift policy check ./src

# List available governance templates
schemashift policy list

Yup → Zod

Available in: Free, Individual, Pro, Team

Transforms Yup schemas to Zod equivalents:

// Before (Yup)
import * as yup from 'yup';

const userSchema = yup.object({
  name: yup.string().required(),
  email: yup.string().email().required(),
  age: yup.number().positive().optional(),
});

// After (Zod)
import { z } from 'zod';

const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  age: z.number().positive().optional(),
});

Mapping Reference

Joi → Zod

Available in: Free, Individual, Pro, Team

// Before (Joi)
import Joi from 'joi';

const schema = Joi.object({
  username: Joi.string().alphanum().min(3).max(30).required(),
  email: Joi.string().email(),
  website: Joi.string().uri(),
});

// After (Zod)
import { z } from 'zod';

const schema = z.object({
  username: z.string().regex(/^[a-zA-Z0-9]+$/).min(3).max(30),
  email: z.string().email().optional(),
  website: z.string().url().optional(),
});

Mapping Reference

Zod v3 → v4

Available in: Individual, Pro, Team

Handles breaking changes between Zod v3 and v4:

// Before (Zod v3)
const schema = z.record(z.number());
const result = schema.safeParse(data);
if (!result.success) {
  console.log(result.error.errors);
}

// After (Zod v4)
const schema = z.record(z.string(), z.number());
const result = schema.safeParse(data);
if (!result.success) {
  console.log(result.error.issues);
}

Breaking Changes Handled

Zod v4 also delivers up to 14x faster parsing performance. See the Zod v4 changelog for the full list of changes.

io-ts → Zod

Available in: Pro, Team

// Before (io-ts)
import * as t from 'io-ts';

const User = t.type({
  name: t.string,
  age: t.number,
  email: t.union([t.string, t.undefined]),
});

// After (Zod)
import { z } from 'zod';

const User = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().optional(),
});

Zod ↔ Valibot

Available in: Pro, Team

Convert between Zod and Valibot schemas:

# Zod to Valibot
schemashift migrate ./src --from zod --to valibot

# Valibot to Zod
schemashift migrate ./src --from valibot --to zod

Key Mappings

Zod → Yup (Backward Migration)

Available in: Pro, Team

AST-based backward migration converting Zod schemas to Yup equivalents:

schemashift migrate ./src --from zod --to yup

// Before (Zod)
import { z } from 'zod';

const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  age: z.number().positive().optional(),
});

// After (Yup)
import * as yup from 'yup';

const userSchema = yup.object({
  name: yup.string().required(),
  email: yup.string().email().required(),
  age: yup.number().positive().notRequired(),
});

Valibot → Zod (Backward Migration)

Available in: Pro, Team

Text-based backward migration converting Valibot schemas to Zod:

schemashift migrate ./src --from valibot --to zod

// Before (Valibot)
import * as v from 'valibot';

const productSchema = v.object({
  name: v.pipe(v.string(), v.minLength(1)),
  price: v.pipe(v.number(), v.minValue(0)),
  status: v.picklist(['active', 'archived']),
});

// After (Zod)
import { z } from 'zod';

const productSchema = z.object({
  name: z.string().min(1),
  price: z.number().min(0),
  status: z.enum(['active', 'archived']),
});

Zod ↔ ArkType

Pro+

Bidirectional migration between Zod and ArkType. ArkType uses a string-based syntax that is fundamentally different from Zod's fluent API.

Zod ↔ Superstruct

Pro+

Bidirectional migration between Zod and Superstruct. Superstruct uses bare function calls without a namespace prefix.

io-ts → Effect Schema

Pro+

Migrate io-ts codecs to Effect Schema. This is the successor path for io-ts users since fp-ts merged into Effect.

fp-ts imports are automatically rewritten to Effect equivalents (e.g., pipe from effect/Function).

Type Helper Migration

SchemaShift automatically converts type inference helpers when migrating between libraries:

Form Library Compatibility

SchemaShift detects form library imports and warns you to update resolvers/adapters after migration:

Config File

Create .schemashiftrc.json in your project root:

{
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/*.d.ts",
    "**/*.test.ts"
  ],
  "backup": {
    "enabled": true,
    "dir": ".schemashift-backup"
  },
  "git": {
    "enabled": false,
    "createBranch": true,
    "branchPrefix": "schemashift/",
    "autoCommit": false,
    "commitMessage": "chore: migrate schemas with SchemaShift"
  },
  "customRules": []
}

Options

Custom Rules

Define custom transformation rules in your config:

{
  "customRules": [
    {
      "name": "company-validator",
      "match": "yup.string().companyId()",
      "replace": "z.string().regex(/^CMP-[0-9]+$/)"
    }
  ]
}

Governance Configuration

Configure schema governance rules in your config file (Team):

{
  "governance": {
    "rules": {
      "naming-convention": { "pattern": ".*Schema$" },
      "max-complexity": { "threshold": 80 },
      "no-any": {},
      "required-validations": {}
    },
    "failOnViolation": true
  }
}

Built-in rules:

Plugin Configuration

Load custom plugins from npm packages or local files (Team):

{
  "plugins": ["./my-plugin.js", "@my-org/schemashift-plugin"]
}

Plugins export a SchemaShiftPlugin interface with optional transform handlers and custom rules. See the GitHub repo for plugin development documentation.

Advanced Analysis

Analyze schema complexity and migration readiness (Individual+):

schemashift analyze ./src --detailed
schemashift analyze ./src --readiness yup->zod
schemashift analyze ./src --complexity --json

Complexity scoring considers chain length, nesting depth, and validation count. Scores are rated as low (0-25), medium (26-50), high (51-75), or critical (76-100).

Risk Scoring

Each migrated file receives a risk score based on warnings, errors, and manual review items (Individual+). Use --max-risk-score in CI to enforce quality thresholds:

schemashift migrate ./src --from yup --to zod --ci --max-risk-score 50

Export risk data for project tracking:

schemashift migrate ./src --from yup --to zod --report csv

Cross-File Resolution

Resolve schema imports across files and transform in dependency order (Pro+):

schemashift migrate ./src --from yup --to zod --cross-file

SchemaShift builds a dependency graph, detects circular dependencies, and applies transformations in topologically sorted order.

Chain Migrations

Perform multi-step migrations in a single command (Pro+):

schemashift migrate ./src --chain yup->zod->valibot

Each step validates intermediate output before proceeding. Combined reports include all steps. Use instead of --from / --to.

Ecosystem Detection

SchemaShift detects third-party packages in your project that may break or need updates during migration (Pro+):

When you run --compat-check, SchemaShift automatically scans your package.json for ecosystem dependencies and reports compatibility issues before migration begins.

# Run ecosystem detection as part of compat check
schemashift migrate ./src --from zod-v3 --to v4 --compat-check

# Or standalone compatibility check
schemashift compat ./src

Standard Schema

SchemaShift detects Standard Schema 1.0 compatible libraries in your project. This helps you understand interoperability options between schema libraries.

Compatible libraries include Zod v3.23+, Valibot v1+, ArkType v2+, @effect/schema, and TypeBox v0.34+. Detection is included in the analyze command output (FREE tier).

Form Resolver Migration

SchemaShift automatically rewrites form resolver imports during migration (Individual+):

For Formik and @mantine/form, TODO comments are added with guidance since those require manual adapter changes.

Complexity Estimation

Get pre-migration effort estimates before transforming any code (Individual+):

The complexity estimator analyzes your schema files and produces an effort level for each file: trivial, low, moderate, high, or extreme. It detects advanced patterns (branded types, recursive schemas, custom validators), performance risks, and provides risk area summaries.

TODO Resolution Summary

After migration, SchemaShift scans all generated TODO(schemashift) comments and produces a categorized summary (Free):

• branded-types — io-ts branded type patterns needing manual conversion
• io-ts-codecs — Codec/decoder patterns with Either monad handling
• fp-ts-patterns — Functional programming patterns from fp-ts
• form-migration — Form library adapter changes needed
• custom-validation — Custom validators requiring manual review
• manual-review — General patterns needing human judgment

Each category includes a resolution guide with specific steps to complete the migration.

Monorepo-Aware Migration

SchemaShift detects monorepo workspace configurations and suggests migration order (Pro+):

• Detects npm, Yarn, and pnpm workspaces from package.json
• Identifies which schema library each package uses
• Produces a topologically sorted migration order based on inter-package dependencies
• Ensures leaf packages migrate before dependents to prevent breakage

Behavioral Warnings

Detect behavioral differences between schema libraries before migration (Free):

schemashift analyze ./src --behavioral yup->zod

Identifies coercion differences (e.g., Yup auto-coerces strings to numbers, Zod does not), validation order changes, and error format differences. Warnings are grouped by category with severity levels to help you prepare for migration.

Bundle Size Estimation

Estimate the bundle size impact of switching schema libraries (Individual+):

schemashift analyze ./src --bundle zod->valibot

Compares minified+gzipped library sizes and reports the estimated delta in kB and percentage. Useful for understanding the size impact before committing to a migration.

Performance Impact Analysis

Identify potential performance changes from your migration (Individual+):

schemashift analyze ./src --performance zod-v3->v4

Reports validation speed differences, parse vs safeParse overhead, and runtime behavior impacts. Warnings are severity-rated (error, warning, info) with detailed explanations.

Type Deduplication Detection

Find structurally similar schema definitions across your codebase (Individual+):

schemashift analyze ./src --dedup

Identifies duplicate schemas with confidence scores. Clean up redundant definitions before or after migration to reduce maintenance burden.

Dead Schema Detection

Find schema definitions that are never referenced elsewhere in your codebase (Individual+):

schemashift analyze ./src --dedup

Scans for variable declarations that use schema library patterns (z., yup., Joi., etc.) and checks if those variables are referenced in other files or elsewhere in the same file. Exported schemas are considered "used" and won't be flagged. Reports the total schema count and a list of unused schemas with file paths and line numbers.

Import Deduplication

Detect duplicate import declarations from the same module within files (Free):

After migration, files may end up with multiple import statements from the same module — for example, two import { ... } from 'zod' lines. The import deduplicator detects these and suggests merged imports for cleaner code.

// Before (duplicate imports)
import { z } from 'zod';
import { ZodError } from 'zod';

// Suggested merge
import { z, ZodError } from 'zod';

Test Scaffolding

Generate validation test files after migration (Pro+):

schemashift migrate ./src --from yup --to zod --scaffold-tests

Creates test stubs for each migrated schema in .schemashift/tests/. Each test file includes basic validation checks to verify the migration preserved behavior.

Audit Logging

Record detailed migration history for compliance (Team):

schemashift migrate ./src --from yup --to zod --audit

Logs each file transform with timestamps, success/failure status, and warning counts. The audit log is persisted to .schemashift/audit-log.json for enterprise compliance and traceability. Enhanced with metadata collection (git commit, branch, CI provider), JSON/CSV export, and date range filtering.

Schema Drift Detection

Detect when schemas diverge from a saved baseline (Team):

The drift detector takes a snapshot of your schema state (file paths, content hashes, schema names) and saves it to .schemashift/schema-snapshot.json. Later, compare the current state against the snapshot to detect added, removed, and modified schema files.

Useful for compliance auditing, CI drift checks, and tracking schema evolution over time.

Governance Templates

Built-in governance rule templates for common policies (Team):

• no-any-schemas — disallow z.any(), yup.mixed(), Joi.any()
• require-descriptions — all schemas must have .describe()
• max-nesting-depth — limit schema nesting depth (configurable threshold)
• no-deprecated-methods — flag .deepPartial(), .strip(), .promise()
• naming-convention — enforce schema naming pattern (configurable regex)
• require-max-length — string schemas must include .max()

Access templates programmatically via getGovernanceTemplate(name), getGovernanceTemplateNames(), and getGovernanceTemplatesByCategory().

CI Reporting (SARIF/JUnit)

Machine-readable output formats for CI/CD pipelines (Pro+):

SARIF — Static Analysis Results Interchange Format for GitHub Code Scanning. Categorizes warnings into manual-review, behavioral-change, deprecated-pattern, and ecosystem-compatibility.

JUnit — XML test report format for CI systems (Jenkins, GitLab CI, etc.). Creates test suites per file with test cases per transform result.

Exit codes: 0 = success, 1 = failure, 2 = warnings (when --fail-on-warnings is enabled).

A reusable GitHub Action is also available at .github/actions/schemashift/action.yml for easy CI/CD pipeline integration. See GitHub Action below.

GitHub Action

A reusable GitHub Action for CI/CD pipeline integration (Pro+):

# .github/workflows/schema-migration.yml
name: Schema Migration
on: [push]
jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/schemashift
        with:
          command: migrate
          path: ./src
          from: yup
          to: zod
          license-key: ${{ secrets.SCHEMASHIFT_LICENSE_KEY }}
          extra-args: "--ci --report json"

Action Inputs

Action Outputs

Webhook Notifications

Send migration event notifications to external services (Team):

Configure webhooks in your .schemashiftrc.json to receive notifications when migration events occur:

{
  "webhooks": [
    {
      "url": "https://hooks.slack.com/services/T00/B00/xxxx",
      "events": ["migration_completed", "migration_failed"],
      "secret": "your-hmac-secret"
    },
    {
      "url": "https://your-api.com/webhooks/schemashift",
      "events": ["governance_violation", "drift_detected"],
      "headers": { "Authorization": "Bearer token" }
    }
  ]
}

Event Types

• migration_started — fired when a migration begins
• migration_completed — fired on successful migration
• migration_failed — fired when a migration fails
• governance_violation — fired when governance rules are violated
• drift_detected — fired when schema drift is detected

Webhook Type Formatting

Add a type field to automatically format payloads for specific platforms:

{
  "webhooks": [
    {
      "url": "https://hooks.slack.com/services/T00/B00/xxxx",
      "type": "slack",
      "events": ["migration_completed"]
    },
    {
      "url": "https://outlook.office.com/webhook/...",
      "type": "teams"
    }
  ]
}

• "slack" — sends Slack Block Kit format (header + section with fields + context)
• "teams" — sends Microsoft Teams Adaptive Card format (TextBlock + FactSet)
• "generic" (default) — sends raw event JSON payload

Webhook Options

Webhooks are signed with HMAC-SHA256 via the X-SchemaShift-Signature header when a secret is configured. Compatible with Slack, Microsoft Teams, Zapier, or any HTTP endpoint.

You can configure a custom timeout per webhook (default: 10 seconds):

{
  "url": "https://slow-api.example.com/webhook",
  "events": ["migration_completed"],
  "timeoutMs": 15000
}

Cross-Field Validation Helpers

Reusable .superRefine() code generators for common cross-field validation patterns (Pro+):

Use suggestCrossFieldPattern(whenCode) to analyze Yup .when() patterns and get a recommended Zod equivalent.

Enhanced .when() Migration

Smart Yup .when() analysis with generated Zod replacement code (Free):

The analyzeWhenPatterns() function detects the type of .when() condition and generates the appropriate Zod replacement:

• Boolean discriminator → z.discriminatedUnion()
• Enum discriminator → z.discriminatedUnion()
• Presence check → z.union() + .superRefine()
• Simple either/or → z.union()
• Complex condition → .superRefine() template

Instead of leaving a bare // TODO: handle .when(), SchemaShift generates working Zod code tailored to the specific pattern detected in your Yup schema.

Zod v4 Behavioral Test Generator

Detect silent v4 behavioral changes and generate regression test files (Pro+):

The behavioral test generator scans your Zod v3 code for 6 patterns where v4 silently changes behavior, then generates Vitest test files documenting the expected differences:

• .default() + .optional() — .default() always provides a value, making .optional() a no-op
• instanceof Error — ZodError no longer extends Error
• .transform() after .refine() — transforms now run even when refinements fail
• .catch() + .optional() — .catch() catches all issues
• Error message format changes
• .flatten() API changes

Tests are output to .schemashift/behavioral-tests/ and can be run with your existing test framework to verify v3 vs v4 behavior before committing.

Incremental Migration

Migrate large projects file-by-file with progress tracking (Pro+):

The incremental tracker persists state to .schemashift/incremental.json, allowing you to pause and resume migrations across sessions. Track completed, failed, and remaining files with percentage progress.

Package Updates

SchemaShift can plan and apply dependency changes to your package.json during migration:

• Adds the target library if not already installed (e.g., adds zod for yup→zod)
• Updates version ranges when needed (e.g., zod ^3.x → ^4.0.0 for v3→v4)
• Suggests removal of source libraries after migration (never auto-removes)
• Handles both dependencies and devDependencies

Schema Verification (Contract Testing)

Pro+

The schemashift verify command provides contract testing for migrated schemas, ensuring that target schemas produce the same validation behavior as source schemas.

• Schema extraction — identifies schema definitions from source code (Zod, Yup, Joi, Valibot patterns and exports)
• Sample generation — creates valid and invalid test data based on detected schema patterns (string, number, boolean, email, url, uuid, optional, nullable)
• Parity scoring — compares pass/fail results between source and target, reporting an overall parity score
• Mismatch reporting — details which samples produced different results and why

schemashift verify ./src -f yup -t zod --samples 100

Canary Migration

Pro+

Canary migration lets you migrate a percentage of files first, verify the results, then continue with the rest. This is especially useful for large codebases where you want to validate the migration approach before committing fully.

# Migrate 20% of files (simplest first)
schemashift migrate ./src -f yup -t zod --canary 20

# Verify, then continue with remaining files
schemashift migrate ./src -f yup -t zod

Files are selected by size (smallest/simplest first) using the IncrementalTracker. State is persisted so you can resume at any point.

Duration Estimation

Individual+

The complexity estimator now includes duration estimation, providing time range estimates based on the migration's effort level and file count:

Ranges scale with file count using a logarithmic factor. Duration is shown during migration when the tier allows complexity estimation.

Compliance Reports

Team

Generate compliance-ready reports from migration audit logs for regulated environments. Use the --compliance-report flag during migration:

schemashift migrate ./src -f yup -t zod --audit --compliance-report soc2

SOC2 Format

• Change Control Summary — total entries, success rate, date range
• Entry Details — change control IDs, timestamps, risk scores, warnings
• Rollback Procedure — backup verification and restore commands

HIPAA Format

• Data Transformation Summary — total entries, success rate, date range
• Integrity Verification — SHA-256 content hashes for each transformation
• Access Control — hostname, user, CI provider, job ID for each operation

CI/CD Templates

Pro+

Ready-to-use CI/CD pipeline templates are provided for multiple platforms, complementing the existing GitHub Action:

GitLab CI

Template at templates/gitlab-ci.yml includes:

• schemashift-migrate job with JUnit report artifacts
• schemashift-analyze job with JSON output
• schemashift-governance job for Team tier

# Include in your .gitlab-ci.yml
include:
  - local: templates/gitlab-ci.yml

Azure DevOps

Template at templates/azure-pipelines.yml includes:

• Analyze job with build artifact publishing
• Migrate job with JUnit test results integration

Pre-Commit Hooks

Pro+

Integrate governance checks into your git workflow. The hooks command automatically detects husky and lint-staged:

# Install hooks (auto-detects husky/lint-staged)
schemashift hooks install

# Check hook status
schemashift hooks status

# Remove hooks
schemashift hooks uninstall

Once installed, governance checks run automatically on pre-commit, catching schema violations before they reach your repository.

Policy-as-Code

Team

The policy command provides structured management of schema governance policies for your organization:

• schemashift policy init — generates a policy file from built-in governance templates
• schemashift policy check <path> — runs governance checks with active policies
• schemashift policy list — shows available governance templates grouped by category

Policies build on top of the existing governance engine, providing a more structured workflow for enforcing schema standards across teams.

Tiers & Features

View pricing and purchase →

Activation

After purchasing, you'll receive a license key via email. Activate it:

schemashift license --activate SCHEMASHIFT_PRO_xxxx-xxxx-xxxx

Your license is stored locally at ~/.config/schemashift/license.json.

Moving to Another Device

Deactivate on your current device first:

schemashift license --deactivate

Then activate on the new device with the same key.

CI/CD Setup

Requires Pro or Team license.

Set the SCHEMASHIFT_LICENSE_KEY environment variable in your CI platform:

GitHub Actions

name: Schema Migration Check

on: [push]

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm install -g schemashift-cli

      - name: Check for Yup schemas
        run: schemashift analyze ./src --json

      - name: Dry run migration
        env:
          SCHEMASHIFT_LICENSE_KEY: ${{ secrets.SCHEMASHIFT_LICENSE_KEY }}
        run: schemashift migrate ./src --from yup --to zod --dry-run --ci

GitLab CI

A ready-to-use template is available at templates/gitlab-ci.yml. Minimal example:

schema-check:
  image: node:22
  script:
    - npm install -g schemashift-cli
    - schemashift migrate ./src --from yup --to zod --dry-run --ci
  variables:
    SCHEMASHIFT_LICENSE_KEY: $SCHEMASHIFT_LICENSE_KEY
  artifacts:
    reports:
      junit: migration-report.xml

Azure DevOps

A ready-to-use template is available at templates/azure-pipelines.yml. Minimal example:

steps:
  - script: |
      npm install -g schemashift-cli
      schemashift migrate ./src --from yup --to zod --ci \
        --report junit --report-output $(Build.ArtifactStagingDirectory)/results.xml
    env:
      SCHEMASHIFT_LICENSE_KEY: $(SCHEMASHIFT_LICENSE_KEY)
  - task: PublishTestResults@2
    inputs:
      testResultsFiles: '$(Build.ArtifactStagingDirectory)/results.xml'

Troubleshooting

License activation fails

• Check your internet connection
• Verify the key is correct (no extra spaces)
• If you've hit the device limit, deactivate another device first

"Migration requires higher tier"

Some migration paths (io-ts, Zod↔Valibot, ArkType, Superstruct, Effect Schema) require paid tiers. Run schemashift pricing to see what's included in each tier. Yup→Zod and Joi→Zod are available in the Free tier.

"No handler for migration"

The requested migration path isn't supported. Supported paths:

• yup → zod
• joi → zod
• zod-v3 → v4
• io-ts → zod
• zod ↔ valibot
• zod → yup
• valibot → zod
• zod ↔ arktype
• zod ↔ superstruct
• io-ts → effect (Effect Schema)

Transformation produces incorrect code

1. Run with --dry-run first
2. Use schemashift rollback to restore from backup
3. Report the issue with the original code snippet

Offline usage

SchemaShift validates your license weekly. You can work offline for up to 7 days after the last successful validation.

Support

• Email: support@qwady.com
• Issues: Email with code samples for transformation bugs