VALIDATORS.md

Validation System Documentation

The Schema Form Engine includes a powerful, metadata-driven validation system. Validators are pure functions that can be composed using a string-based syntax or defined as complex objects within your schema.

🚀 Key Concepts

• Rule String Syntax: required|email|min:5 (Quick & easy)
• Object Syntax: Used for complex validation with specific options.
• Engine Gating: The Form Engine prevents submission if any field fails validation.
• Localization: All error messages are fully localizable via vue-i18n.

📚 Available Validators

The following validators are available out-of-the-box. Each rule can be used in the rules property of your schema field.

Rule	Syntax Example	Description	Options
Required	required	Field must have a value (not null, undefined, or empty string/array).	None
Email	email	Must be a valid email address format.	None
Min Length	minLength:5	String or array must have at least min items/characters.	min (number)
Max Length	maxLength:255	String or array must have at most max items/characters.	max (number)
Alpha	alpha	Only alphabetic characters allowed (a-z, A-Z).	None
Alpha Dash	alphaDash	Alpha characters, dashes, and underscores allowed.	None
Alpha Numeric	alphaNumeric	Alpha characters and numbers allowed.	None
Numeric	numeric	Must be a valid numeric value (string or number).	None
Integer	integer	Must be an integer (no decimals).	None
Between	between:1,10	Number must be between min and max (inclusive).	min, max (numbers)
Digits Between	digitsBetween:3,5	String must be numeric and have length between min/max.	min, max (numbers)
Min Value	minValue:18	Numeric value must be at least value.	value (number)
Max Value	maxValue:100	Numeric value must be at most value.	value (number)
Regex	regex:^A.*$	Value must match the provided regular expression.	pattern (string), flags (string)
Includes	includes	Value must be present in the allowed list.	list (array)
URL (Strict)	urlStrict	Must be a valid URL with protocol (http/https).	None
UUID	uuid	Must be a valid UUID string.	None
IP Address	ip	Must be a valid IPv4 address.	None
IPv6	ipv6	Must be a valid IPv6 address.	None
MAC Address	macAddress	Must be a valid MAC address.	None
Same As	confirmed:password	Matches value against another field (e.g., password confirm).	target (value)

🧬 Usage Examples

1. Basic usage with Pipe Syntax

Simple string-based rules are perfect for common validations. Parameters are passed after a colon.

{
  "model": "user.age",
  "label": "Age",
  "component": "Input",
  "rules": "required|integer|between:18,65"
}

2. Complex Rules with Object Syntax

For rules that require complex arguments (like regex patterns with special characters) or when you prefer structured data, use the object syntax:

{
  "model": "username",
  "component": "Input",
  "rules": {
    "required": true,
    "regex": {
      "pattern": "^[A-Za-z0-9_]+$",
      "flags": "i"
    },
    "minLength": { "min": 3 }
  }
}

3. Conditional Validation

Validation rules can be dynamically adjusted using the reactive schema capabilities or by using evaluate() expressions within your component logic to toggle readonly or disabled states, which indirectly affects user interaction.

🧩 Custom Validators

You can easily extend the validation library by creating a new validator module. The system auto-discovers validators in utils/validators/*.ts.

Example: isBlue.ts

// utils/validators/isBlue.ts
import { useI18n } from "vue-i18n";
const { t } = useI18n();

// 1. Define the Validator Function
export const isBlue = (value: string) => {
  if (!value) return undefined; // Skip empty (use 'required' for that)
  return value.toLowerCase() === "blue"
    ? undefined
    : t("validation.must_be_blue");
};

// 2. Define Metadata (for Form Builder UI)
export const metadata = {
  label: "Must be Blue",
  description: "Validates that the input is the color blue",
};

// 3. Register the Validator
export const extend = (registry: any) => {
  registry.isBlue = isBlue;
};

Using your new validator:

{
  "model": "favoriteColor",
  "rules": "required|isBlue"
}