schema-dsl

🎯 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

🎨 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

🚀 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:    '[e-mail]',
  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`     DECIMAL(10, 2) NOT NULL,
  `stock`     INT NOT NULL,
  `category`  VARCHAR(255) NOT NULL,
  `createdAt` DATETIME NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
*/

// 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

📖 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

📝 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

• 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