zaggino/custom-format-validators

Custom Format Validators in z-schema

JSON Schema format constrains string (or other) values beyond basic type checking. z-schema includes built-in validators and supports registering custom ones — both sync and async.

Built-in formats

z-schema ships with validators for all standard JSON Schema formats:

| Format | Validates | | ----------------------- | ------------------------------------------- | | date | RFC 3339 full-date (2024-01-15) | | date-time | RFC 3339 date-time (2024-01-15T09:30:00Z) | | time | RFC 3339 time (09:30:00Z) | | email | RFC 5321 email address | | idn-email | Internationalized email | | hostname | RFC 1123 hostname | | idn-hostname | Internationalized hostname | | ipv4 | IPv4 address | | ipv6 | IPv6 address | | uri | RFC 3986 URI | | uri-reference | URI or relative reference | | uri-template | RFC 6570 URI template | | iri | Internationalized URI | | iri-reference | Internationalized URI reference | | json-pointer | RFC 6901 JSON Pointer | | relative-json-pointer | Relative JSON Pointer | | regex | ECMA-262 regex | | duration | ISO 8601 duration | | uuid | RFC 4122 UUID |

Registering a sync format

A format validator is a function (input: unknown) => boolean. Return true if valid, false if invalid. Return true for non-applicable types (e.g., when input is not a string) — z-schema calls format validators for any value type.

Global registration (shared across all instances)

import ZSchema from 'z-schema';

ZSchema.registerFormat('postal-code', (value) => {
  if (typeof value !== 'string') return true; // skip non-strings
  return /^\d{5}(-\d{4})?$/.test(value);
});

Instance-scoped registration

const validator = ZSchema.create();
validator.registerFormat('postal-code', (value) => {
  if (typeof value !== 'string') return true;
  return /^\d{5}(-\d{4})?$/.test(value);
});

Instance formats override global formats with the same name.

Via options at creation time

const validator = ZSchema.create({
  customFormats: {
    'postal-code': (value) => typeof value === 'string' && /^\d{5}(-\d{4})?$/.test(value),
    'always-valid': () => true,
    'disable-email': null, // disable the built-in email validator
  },
});

Pass null to disable a built-in or globally registered format.

Registering an async format

Return Promise<boolean>. The validator must be created with { async: true }.

const validator = ZSchema.create({ async: true });

validator.registerFormat('user-exists', async (value) => {
  if (typeof value !== 'number') return true;
  const user = await db.findUser(value);
  return user != null;
});

// Validate (returns Promise)
try {
  await validator.validate(data, schema);
} catch (err) {
  console.log(err.details);
}

Timeout

Async format validators time out after asyncTimeout milliseconds (default: 2000). Increase for slow operations:

const validator = ZSchema.create({
  async: true,
  asyncTimeout: 10000, // 10 seconds
});

Timed-out validators produce an ASYNC_TIMEOUT error.

Format assertion behavior across drafts

The JSON Schema spec changed how format works in newer drafts:

| Draft | Default behavior | With formatAssertions: true | | -------------- | ---------------------------------- | ----------------------------------------- | | draft-04/06/07 | Always asserts (fails on mismatch) | Always asserts | | draft-2019-09 | Always asserts (z-schema default) | Annotation-only unless vocabulary enabled | | draft-2020-12 | Always asserts (z-schema default) | Annotation-only unless vocabulary enabled |

z-schema defaults to formatAssertions: null (legacy — always assert). To respect the spec's vocabulary-aware behavior for modern drafts:

const validator = ZSchema.create({ formatAssertions: true });

To disable all format assertions (annotation-only):

const validator = ZSchema.create({ formatAssertions: false });

Unknown formats

By default, z-schema reports UNKNOWN_FORMAT for unrecognized format names in draft-04/06/07. Modern drafts (2019-09, 2020-12) always silently ignore unknown formats.

To suppress unknown format errors in older drafts:

const validator = ZSchema.create({ ignoreUnknownFormats: true });

Unregistering a format

// Global
ZSchema.unregisterFormat('postal-code');

// Instance
validator.unregisterFormat('postal-code');

Listing formats

// List globally registered custom formats
const customFormats = ZSchema.getRegisteredFormats();

// List all supported formats (built-in + custom) on an instance
const allFormats = validator.getSupportedFormats();

// Check if a specific format is supported
const supported = validator.isFormatSupported('postal-code');

Real-world patterns

Phone number validation

ZSchema.registerFormat('phone', (value) => {
  if (typeof value !== 'string') return true;
  return /^\+?[1-9]\d{1,14}$/.test(value); // E.164 format
});

ISO 8601 date (strict)

ZSchema.registerFormat('iso-date', (value) => {
  if (typeof value !== 'string') return true;
  const d = new Date(value);
  return !isNaN(d.getTime()) && value === d.toISOString().split('T')[0];
});

Business rule: value from external list

const validator = ZSchema.create({ async: true });

validator.registerFormat('valid-country', async (value) => {
  if (typeof value !== 'string') return true;
  const countries = await fetchValidCountries();
  return countries.includes(value.toUpperCase());
});

Side-effect: prefill defaults

Format validators can mutate objects (use with caution):

ZSchema.registerFormat('fill-defaults', (obj) => {
  if (typeof obj === 'object' && obj !== null) {
    (obj as Record<string, unknown>).createdAt ??= new Date().toISOString();
  }
  return true;
});

Schema usage

{
  "type": "object",
  "properties": {
    "phone": { "type": "string", "format": "phone" },
    "country": { "type": "string", "format": "valid-country" },
    "zipCode": { "type": "string", "format": "postal-code" }
  }
}