Validation rules
Every validation rule in the FormDB form builder, the field types each applies to, and the 422 error response returned when a check fails.
This page lists every validation rule you can add in the form builder, which field types each rule works with, and the error response your form receives when a submission fails.
How validation works
Validation runs on FormDB's servers for every submission. It checks the fields you defined in the form builder, no matter how your HTML is written.
- Fields that are not defined in the builder are accepted without any checks.
- Values are trimmed first. An empty value counts as missing.
- A missing value fails only if the field is Required. A missing optional field is skipped and none of its rules run.
- Each field reports one error: the first check that fails.
- A submission that fails validation is not stored and does not use your quota.
Remember to click Save in the builder. Validation uses the last saved version of your fields.
Built-in checks
These run before any rules you add.
Field type | Check | Error message |
|---|---|---|
Any required field | A value must be present. For File upload, at least one file. |
|
Must look like an email address. |
| |
URL | Must be a full address such as |
|
Number | Must be a number. |
|
Date | Must be in the format |
|
Checkboxes, Radio group, Dropdown | Each value must be one of the field's options. |
|
Short text, Long text and Phone have no built-in format check.
Add a rule
- Open the builder and select a field.
- In the Validation section, click Rule.
- Pick a rule from the list and fill in its value if it has one.
- Click Save.
Each rule can be added once per field, except Must contain and Must not contain, which can be added several times. Radio group and Dropdown fields have no rules.
Text rules
Rule | Applies to | What it checks | Error message |
|---|---|---|---|
Min length | Short text, Long text, Phone | At least N characters. |
|
Max length | Short text, Long text, Phone | At most N characters. |
|
Must contain | Short text, Long text | The value includes this text. Case-sensitive. |
|
Must not contain | Short text, Long text | The value does not include this text. Case-sensitive. |
|
Pattern | Short text, Phone | The value matches a regular expression. |
|
A regular expression is a compact way to describe a text format. For example, ^[A-Z]{3}-\d+$ accepts values like ABC-123. Patterns use JavaScript syntax. A pattern matches anywhere in the value unless you anchor it with ^ at the start and $ at the end. A pattern that is not valid is ignored.
Email rule
Rule | Applies to | What it checks | Error message |
|---|---|---|---|
Allowed domains | The address belongs to one of the listed domains, for example |
|
Number rules
Rule | Applies to | What it checks | Error message |
|---|---|---|---|
Min value | Number | The smallest accepted number. |
|
Max value | Number | The largest accepted number. |
|
Whole number | Number | No decimals. |
|
Max decimals | Number | At most N digits after the decimal point. |
|
Positive only | Number | Greater than zero. |
|
URL rules
Rule | Applies to | What it checks | Error message |
|---|---|---|---|
Allowed domains | URL | The link points to one of the listed domains or their subdomains. |
|
Protocol | URL | The address starts with the scheme you choose: HTTPS only, HTTP only or Either. |
|
Note: For the Protocol rule, pick an option from the dropdown even if the one you want is already displayed. The rule has no effect until you choose a value.
Date rules
Rule | Applies to | What it checks | Error message |
|---|---|---|---|
Earliest date | Date | On or after the date you choose. |
|
Latest date | Date | On or before the date you choose. |
|
Future only | Date | After today. |
|
Past only | Date | Before today. |
|
No weekends | Date | Not a Saturday or Sunday. |
|
"Today" is today's date in UTC, not the visitor's local time zone. Today itself fails both Future only and Past only.
File rules
Rule | Applies to | What it checks | Error message |
|---|---|---|---|
Max file size | File upload | Each file is at most N MB. |
|
Allowed types | File upload | Each file's extension is on the list, for example |
|
Min files | File upload | At least N files. |
|
Max files | File upload | At most N files. |
|
Allowed types looks at the file name's extension, not at the file's contents.
Checkbox rules
Rule | Applies to | What it checks | Error message |
|---|---|---|---|
Min selections | Checkboxes | At least N options ticked. |
|
Max selections | Checkboxes | At most N options ticked. |
|
The 422 error response
When validation fails and your form asked for JSON, FormDB returns status 422 with this body:
{
"ok": false,
"error": {
"code": "validation_failed",
"message": "Email must be a valid email address. (+1 more)",
"fields": {
"email": { "message": "Email must be a valid email address.", "rule": "type" },
"message": { "message": "Message is required.", "rule": "required" }
}
}
}error.messageis the first field's message. When more than one field failed,(+N more)is added.error.fieldsis keyed by each field's name. Use it to show a message next to the right input.ruletells you which check failed:required,type(a built-in format check),option(a value that is not one of the field's options), or the rule's identifier.
Rule identifiers: minLength, maxLength, contains, notContains, pattern, emailDomains, minValue, maxValue, integer, decimalPlaces, positive, urlDomains, urlProtocol, minDate, maxDate, futureOnly, pastOnly, noWeekends, maxFileSize, fileTypes, minFiles, maxFiles, minSelections, maxSelections.
For plain HTML forms that do not use JavaScript, the visitor sees a hosted "Submission failed" page with the summary message only. Per-field detail is available in the JSON response.
Here is how to show per-field messages in the browser:
const response = await fetch("https://api.formdb.io/f/your-form-id", {
method: "POST",
headers: { Accept: "application/json" },
body: new FormData(form),
});
const body = await response.json();
if (response.status === 422) {
for (const [name, detail] of Object.entries(body.error.fields)) {
console.log(name, detail.message, detail.rule);
}
}Browser checks and server checks
The code generated by the builder adds matching HTML attributes for some rules, so visitors get instant feedback: Min length, Max length, Pattern, Min value, Max value, Whole number, Max decimals, Earliest date, Latest date and Allowed types for files.
The other rules are checked on the server only. Your form will receive a 422 if they fail, so make sure your page shows the error message.
Next steps
- Form builder: where rules are added.
- JavaScript and AJAX: display errors in your page.
- Endpoint reference: all other error codes.
Ready to try it? Create a free account and send your first submission.