Input Validation
Overview
When you get the value of an input field (via the Input or Form modules), it must first be validated to make sure it is safe to work with.
Rulesets
To declare what kinds of values are allowed for a field, you assign it a ruleset.
A ruleset is just a Map of one or more validation rules.
Every ruleset must have a type rule, plus any additional constraints.
// Positive (i)nteger
Input.get('age', { type: 'i' })
// (s)tring, 3 to 12 characters long.
Input.get('color', { type: 's', min: 3, max: 10 })Shorter Syntax
Instead of a Map, you can use a pipe-delimited string.
The first value must be the type, followed by any additional rules.
Rules that only take a true boolean can be set as a standalone flag.
Input.get('age', 'i')
Input.get('color', 's|min:3|max:12|optional')Defaults
All fields are required unless given the optional rule.
By default, the validator applies these filters to the incoming data, unless overrided by a rule:
- HTML tags are removed.
- Newlines are removed.
- Consecutive spaces are shrunk to 1 space.
Types
Basic Types
| type | Description | Length/Range | Examples |
|---|---|---|---|
| b | boolean | -- | 'true', 'false', '1', '0' |
| i | integer | 0 - any | 1, 7, 1000 |
| f | float | 0 - any | 1.0, 3.14 |
| s | string | 1 - 50 | 'abc 123' |
| ms | multiline string | 1 - 2000 | 'Hello,\nI have a bug.' |
| id | id token (a-z A-Z 0-9 -_.) | 1 - 100 | 's63asg352', 'my-post' |
Registration Types
| type | Length | Characters | Examples |
|---|---|---|---|
| username | 3 - 20 | a-z A-Z 0-9 _ | cat123 |
| password | 8 - 100 | any | any |
| newPassword | 8 - 100 | any | see below |
| 4 - 60 | ___@____ | me@mail.com | |
| accepted | -- | -- | Must be 'true' or '1' |
Contact Types
| type | Length | Characters | Examples |
|---|---|---|---|
| name | 1 - 50 | any | Juan D. García-Díaz |
| firstName | 1 - 20 | any | Juan |
| lastName | 1 - 30 | any | García-Díaz |
| phone | 6 - 30 | 0-9 ().-+ext | (123) 456-7890 |
Content Types
| type | Length | Characters | Examples |
|---|---|---|---|
| title | 1 - 80 | any | e.g. forum titles |
| comment | 1 - 2000 | any | e.g. forum posts |
Date Types
Date types return a Date object.
| type | Format | Examples |
|---|---|---|
| date | yyyy-mm-dd | 2021-07-14 |
| dateTime | yyyy-mm-ddTMM:SS | 2021-07-14T15:43 |
| dateMonth | yyyy-mm | 2021-07 |
| dateWeek | yyyy-W## | 2021-W13 |
| time | MM:SS | 13:45 |
Other Types
| type | Length | Characters | Examples |
|---|---|---|---|
| url | 8 - 200 | http(s)://____ | http://asite.com |
| search | 1 - 100 | any | any |
| color | 7 | #RRGGBB | #113399 |
| json | 1 - any | {...} | '{a:1,b:2,c:"three"}' |
| xDangerRaw | 1 - any | any | -- |
Constraints
Constraint Rules
| rule | Description |
|---|---|
| optional: true | Field is not required. (All fields are required by default) |
| min: # | String length or number must be equal or greater. |
| max: # | String length or number must be equal or less than. |
| step: # | Number must be divisible by step interval. |
| regex: pattern | Entire string must match pattern. Ex: regex: r'\w\d+' |
| in: list | Must be in list. Ex: in: ['red', 'blue', 'green'] |
| notIn: list | Must NOT be in list. |
| same: otherField | Must have same value as otherField. Ex: same: 'passwordConfirm' |
| notSame: otherField | Must NOT have same value as otherField. |
Modifier Rules
| rule | Description |
|---|---|
| list: true | Field has multiple values (e.g. via checkboxes) |
| civilize: true | Apply String.civilize(). |
| xDangerAllowHtml: true | Do not strip HTML tags. |
Uploads
Upload input fields should have an HTML type of file.
The validation type can either be image or file.
Image Uploads
| rule | Description |
|---|---|
| type:image | |
| dir:path | Upload directory, relative to `data/files`. |
| dim:width,height | Resize the image to these dimensions. Crop to center if necessary. |
| keepAspectRatio:true | Do not crop when resizing to `dim`. |
// Example:
{
type: 'image',
dir: 'uploads/profiles',
dim: '200,200',
}File Uploads
| rule | Description |
|---|---|
| type:file | |
| dir:path | Upload directory, relative to `data/files`. |
| exts:list | Allowed extensions. MIME type will be validated. |
| maxSizeKb:# | Must not be greater than this size. |
// Example:
{
type: 'file',
dir: 'uploads/docs',
exts: 'doc,pdf',
maxSizeKb: 200,
}Passwords
Any password or newPassword field will be returned as a Password object instead of a string.
This protects it from being leaked as plain text elsewhere in your app.
New Password Validation
When created via the Form module, fields with the newPassword rule are validated on the client to prevent weak passwords.
A password is allowed if it follows these rules:
- At least 8 characters
- At least one lowercase letter
- At least one non-letter (number or special character)
- Does not follow common keyboard patterns (e.g. "asdf...")
- Does not include common phrases (e.g. "password")
- Does not include the local hostname (e.g. "mysite")
These rules effectively eliminate the top 1,000 most common passwords, and 99% of the 10,000 most common passwords.
This does not lead to perfectly secure passwords, but is a reasonable default for non-critical websites.
To support passwords created by password managers, there is a high length limit (100 characters) and no limit to the type of characters allowed.