#schema-dsl API Reference

Use this as the complete public API reference after you understand the task-oriented guides. For a shorter route into the API surface, see API Overview.

#dsl / s Namespace

#Description

The main DSL namespace. s and dsl are the same function object: s === dsl. The callable form accepts string definitions and object definitions, while namespace factories provide a discoverable chain entry without maintaining a second grammar. Public examples use schema-dsl/pure + s as the default no-prototype-mutation entry.

#Syntax

s(definition: string | object): IDslBuilder | JSONSchema

s.email(): IDslBuilder
s.string(): IDslBuilder
s.number(): IDslBuilder

Because s === dsl, calling the shared object through either name remains compatible. The recommended documentation style is s({ ... }) for schema objects, s('...') for DSL seed builders, and s.xxx() for discoverable factory entry points. The dsl name remains a compatibility and semantic alias.

#Parameters

• definition (string | object) - DSL definition.
  • String input returns a DslBuilder instance for chainable calls.
  • Object input returns a JSON Schema object.

#Return Value

• DslBuilder / IDslBuilder - returned when the input is a string or namespace factory is used.
• Object - returned when the input is an object, as a JSON Schema.

#Example

import { s } from 'schema-dsl/pure';

// Plain DSL strings: shortest schema object
const schema = s({
  username: 'string:3-32!',
  email: 'email!'
});

// DSL seed: compact DSL plus builder chain methods
s('email!').label('email').pattern(/custom/);

// Factory form: strongest TypeScript method discovery
s.email().label('email').pattern(/custom/).require();

#Namespace Factories

Built-in factories are available on the shared s / dsl namespace:

Examples:

s('email!').label('Email')
s.email().label('Email').require()
s.array(s.string().require()).min(1)
s.enum('admin', 'user', 'guest')
s.type('tenant-id').require()

#DslBuilder Class

#Description

Schema builder class. It supports chainable methods for adding validation rules.

#Constructor

new DslBuilder(dslString: string)

Parameters:

• dslString (string) - DSL string, for example 'string:3-32!'.

#Methods

#Complete chain method surface

s('...'), callable namespace aliases, and namespace factories such as s.email() return a DslBuilder typed with the public IDslBuilder chain contract. Use s('email!') when you want compact DSL plus builder hints without relying on String prototype authoring, and use s.email() when you want the strongest TypeScript method discovery. Direct String chaining remains supported through String Extensions or transform, but it is no longer the default documentation entry. See Chain Method List for the complete method table and entry support.

Examples:

s('string').default('active')
s.string().default('active')
s.string().username('5-20').label('username').require()
s.number().min(18).max(120).precision(2).multiple(0.5)
s.object().strict().requireAll()
s.array(s.string().require()).min(1).noSparse().includesRequired(['admin'])
s.array({ name: 'string!', quantity: 'number:1-999!' }).min(1)

// Direct String chain compatibility path:
// runtime requires schema-dsl/register-string, compat/root, or compile-time transform;
// TypeScript declarations require schema-dsl/string-types.
'string'.default('active')

#.pattern(regex, message?)

Adds regular expression validation.

Parameters:

• regex (RegExp | string) - regular expression.
• message (string, optional) - custom error message.

Returns: DslBuilder

Example:

s('string:3-32!')
  .pattern(/^[a-zA-Z0-9_]+$/, 'Only letters, numbers, and underscores are allowed')

#.label(text)

Sets the field label used in error messages.

Parameters:

• text (string) - label text.

Returns: DslBuilder

Example:

s('email!').label('email address')

#.messages(messages)

Sets custom error messages.

Parameters:

• messages (Object) - error message map.
  • Key: error code, such as 'string.min'.
  • Value: error message template.

Returns: DslBuilder

Example:

s('string:3-32!')
  .messages({
    min: 'At least {{#limit}} characters',
    max: 'At most {{#limit}} characters'
  })

#.description(text)

Sets a field description.

Parameters:

• text (string) - description text.

Returns: DslBuilder

Example:

s('url').description('Personal website URL')

#.custom(validator)

Adds a custom validator.

Parameters:

• validator (Function) - validation function.
  • Signature: (value) => boolean | string | { error, message } | void
  • Return true to pass.
  • Return false, an error message string, or an error object to fail.
  • Synchronous validators are executed by both validate() and validateAsync(). Async validators that return Promise are executed only by validateAsync(). Calling validate() with a Promise-returning custom validator returns an explicit sync error.

Returns: DslBuilder

