validate

import validate

Schema-based input validation for Zuri applications.

The validate module provides a fluent, chainable API for defining field-level validation rules, composing them into schemas, and checking arbitrary data dictionaries against those schemas.

Quick start

import validate

var schema = validate.schema({
  name:     validate.required().string().max_length(100),
  email:    validate.required().string().email(),
  age:      validate.required().integer().between(18, 120),
  website:  validate.string().url().sometimes(),
})

var result = schema.check({
  name:  'Ada Lovelace',
  email: 'ada@example.com',
  age:   36,
})

if result.valid {
  echo 'All good.'
} else {
  for err in result.errors {
    echo '${err.field}: ${err.message}'
  }
}

Rule chaining

Every top-level function returns a Validator instance. Rules are evaluated in the order they are chained. By default, evaluation stops at the first failing rule for each field (bail mode). Pass .bail(false) to collect all errors for a field.

# Collects every error for "password" rather than stopping at the first.
var rules = validate.schema({
  password: validate.required().string()
    .min_length(8)
    .regex('/[A-Z]/')
    .regex('/[0-9]/')
    .bail(false),
})

Optional fields

var rules = validate.schema({
  # bio is optional; when present it must be at most 500 chars.
  bio: validate.string().max_length(500).sometimes(),

  # nickname is optional and may be nil.
  nickname: validate.nullable().string().max_length(30).sometimes(),
})

Cross-field validation

var schema = validate.schema({
  password:              validate.required().string().min_length(8),
  password_confirmation: validate.required().string().confirmed(),
  role:                  validate.required().string().is_in(['user', 'admin']),
  admin_code:            validate.required_if('role', 'admin').string(),
})

required_if() (like the other conditional-requirement functions below) must come before .string() in the chain: see “Sequential Validation” further down for why the order here matters.

Nested fields (dot-notation)

var schema = validate.schema({
  'address.street':  validate.required().string(),
  'address.city':    validate.required().string(),
  'address.country': validate.required().string().length(2).uppercase(),
})

List items (wildcard)

var schema = validate.schema({
  'tags.*': validate.required().string().max_length(32).alpha_dash(),
})

Custom rules

Inline function:

var schema = validate.schema({
  code: validate.required().string().custom(@(value) {
    return value.starts_with('ZURI-') and value.length() == 12
  }, 'Must be a valid Zuri code (ZURI-XXXXXXX).')
})

Subclassing Rule:

import validate { Rule, Validator }

class Slug < Rule {
  validate(value) {
    if !is_string(value) return false
    return !!value.match('/^[a-z0-9]+(?:-[a-z0-9]+)*$/')
  }
  error() { return 'The ${self.name} field must be a valid slug.' }
}

var schema = validate.schema({
  slug: Validator().required().use(Slug),
})

Raising on failure

import validate { ValidationError }

def create_user(req, res) {
  catch {
    schema.check_or_raise(req.body)
  } as e

  if e {
    return res.json({ errors: schema.group_errors(e.errors) }, 422)
  }

  return res.json({ ok: true })
}

HTTP handler pattern

import http
import validate
import validate { ValidationError }

var create_user_schema = validate.schema({
  name:     validate.required().string().max_length(100),
  email:    validate.required().string().email(),
  password: validate.required().string().min_length(8),
  role:     validate.required().string().is_in(['user', 'admin']).sometimes(),
})

server.handle('POST', '/users', @(req, res) {
  catch {
    create_user_schema.check_or_raise(req.body)
  } as e

  if e {
    return res.json({ errors: create_user_schema.group_errors(e.errors) }, 422)
  }
  # ... create user
  res.json({ status: 'created' }, 201)
})

Sequential Validation

The validation mode is sequential, meaning that each field is validated in turn. This is the behavior you expect from a form submission. It is important to keep this in mind when using this module.

Consider the example below:

var schema = validate.schema({
  name: validate.required_if('age', 30).string().max_length(100),
  age:  validate.required().integer().between(18, 120),
})

If the age field is empty, the validation of name will not raise any error. This is because the required_if rule is only applied if the age field is 30 or greater and the entire chain exists before the next rule string().

However, if the validation rules were modified like this:

var schema = validate.schema({
  name: validate.string().required_if('age', 30).max_length(100),
  age:  validate.required().integer().between(18, 120),
})

Even when the age field is empty, the validation of name will raise an error if it is empty. This is because the string rule comes before the required_if rule.

With this behavior in mind, it is advised that optional rules such as sometimes, nullable, *_if, *_unless rules are applied early in the chain unless you absolutely want them to fail irrespective.

The validate API

Every public name in validate, wherever it is declared. Each links to the page that documents it.

Submodules

Functions

schema()

validate.schema(ruleset) -> Schema

Creates a new Schema from the given ruleset dictionary.

This is the primary entry point for defining a validation schema. Each key is a field name (supports dot-notation and .* wildcards) and each value must be a Validator instance.

import validate

var schema = validate.schema({
  username: validate.required().string().alpha_dash().max_length(30),
  email:    validate.required().string().email(),
})

Parameters

• ruleset (dict)

Returns Schema

Raises ArgumentError

Raises ValueError

2026, Richard Ore and The Zuri Contributors