🎯 schema-dsl

Declare field rules with the simplest DSL — let one schema drive validation, derivation, export, and documentation.

📚 Documentation: https://vextjs.github.io/schema-dsl

Quick Start · Documentation · Feature Overview · Examples

npm install schema-dsl

---

⚡ TL;DR (30-second intro)

What is schema-dsl?

Write field rules like this:

import { dsl, validate } from 'schema-dsl';

const userSchema = dsl({
  username: 'string:3-32!',
  email:    'email!',
  role:     'admin|user|guest',
  contact:  'types:email|phone'
});

const result = validate(userSchema, req.body);

Then that same set of rules continues to power:

• ✅ Sync / async validation — validate() / validateAsync()
• ✅ Schema derivation — pick / omit / partial to tailor schemas per endpoint
• ✅ Database schemas — export directly to MongoDB / MySQL / PostgreSQL
• ✅ Field documentation — auto-generate Markdown
• ✅ Unified error model — ValidationError + I18nError
• ✅ Internationalization — 5 built-in locales (zh-CN / en-US / ja-JP / es-ES / fr-FR), switchable at runtime

5-minute tutorial: Quick Start | Full docs: Online Documentation

---

🗺️ Documentation

Getting started:

• Quick Start — up and running in 5 minutes
• DSL Syntax Reference — syntax cheatsheet
• FAQ — common questions

Core features:

• validate() — synchronous validation API
• SchemaUtils — schema reuse
• Conditional Validation API — dsl.if / dsl.match
• Async Validation & Framework Integration — Express / Koa / Fastify
• Error Handling & i18n — error model

Export & integration:

• Export Guide — MongoDB / MySQL / PostgreSQL
• TypeScript Guide — type inference and usage
• Plugin System — custom extensions

Full docs: Online Documentation · Chinese Documentation · Feature Index

---

✨ Why schema-dsl?

🎯 Minimal DSL — 65% less code

❌ Traditional approach — verbose // Joi — requires 8 lines const schema = Joi.object({ username: Joi.string() .min(3).max(32).required(), email: Joi.string() .email().required(), age: Joi.number() .min(18).max(120) });

✅ schema-dsl — concise and clean // just 3 lines const schema = dsl({ username: 'string:3-32!', email: 'email!', age: 'number:18-120' });

💪 Full-featured

Feature	schema-dsl	Notes
Basic validation	✅	string, number, boolean, date, email, url, phone…
Advanced validation	✅	regex, custom functions, conditional branches, nested objects, arrays…
Cross-type union	✅	types:email|phone — one field accepts multiple types
Error messages	✅	auto-translated + custom messages + field labels
i18n business errors	✅	I18nError with numeric error codes
Database export	✅	MongoDB / MySQL / PostgreSQL schema generation
Documentation generation	✅	Markdown field docs auto-generated
TypeScript	✅	Written in native TypeScript with full type inference
Plugin system	✅	Custom types / formats / validators
Schema reuse	✅	pick / omit / partial / extend
Side-effect-controlled entries	✅	root compatibility, schema-dsl/pure for no String.prototype installation, and schema-dsl/runtime for isolated runtime state
Compile-time transform	✅	schema-dsl/transform core and optional schema-dsl/esbuild adapter

🎨 One schema, many uses (unique capability)

import { dsl, exporters, SchemaUtils } from 'schema-dsl';

const userSchema = dsl({
  id:        'uuid!',
  username:  'string:3-32!',
  email:     'email!',
  password:  'string:8-64!',
  age:       'number:18-120',
  createdAt: 'string!'
});

// 📋 derive scenario-specific schemas
const createSchema = SchemaUtils.omit(userSchema, ['id', 'createdAt']);
const updateSchema = SchemaUtils.partial(SchemaUtils.pick(userSchema, ['username', 'email']));
const publicSchema = SchemaUtils.omit(userSchema, ['password']);

// 🗄️ export the same schema to any database
const mongoSchema = new exporters.MongoDBExporter().export(userSchema);
const mysqlDDL    = new exporters.MySQLExporter().export('users', userSchema);
const pgDDL       = new exporters.PostgreSQLExporter().export('users', userSchema);

