Validation

Introduction

Stelar provides a powerful system to validate your application’s incoming data. You can specify rules in the inputs of your actions or use the validation system directly, given the data to be validated and a set of rules.

Validation Quickstart

To learn about Stellar’s powerful validation features, let’s look at a complete example of validating an action request and displaying the error messages.

To use the validation system directly in your actions’ declarations to automatically validate the requests you just need specify the rules on your inputs. On the follow example there is an action to register an user, this action receives an email and a password who needs to be confirmed.

exports.registerUser = {
  name: 'registerUser',
  description: 'This action registers a new user.'

  inputs: {
    email: {
      validator: 'required|email'
    },
    password: {
      validator: 'required|confirmed'
    }
  },

  run (api, action, next) {
    // logic to register the user...

    next()
  }
}

To set the validation rules for a input field you must set the validator property with the desired rules.

Available Validation Rules

Below is a list of all available validation rules and their function:

alpha

The field under validation must be entirely alphabetic characters.

alpha_dash

The fields under validation may have alpha-numeric characters, as well as dashes and underscores.

alpha_num

The field under validation must be entirely alpha-numeric characters.

array

The field under validation must be an array.

before:date

The field under validation must be a value preceding the given date.

between:min,max

The field under validation must have a size between the given min and max. Strings, numerics, and arrays are evaluated in the same fashion as the size rule.

boolean

The field under validation must be able to cast as a boolean. Accepted input are true and false.

confirmed

The field under validation must have a matching field of foo_confirmation. For example, if the field under validation is password, a matching password_confirmation field must be present in the input.

date

The field under validation must be a valid date according to the Date JavaScript function.

different:field

The field under validation must have a different value than field.

email

The field under validation must be formatted as an e-mail address.

filled

The field under validation must not be empty when it is present.

in:foo,bar,…

The field under validation must be included in the given list of values.

ip

The field under validation must be an IP address.

json

The field under validation must be a valid JSON string.

max

The field under validation must be less than or equal to a maximum value. Strings, numerics, and arrays are evaluated in the same fashion as the size rule.

min

The field under validation must have a minimum value. Strings, numerics, and arrays are evaluated in the same fashion as the size rule.

not_in:foo,bar,…

The field under validation must not be included in the given list of values.

regex:pattern,flags

The field under validation must match the given regular expression.

Note: When using the regex pattern, it may be necessary to specify rules in an array instead of using pipe delimiters, especially if the regular expression contains a pipe character.

required

The field under validation must be present in the input data.

required_if:anotherfield,value,…

The fields under validation must be present and not empty if the anotherfield field is equal to any value.

required_unless:anotherfield,value,…

The field under validation must be present and not empty unless the anotherfield field is equal to any value.

required_with:foo,bar,…

the field under validation must be present and not empty only if any of the other specified field are present.

required_with_all:foo,bar,…

The field under validation must be present and not empty only if all of the other specified fields are present.

required_without:foo,bar,…

The field under validation must be present and not empty only when any of the other specified fields are not present.

required_without_all:foo,bar,…

The field under validation must be present and not empty only when all of the other specified fields are not present.

same:field

The given field must match the field under validation.

size:value

The field under validation must have a size matching the given value. For string data, value corresponds to the number of characters. For numeric data, value corresponds to a given integer value. For an array, size corresponds to the length of the array.

url

The field under validation must be a valid URL.

Using Functions as a Validator

You can also use functions to validate your input. Please, don’t use arrow functions otherwise Stellar will not be able to inject the api instance as the context (this). The function receives one parameter, who is the inputted value.

exports.example = {
  name: 'example',

  inputs: {
    value: {
      validator: function (value) {
        return (value === 'test123') ? true : 'This is an error message!'
      }
    }
  }
}

The function must return an Boolean or a String, where String or false means that the validation failed. If a String is returned this will be used as the error message.

Automatic Error Response

Stellar can generate automatic error responses when at least one input field don’t match with the validation rules defined in the action. The error message is always a hash here the key is the field name and the value is the effective error for that field. The follow snippet shows an error response:

{
  "error": {
    "email": "The email must be a valid email address.",
    "password": "The password field is required."
  }
}

← Security Logging →

Models