Form Validation

Last edit: Feb 28, 2020

Validations are used to ensure that only valid data is saved into your database.
This reference shows you how to validate the state of objects before they go into the database using Form's validations feature.

After reading this reference, you will know:

  • How to configure form validation
  • How to render validation errors

Example

Simple validation example:

fields:
  properties:
    title:
      validation:
        presence: true

A form with the above configuration will not be valid without title property passed with the request unless it's already set on the object passed to the form.

Validation types

You can use the following validation types:

presence

title:
  validation:
    presence: true

unique

fields:
  properties:
    slug:
      validation:
        presence: true
        unique:
          scope:
            - other_property
          message: Must be unique

confirmation

This validation is used when the same value needs to be entered twice.

When you set it to true, the system will require a second form value to be sent to validate. The field will be named <field_name>_confirmation.

For example, a password field with confirmation: true will expect both the password and the password_confirmation fields to be equal.

This means you need to add the password_confirmation field to your form configuration. Because it does not have to be saved into the database, it can be virtual.

The default error message for this validator is the "doesn't match %{attribute}".

password:
  validation:
    confirmation: true
password_confirmation:
  property_options:
    virtual: true

inclusion / exclusion

   malpractice_history:
      validation:
        inclusion:
          in: [true, false]
          message: disclosure is required

format

Tries to match provided value with regexp defined in with.

When presence is set to false, blank value will produce validation error. To avoid that, use allow_blank: true.

phone:
  validation:
    presence: false
    format:
      with: \A[+]?[\d \-()]+\z
      allow_blank: true
      message: This seems to be an invalid phone number. Please try using numbers only

file_content_type

custom_attachments:
  document:
    file:
      validation:
        presence: true
        file_content_type:
          allow:
          - image/jpeg
          - image/png
          - application/pdf
          - application/msword
          - application/vnd.ms-excel

length

attachments:
  validation:
    length:
      is: 2
      message: You need to include Frontside and Backside Photo ID

The possible length constraint options are:

Validation Description Default error message
minimum Cannot have less than the specified number is too short (minimum is %{count} characters)
maximum Cannot have more than the specified number is too long (maximum is %{count} characters)
is The attribute length must be equal to the given number. is the wrong length (should be %{count} characters)

numericality

rate_amount:
  validation:
    presence: true
    numericality:
      greater_than_or_equal_to: 0

Available options are:

Validation Description Default error message
greater_than Input must be greater than the set value must be greater than %{count}
greater_than_or_equal_to Input must be greater than or equal to the set value must be greater than or equal to %{count}
equal_to Input must be equal to the set value must be equal to %{count}
less_than Input must be less than the set value must be less than %{count}
less_than_or_equal_to Input must be less than or equal to the set value must be less than or equal to %{count}
other_than Input must be other than the set value must be other than %{count}
odd Input must be an odd number if set to true must be odd
even Input must be an even number if set to true must be even

datetime

Datetime is a date with exact time, to the second. For example: Fri Feb 07 15:29:43 2020 UTC.

Our system can convert human phrases (for example: 1 hour ago, 3 hours from now, now, 1 day ago) to datetime, so you can write them easier.

Note: yesterday will take yesterdays date at midnight, if you want to preserve time of the day, use 1 day ago

my_date:
  validation:
    datetime:
      after: "10 minutes ago"
      message: "Must not be earlier than 10 minutes ago"

my_date2:
  validation:
    datetime:
      before: "now"
      message: "Must be in the past"

The possible date constraint options are:

Validation Description
at Must be at this exact datetime
before Must be earlier than provided datetime
after Must be later than provided datetime
at_or_before Must be exactly the datetime or earlier
at_or_after Must be exactly the datetime or later

All default error messages are in a format Datetime is not %s %s where the first %s is validation name (is_at, before etc.) and the second %s is the argument of this validation.
If the provided argument is not a valid datetime (for example after: "I am not a valid datetime"), a 501 error is raised and a Log is created with a Date/Time Validation Error description.

date

my_date:
  validation:
    date:
      after: "1 day from now"
      message: "Must be at least 1 day in the future"

The possible date constraint options are:

Validation Description
is_at Must be at this exact date
before Must be earlier than provided date
after Must be later than provided date
on_or_before Must be exactly the date or earlier
on_or_after Must be exactly the date or later

All default error messages are in a format Date is not %s %s where the first %s is validation name (is_at, before etc.) and second %s is the argument of this validation.
If provided argument is not a valid date (for example after: "I am not date"), a 501 error is raised and Log is created with Date/Time Validation Error description.

Conditional Validation

It is possible to validate attributes based on the state of other attributes from the form.

expiry_year:
  validation:
    presence:
      if: '{% if form.expires %}true{% endif %}'

Common Validation Options

message

It is possible to overwrite the default message with additional fields:

customizations:
  expertise:
    validation:
      presence:
        message: Expertise is required.

allow_nil

The allow_nil option skips the validation when the value being validated is nil.

allow_blank

Allows passing an empty string.

Validation Errors

When form validation is raised, an error message is added to form.errors object that contains errors corresponding to fields.

If you need errors for particular field, access them through:


{{ form_object.errors.<field_name> }}

Example:


{{ form_object.errors.name }}

Translation

Each error message can be translated with the platformOS translation mechanism.

See Translations: System Messages for more information.

Questions?

We are always happy to help with any questions you may have.