// 📝 generate field documentation from the same schema
const markdown = exporters.MarkdownExporter.export(userSchema, { title: 'User Field Reference' });

⚠️ SQL exporters only accept anyOf / oneOf when every branch resolves to the same SQL column type (for example ipv4 | ipv6). Ambiguous unions such as string | number now throw an explicit error instead of silently choosing the first branch.

---

📦 Installation

npm install schema-dsl

Runtime requirement: Node.js >= 18.0.0

---

📦 Package Entry Points

schema-dsl keeps the root import compatible with v1-style direct string chaining, and also exposes explicit entries for projects that want tighter control over global side effects.

Entry	Purpose
schema-dsl	Root compatibility entry; imports install the non-enumerable String chain API by default.
schema-dsl/pure	Same core API without installing String.prototype extensions. This controls prototype side effects only; it does not isolate Locale, TypeRegistry, PATTERNS or validator instances.
schema-dsl/compat	Explicit compatibility entry that installs String extensions on import.
schema-dsl/register-string	Side-effect entry for explicitly registering String extensions during application startup.
schema-dsl/string-types	Opt-in TypeScript declarations for String-chain authoring; no runtime prototype installation.
schema-dsl/transform	Babel AST transform core that rewrites static string-chain calls into dsl('...') calls.
schema-dsl/runtime	Runtime adapter factory for per-tenant/per-app isolated Locale messages, messageProvider, TypeRegistry scope, PATTERNS, Validator/AJV instances and I18nError creation.
schema-dsl/esbuild	Optional esbuild plugin adapter around the transform core. esbuild is an optional peer dependency.

import { dsl, validate } from 'schema-dsl/pure';
import 'schema-dsl/string-types';
import { transformSchemaDsl } from 'schema-dsl/transform';
import { schemaDslEsbuildPlugin } from 'schema-dsl/esbuild';
import { createRuntime } from 'schema-dsl/runtime';

const schema = dsl({ email: dsl('email!').label('Email').required() });

const transformed = transformSchemaDsl(
  'export const field = "admin|user|guest".label("Role")',
  { filename: 'schema.ts' }
);

const plugins = [schemaDslEsbuildPlugin()];

const tenantRuntime = createRuntime({
  locale: 'tenant-a',
  messages: {
    'tenant.user.missing': { code: 'TENANT_USER_MISSING', message: 'Tenant user {{#id}} is missing' }
  },
  types: {
    tenantId: { type: 'string', pattern: '^tenant_[a-z0-9]+$' }
  },
  messageProvider: ({ key, locale, fallback }) =>
    key === 'number.min' ? `[${locale}] {{#label}} must be >= {{#limit}}` : fallback
});

const tenantSchema = tenantRuntime.dsl({
  id: 'tenantId!',
  age: 'number:18-120'
});

const tenantResult = tenantRuntime.validate(tenantSchema, { id: 'tenant_demo', age: 16 });

The transform handles static DSL string literals, including naked pipe enums such as "admin|user|guest", and injects imports from schema-dsl/pure. By default it rewrites the complete built-in String-chain API (.label(), .pattern(), .required(), .toJsonSchema(), and the other methods installed by schema-dsl). Use additionalMethods for user-defined chain methods, and additionalTypes / additionalTypePatterns for registered custom DSL type literals such as "tenant-id!".label("Tenant"); methods remains a legacy replacement set when you intentionally want to override the built-in default list. Dynamic expressions, computed member calls, and already transformed dsl(...) calls are left unchanged.

Use schema-dsl/runtime when a framework needs independent runtime state per app, tenant, worker, or plugin host. createRuntime() keeps message lookup, per-call messageProvider, runtime custom types, pattern overrides, Validator/AJV caches, custom keyword messages, conditional branches, async custom validators, and createI18nError() inside that runtime instance. Use one runtime for the app/plugin lifecycle, pass request-level locale, messages, messageProvider or { coerce: false } via per-call options, and call configure(..., { mode: 'replace' | 'reset' }), clearCache(), getStats() or dispose() for hot reload and shutdown. The default root import and schema-dsl/pure remain compatible global APIs.

