Skip to documentation content

Form Field Validators

On this page

    Validators that check a form field value before submit, including {{ validators }}, the shared {{ validator }} shape, and each typed validator object.

    Some field types expose a {{ validators }} object; others do not. That object is not polymorphic: object_type is always validators, and validators holds a flat list of validator objects.

    Each item in that list is polymorphic. Liquid exposes the shared shape as {{ validator }}, but at runtime each item is one of the typed validator objects on this page. Use object_type or type to tell which implementing type you have.

    Unlike conditions, multiple validators are not grouped with and/or. They sit in one flat list. {{ validator }} documents only the shared properties (object_type, is_valid, type, and message). Typed objects add the rest.

    These are form-field validators, not Liquid {% if %} operators.

    {{ validators }}

    The validators object on a form field. This object is not polymorphic: object_type is always validators. Some field types expose it; others do not. validators holds a flat list of validator objects, and each of those is one of the typed validator objects.

    Properties
    Name Type Description
    is_valid boolean Will be true if validators contains one or more validators
    object_type string Will always be "validators"
    validators list The list of validator objects for the current field. Each item is one of the typed {{ validator }} objects
    output string {JSON object}

    {{ validator }}

    {{ validator }} is the shared shape for one form-field validator. It is not a separate runtime type: each item in the validators list is one of the typed validator objects on this page (email_validator, maxsize_validator, and the rest). Use object_type or type to tell which implementing type you have.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string The object_type of the implementing validator (for example email_validator or maxsize_validator)
    type string The type of validator. Each type corresponds to a different validator object which has its own additional properties
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    output string {JSON object}

    Typed validator objects add further properties that are not listed here (for example value or field_id). See each type on this page.

    {{ alphanumeric_validator }}

    A form-field validator that requires the value to contain only letters and numbers.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "alphanumeric_validator"
    type string Will always be "alphanumeric"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    output string {JSON object}

    {{ decimal_validator }}

    A form-field validator that requires the value to be a decimal number.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "decimal_validator"
    type string Will always be "decimal"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    output string {JSON object}

    {{ different_validator }}

    A form-field validator that requires the value to differ from another field.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "different_validator"
    type string Will always be "different"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    field_id string The field_id of the other field that this value must differ from
    output string {JSON object}

    {{ email_validator }}

    A form-field validator that requires the value to be an email address.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "email_validator"
    type string Will always be "email"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    output string {JSON object}

    {{ eq_validator }}

    A form-field validator that requires the value to equal a given value.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "eq_validator"
    type string Will always be "eq"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value string The value that the field must equal
    invert boolean When true, the validator requires the field value not to equal the given value
    output string {JSON object}

    {{ gt_validator }}

    A form-field validator that requires the value to be greater than a given value or another field.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "gt_validator"
    type string Will always be "gt"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value string The value that the field must be greater than, when field_id is not set
    field_id string When set, the field_id of the other field that this value must be greater than
    output string {JSON object}

    {{ gte_validator }}

    A form-field validator that requires the value to be greater than or equal to a given value or another field.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "gte_validator"
    type string Will always be "gte"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value string The value that the field must be greater than or equal to, when field_id is not set
    field_id string When set, the field_id of the other field that this value must be greater than or equal to
    output string {JSON object}

    {{ lt_validator }}

    A form-field validator that requires the value to be less than a given value or another field.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "lt_validator"
    type string Will always be "lt"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value string The value that the field must be less than, when field_id is not set
    field_id string When set, the field_id of the other field that this value must be less than
    output string {JSON object}

    {{ lte_validator }}

    A form-field validator that requires the value to be less than or equal to a given value or another field.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "lte_validator"
    type string Will always be "lte"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value string The value that the field must be less than or equal to, when field_id is not set
    field_id string When set, the field_id of the other field that this value must be less than or equal to
    output string {JSON object}

    {{ maxitems_validator }}

    A form-field validator that requires a list field to have at most a given number of selected items.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "maxitems_validator"
    type string Will always be "maxitems"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value integer The maximum number of selected items
    output string {JSON object}

    {{ maxlength_validator }}

    A form-field validator that requires the value to be no longer than a given number of characters.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "maxlength_validator"
    type string Will always be "maxlength"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value integer The maximum number of characters allowed
    output string {JSON object}

    {{ maxsize_validator }}

    A form-field validator that limits the size of an uploaded file.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "maxsize_validator"
    type string Will always be "maxsize"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value integer The maximum allowed size for an uploaded file
    output string {JSON object}

    {{ minitems_validator }}

    A form-field validator that requires a list field to have at least a given number of selected items.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "minitems_validator"
    type string Will always be "minitems"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value integer The minimum number of selected items
    output string {JSON object}

    {{ minlength_validator }}

    A form-field validator that requires the value to be at least a given number of characters.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "minlength_validator"
    type string Will always be "minlength"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value integer The minimum number of characters required
    output string {JSON object}

    {{ not_validator }}

    A form-field validator that requires the value not to equal a given value.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "not_validator"
    type string Will always be "not"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value string The value that the field must not equal
    output string {JSON object}

    {{ number_validator }}

    A form-field validator that requires the value to be an integer number.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "number_validator"
    type string Will always be "number"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    output string {JSON object}

    {{ phone_validator }}

    A form-field validator that requires the value to be a phone number.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "phone_validator"
    type string Will always be "phone"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    output string {JSON object}

    {{ regex_validator }}

    A form-field validator that requires the value to match a regular expression.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "regex_validator"
    type string Will always be "regex"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    value string The regular expression to test the field value against
    invert boolean When true, the validator requires the field value not to match the pattern
    output string {JSON object}

    {{ same_validator }}

    A form-field validator that requires the value to match another field.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "same_validator"
    type string Will always be "same"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    field_id string The field_id of the other field that this value must match
    invert boolean When true, the validator requires the field value to differ from the other field
    output string {JSON object}

    {{ url_validator }}

    A form-field validator that requires the value to be a URL.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    object_type string Will always be "url_validator"
    type string Will always be "url"
    message string The message to display when this validator fails. If message is null or empty, a reasonable default is used
    output string {JSON object}