Validation rules

Rules are how a form decides whether a value is acceptable. You attach them to a field as an array. Each rule is an object with an r key naming the rule:

{
  "name": "email",
  "type": "text",
  "label": "Email",
  "rules": [{ "r": "required" }, { "r": "email" }]
}

Rules run in order on the server. A field with no rules accepts anything (subject to the global size limits).

Rules that take a parameter

Some rules need a value, written after a colon inside the r string:

{ "r": "min:3" }
{ "r": "max:2000" }
{ "r": "in:Sales,Support,Other" }
{ "r": "regex:/^[A-Z]{2}\\d{4}$/" }

Built-in rules

Rule	Checks	Example
required	The field is not empty. On a checkbox it means “must be ticked”. On a file field it means “a file was uploaded”.	{ "r": "required" }
email	A valid email address.	{ "r": "email" }
min:N	The text is at least N characters long.	{ "r": "min:10" }
max:N	The text is at most N characters long.	{ "r": "max:500" }
numeric	The value is a number.	{ "r": "numeric" }
integer	The value is a whole number.	{ "r": "integer" }
date	A real date in YYYY-MM-DD format.	{ "r": "date" }
url	A valid URL.	{ "r": "url" }
tel	A loose international phone number: 6 to 15 digits, common separators and a leading + allowed.	{ "r": "tel" }
regex:pattern	The value matches your regular expression. The pattern is taken literally.	{ "r": "regex:/^[A-Z]{2}\\d{4}$/" }
in:a,b,c	The value is one of the listed options.	{ "r": "in:S,M,L,XL" }

Polish rules

For Polish sites, three extra rules are built in:

Rule	Checks
phone	A Polish phone number (9 digits, also accepts landline numbers). Stricter than tel.
nip	A valid Polish NIP (tax identification number), including its checksum.
postCodePL	A Polish postal code in NN-NNN format.

Use phone instead of the loose tel rule when the site serves one country. Use tel when visitors could be anywhere.

Rules for file fields

File fields take their own rules. See Field types for the file field itself.

Rule	Checks
mimes:ext,ext	The file’s real type (detected from its contents) is in this list. Example: mimes:pdf,jpg,png.
maxSize:MB	The file is no larger than this many megabytes. There is also a hard 10 MB cap regardless of this rule.
maxFiles:N	At most N files. Currently one file per field is supported.

Error messages

If a value fails a rule, OctaForms returns a message for that rule. You do not have to write any messages: leave the rule as { "r": "..." } and a clear, translated default is used automatically. This is the recommended approach, because the default follows the site’s language.

To override a message for a specific rule, add an m key:

{ "r": "required", "m": "Please tell us your name so we can reply." }

Errors come back grouped by field and then by rule, so your form can show each message next to the field it belongs to. The exact shape is in Your own JavaScript; the JS helper places them for you.

Adding your own rule

Developer

You can register custom rules with a filter. See Custom validation rules.