createSchemaDslRuntime() and createSchemaDslAdapter() are equivalent aliases of createRuntime() for adapter-oriented integrations.

---

🚀 Quick Start

1. Basic validation

import { dsl, validate } from 'schema-dsl';

const userSchema = dsl({
  username: 'string:3-32!',
  email:    'email!',
  age:      'number:18-120',
  role:     'admin|user|guest',
  tags:     'array<string>'
});

// ✅ validation passed
const result = validate(userSchema, {
  username: 'john_doe',
  email:    'john@example.com',
  age:      25,
  role:     'user',
  tags:     ['verified']
});

console.log(result.valid);   // true
console.log(result.data);    // validated data

// ❌ validation failed
const bad = validate(userSchema, { username: 'ab', email: 'not-email' });
console.log(bad.errors);
// [
//   { path: 'username', message: 'username must be at least 3 characters' },
//   { path: 'email',    message: 'email must be a valid email address' }
// ]

2. Async validation + Express integration

import { dsl, validateAsync, ValidationError } from 'schema-dsl';

const createUserSchema = dsl({
  username: 'string:3-32!',
  email:    'email!',
  password: 'string:8-32!'
});

app.post('/api/users', async (req, res, next) => {
  try {
    // throws ValidationError automatically on failure
    const validData = await validateAsync(createUserSchema, req.body);
    const user = await db.users.create(validData);
    res.json({ success: true, data: user });
  } catch (error) {
    next(error);
  }
});

// global error handler
app.use((error, req, res, next) => {
  if (error instanceof ValidationError) {
    return res.status(400).json({ success: false, errors: error.errors });
  }
  next(error);
});

3. Schema reuse (create / update / public)

import { dsl, SchemaUtils } from 'schema-dsl';

const userSchema = dsl({
  id:        'uuid!',
  username:  'string:3-32!',
  email:     'email!',
  password:  'string:8-64!',
  createdAt: 'string!'
});

// create endpoint: remove server-generated fields
const createSchema = SchemaUtils.omit(userSchema, ['id', 'createdAt']);

// update endpoint: pick editable fields, all optional
const updateSchema = SchemaUtils.partial(
  SchemaUtils.pick(userSchema, ['username', 'email'])
);

// public response: hide sensitive fields
const publicSchema = SchemaUtils.omit(userSchema, ['password']);

4. Database schema export

import { dsl, exporters } from 'schema-dsl';

const productSchema = dsl({
  name:      'string:1-100!',
  price:     'number:>0!',
  stock:     'integer:0-!',
  category:  'string!',
  createdAt: 'datetime!'
});

// MongoDB $jsonSchema (for db.createCollection() document validation; not a Mongoose model schema)
const mongoSchema = new exporters.MongoDBExporter().export(productSchema);
/*
{
  $jsonSchema: {
    bsonType: 'object',
    properties: {
      name:      { bsonType: 'string', minLength: 1, maxLength: 100 },
      price:     { bsonType: 'double', minimum: 0 },
      stock:     { bsonType: 'int',    minimum: 0 },
      category:  { bsonType: 'string' },
      createdAt: { bsonType: 'string' }
    },
    required: ['name', 'price', 'stock', 'category', 'createdAt']
  }
}
*/

// MySQL DDL
const mysqlDDL = new exporters.MySQLExporter().export('products', productSchema);
/*
CREATE TABLE `products` (
  `name`      VARCHAR(100) NOT NULL,
  `price`     DOUBLE NOT NULL,
  `stock`     BIGINT NOT NULL,
  `category`  VARCHAR(255) NOT NULL,
  `createdAt` DATETIME NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
*/

// Markdown field documentation
const markdown = exporters.MarkdownExporter.export(productSchema, { title: 'Product Field Reference' });

---

🗒️ Feature Overview

Common use cases