Example:

s('string:3-32!')
  .custom((value) => {
    if (value === 'admin') {
      return { error: 'username.exists', message: 'Username already exists' };
    }
  })

#.default(value)

Sets a default value.

Parameters:

• value (any) - default value.

Returns: DslBuilder

Example:

s('string').default('guest')

#.username(preset?)

Username validation. It automatically sets length and regular expression rules.

Parameters:

• preset (string | Object, optional) - preset config.
  • String: 'short' | 'medium' | 'long' | '5-20'
  • Object: { minLength, maxLength, allowUnderscore, allowNumber }
  • Default: 'medium', meaning 3-32 characters.

Returns: DslBuilder

Example:

// Default medium, 3-32 chars
s('string!').username()

// Custom range
s('string!').username('5-20')

// Preset
s('string!').username('short')  // 3-16 chars

#.password(strength?)

Password strength validation. It automatically sets length and regular expression rules.

Parameters:

• strength (string, optional) - strength level.
  • 'weak' - at least 6 characters
  • 'medium' - 8 characters, letters plus numbers, default
  • 'strong' - 8 characters, uppercase, lowercase, and numbers
  • 'veryStrong' - 10 characters, uppercase, lowercase, numbers, and special characters

Returns: DslBuilder

Example:

s('string!').password('strong')

#.phone(country?)

Phone number validation. It automatically sets length and regular expression rules.

Parameters:

• country (string, optional) - country code.
  • 'cn' - China, default
  • 'us' - United States
  • 'uk' - United Kingdom
  • 'hk' - Hong Kong
  • 'tw' - Taiwan
  • 'international' - international format

Returns: DslBuilder

Note: phone() only applies to string schemas. Use s('string!').phone('cn'); number schemas throw to avoid mixed numeric and string constraints.

Example:

// Recommended
s('string!').phone('cn')

#.toSchema()

Converts the builder to a JSON Schema object with internal schema-dsl markers.

Returns: Object - JSON Schema object including _required, _customMessages, _label, and other internal fields.

Example:

const schema = s('email!').label('email').toSchema();
// { type: 'string', format: 'email', _label: 'email', _required: true }

#.toJsonSchema() ^v1.2.5+

Converts the builder to a clean JSON Schema object without internal markers.

Unlike toSchema(), toJsonSchema() removes all schema-dsl internal markers:

• Underscore-prefixed fields: _required, _customMessages, _label, _customValidators, _whenConditions
• Custom validation keywords, which are removed directly: alphanum, lowercase, uppercase, trim, jsonString, port, requiredAll, strictSchema, noSparse, includesRequired, dateFormat, dateGreater, dateLess, precision
• exactLength special translation: it is not removed directly. It is converted to standard JSON Schema { minLength: N, maxLength: N }, matching the v1-compatible string:N behavior.

multipleOf is a standard JSON Schema field and is not removed. v2 fixed the incorrect v1 behavior here.

The returned object can be embedded directly in OpenAPI or standard JSON Schema documents without extra downstream cleanup.

Returns: Object - clean JSON Schema object.

Use cases:

• Generate OpenAPI documents
• Export to external systems
• Any scenario that needs standard JSON Schema

Example:

// Compare toSchema() and toJsonSchema()
const builder = s('string:3-32!').label('username').messages({ min: 'At least 3 chars' });

builder.toSchema();
// { type: 'string', minLength: 3, maxLength: 32, _required: true, _label: 'username', _customMessages: { min: 'At least 3 chars' } }

builder.toJsonSchema();
// { type: 'string', minLength: 3, maxLength: 32 }
// No _required, _label, _customMessages, or other internal fields.

// string:N syntax, exactLength -> minLength + maxLength
const exact = s('string:6!');
exact.toSchema();
// { type: 'string', exactLength: 6, _required: true }
exact.toJsonSchema();
// { type: 'string', minLength: 6, maxLength: 6 }
// exactLength is translated to standard JSON Schema minLength + maxLength.

// enum example
const enumBuilder = s('enum:admin,user,guest!');
enumBuilder.toJsonSchema();
// { type: 'string', enum: ['admin', 'user', 'guest'] }

// OpenAPI generation
const schema = s({
  username: 'string:3-32!',
  email: 'email!',
  age: 'number:0-120'
});
// Iterate fields and call toJsonSchema() to get standard JSON Schema.

#.validate(data)

Validates data with the builder convenience method.

Parameters:

• data (any) - data to validate.

Returns: Promise