Use case	API	Docs
API parameter validation	validateAsync + ValidationError	Async Validation
Form / script validation	validate()	validate()
Batch data validation	SchemaUtils.validateBatch()	SchemaUtils
create / update derivation	pick / omit / partial	SchemaUtils
Database table creation	MongoDBExporter / MySQLExporter	Export Guide
Field documentation	MarkdownExporter	Export Guide
Multilingual API errors	I18nError	Error Handling
Conditional / dynamic rules	dsl.if() / dsl.match()	Conditional API
Custom type extensions	PluginManager	Plugin System
No global String extension	schema-dsl/pure	API Reference
Compile-time string-chain transform	transformSchemaDsl() / schemaDslEsbuildPlugin()	API Reference

---

📖 DSL Syntax Reference

Basic types

dsl({
  // string
  name:     'string!',         // required
  code:     'string:6',        // exact length 6
  bio:      'string:-500',     // max length 500
  username: 'string:3-32',     // length range 3–32

  // number
  age:   'number:18-120',      // range 18–120
  score: 'integer:0-100',      // integer 0–100
  price: 'number:>0',          // strictly greater than 0
  level: 'number:>=1',         // greater than or equal to 1

  // enum
  status: 'active|inactive|pending',  // string enum
  tier:   'enum:number:1|2|3',        // numeric enum

  // array
  tags:  'array<string>',             // string array
  items: 'array:1-10<number>',        // 1–10 numeric elements

  // boolean
  active: 'boolean!',

  // union type
  contact: 'types:email|phone!',      // email or phone, required
  price2:  'types:number:0-|string',  // number or string
})

Built-in formats

dsl({
  email:     'email!',          // email address
  website:   'url!',            // URL
  birthday:  'date!',           // YYYY-MM-DD
  createdAt: 'datetime!',       // ISO 8601
  userId:    'uuid!',           // UUID
  phone:     'phone:cn!',       // Chinese mobile number
  idCard:    'idCard:cn!',      // Chinese national ID
  slug:      'slug:3-100!',     // URL-friendly string
})

Fluent chain API (recommended for TypeScript)

import { dsl } from 'schema-dsl';

const schema = dsl({
  username: dsl('string:3-32!')
    .username()
    .label('username')
    .messages({ required: 'Username is required' }),

  email: dsl('email!').label('email address'),

  phone: dsl('string:11!')
    .pattern(/^1[3-9]\d{9}$/)
    .label('phone number'),
});

Conditional validation

// dsl.match — route to different rules based on a field value
const contactSchema = dsl({
  type:    'email|phone|wechat',
  contact: dsl.match('type', {
    email:  'email!',
    phone:  'string:11!',
    wechat: 'string:6-20!',
  })
});

// dsl.if — simple conditional branch
const orderSchema = dsl({
  isVip:    'boolean!',
  discount: dsl.if('isVip', 'number:10-50!', 'number:0-10')
});

// dsl.if chain assertion
dsl.if(d => !d.account)
  .message('Account not found')
  .and(d => d.account.balance < amount)
  .message('Insufficient balance')
  .assert(data);

---

🌍 Internationalization

import { dsl, validate, Locale, I18nError } from 'schema-dsl';

// built-in locales: zh-CN / en-US / ja-JP / es-ES / fr-FR (auto-loaded, no configuration needed)
const result = validate(schema, data, { locale: 'en-US' });
// error messages automatically use the specified locale

// register a custom locale
Locale.addLocale('zh-CN', {
  'user.notFound':    'User not found',
  'user.forbidden':   { code: 40003, message: 'Access forbidden' },
});

// throw i18n business errors
I18nError.assert(user, 'user.notFound');                    // auto-throw when user is falsy
I18nError.throw('user.forbidden', {}, 403);                 // throw directly
I18nError.assert(ok, 'user.notFound', {}, 404, locale);     // specify locale at runtime

// errors carry a numeric code; frontend can branch on it
try {
  await api.getUser(id);
} catch (error) {
  switch (error.code) {
    case 40003: showForbiddenPage(); break;
  }
}

---

🔌 Plugin System

import { PluginManager, Validator, dsl } from 'schema-dsl';

const pluginManager = new PluginManager();

// register a custom format plugin (must provide an install function)
pluginManager.register({
  name: 'extra-formats',
  install(core) {
    const validator = core as Validator;
    // register custom formats on the Validator instance via addFormat
    validator.addFormat('hex-color', {
      validate: (v: string) => /^#[0-9A-F]{6}$/i.test(v)
    });
    validator.addFormat('mac-address', {
      validate: (v: string) => /^([0-9A-F]{2}:){5}[0-9A-F]{2}$/i.test(v)
    });
  }
});

// create a Validator and install plugins
const validator = new Validator();
pluginManager.install(validator);

// use the custom formats in a schema
const schema = dsl({ color: 'hex-color!', mac: 'mac-address' });
const result = validator.validate(schema, { color: '#FF5733', mac: '00:1A:2B:3C:4D:5E' });

---

🔧 Core API Reference

API	Purpose	Returns	Docs
dsl(schema)	Create a schema	Schema object	DSL Syntax
validate(schema, data)	Synchronous validation	{ valid, errors, data }	validate()
validateAsync(schema, data)	Asynchronous validation	Promise (throws on failure)	Async Validation
SchemaUtils.pick()	Select fields	New schema	SchemaUtils
SchemaUtils.omit()	Exclude fields	New schema	SchemaUtils
SchemaUtils.partial()	Make all fields optional	New schema	SchemaUtils
dsl.if(condition)	Conditional validation	ConditionalBuilder	Conditional API
dsl.match(field, map)	Branch validation	ConditionalBuilder	Conditional API
I18nError.throw()	Throw an i18n error	never	Error Handling
I18nError.assert()	Assert then throw	void	Error Handling
schema-dsl/pure	Import the API without installing String extensions	API namespace	API Reference
schema-dsl/string-types	Opt into TypeScript hints for String-chain authoring	Type declarations	TypeScript Usage
transformSchemaDsl()	Rewrite static string-chain DSL calls at compile time	{ code, changed, warnings }	API Reference
schemaDslEsbuildPlugin()	Use the transform in esbuild build/context flows	esbuild plugin	API Reference

---

📝 TypeScript Usage

import { dsl, validateAsync, ValidationError } from 'schema-dsl';

// ✅ wrap strings with dsl() in TypeScript for full type inference
const userSchema = dsl({
  username: dsl('string:3-32!').label('username'),
  email:    dsl('email!').label('email'),
  age:      dsl('number:18-100').label('age')
});

try {
  const validData = await validateAsync(userSchema, payload);
  // validData has full type inference
} catch (error) {
  if (error instanceof ValidationError) {
    error.errors.forEach(e => console.log(`${e.path}: ${e.message}`));
  }
}

Note: In TypeScript projects, wrap strings with dsl('...') to get type inference. In JavaScript projects you can pass strings directly. See the TypeScript Guide for details.

---

🛠️ Development

npm run build      # compile TypeScript
npm run test       # run tests
npm run typecheck  # type check

Local documentation preview:

cd website
npm run dev

---

🤝 Contributing

git clone https://github.com/vextjs/schema-dsl.git
cd schema-dsl
npm install
npm test

See CONTRIBUTING.md for details.

---

🔗 Links

📖 Core documentation

• Quick Start — up and running in 5 minutes
• DSL Syntax Guide — complete syntax reference
• validate() — synchronous validation API
• API Reference — complete API docs
• TypeScript Guide — required reading for TS users
• Best Practices — avoid common pitfalls
• Troubleshooting — diagnosing issues

🎯 Feature documentation

• SchemaUtils
• Conditional Validation API
• Async Validation
• Error Handling & i18n
• Union Types
• Enum Types

🗄️ Export & integration

• Export Guide
• MongoDB Exporter
• MySQL Exporter
• PostgreSQL Exporter
• Markdown Exporter
• ⚠️ Export Limitations

💻 Examples

• Run all documentation examples with npm run examples:run.
• quick-start.ts — basic usage and registration form
• validate-async.ts — async validation and ValidationError handling
• export-guide.ts — database export overview
• error-handling.ts — field errors and business error handling
• plugin-system.ts — plugin system and hooks

📝 Changelog & contributing

• Changelog
• Contributing Guide
• Security Policy

---

📄 License

Apache-2.0

---

If this project is useful to you, please consider giving it a Star ⭐

Made with ❤️ by the schema-dsl team