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}
    Example Show a hint only when a field has validatorsNot every field type exposes {{ validators }}. Guard on is_valid before reading its list, since a field with none still returns the object.
    Liquid
    {%- if form_field.validators.is_valid -%}
	<p class="field-hint">{{ form_field.validators.validators | size }} rule(s) apply to this field.</p>
{%- endif -%}

    validators.is_valid is true only when the list holds one or more validator objects, so this never prints an empty hint for a field with none. validators.validators is the flat list to loop or count.

    Example Fall back to a generic message when a validator has none{{ validator }} always has message, but it is often blank so the runtime default applies. Build your own fallback with the type when you render messages yourself.
    Liquid
    {%- for v in form_field.validators.validators -%}
	<li data-rule="{{ v.type }}">{{ v.message | default: v.type | append: " validation failed" }}</li>
{%- endfor -%}

    message is one of {{ validator }}'s shared properties, present on every typed validator, but it is commonly empty because the field relies on the CMS's own default wording. default swaps in the validator's type so the list item is never blank.

    {{ 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.

    Example Fall back to a generic message when a validator has none{{ validator }} always has message, but it is often blank so the runtime default applies. Build your own fallback with the type when you render messages yourself.
    Liquid
    {%- for v in form_field.validators.validators -%}
	<li data-rule="{{ v.type }}">{{ v.message | default: v.type | append: " validation failed" }}</li>
{%- endfor -%}

    message is one of {{ validator }}'s shared properties, present on every typed validator, but it is commonly empty because the field relies on the CMS's own default wording. default swaps in the validator's type so the list item is never blank.

    {{ 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}
    Example Show a required-format hint for a validatoralphanumeric_validator, decimal_validator, email_validator, number_validator, phone_validator, and url_validator all share the same shape — a format check with no extra properties beyond message.
    Liquid
    {%- for v in form_field.validators.validators -%}
	<li>Must be a valid {{ v.type }}.</li>
{%- endfor -%}

    These six types add nothing beyond {{ validator }}'s own object_type/type/message — there is no value or field_id to read, because the rule is a fixed format check rather than a comparison. type already names the format (email, url, phone, number, decimal, alphanumeric), so it doubles as the hint text.

    {{ 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}
    Example Show a required-format hint for a validatoralphanumeric_validator, decimal_validator, email_validator, number_validator, phone_validator, and url_validator all share the same shape — a format check with no extra properties beyond message.
    Liquid
    {%- for v in form_field.validators.validators -%}
	<li>Must be a valid {{ v.type }}.</li>
{%- endfor -%}

    These six types add nothing beyond {{ validator }}'s own object_type/type/message — there is no value or field_id to read, because the rule is a fixed format check rather than a comparison. type already names the format (email, url, phone, number, decimal, alphanumeric), so it doubles as the hint text.

    {{ 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}
    Example Compare a validator against another fielddifferent_validator and same_validator both compare this field to another field by field_id, requiring the values to differ or match.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "different_validator" -%}
		<li>Must differ from {{ v.field_id }}</li>
	{%- elsif v.object_type == "same_validator" -%}
		<li>Must match {{ v.field_id }}</li>
	{%- endif -%}
{%- endfor -%}

    Both types read field_id, never a literal value — they always compare against another field on the same form, not a fixed string. same_validator also has invert (unused here), which reverses the check to "must differ" instead.

    {{ 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}
    Example Show a required-format hint for a validatoralphanumeric_validator, decimal_validator, email_validator, number_validator, phone_validator, and url_validator all share the same shape — a format check with no extra properties beyond message.
    Liquid
    {%- for v in form_field.validators.validators -%}
	<li>Must be a valid {{ v.type }}.</li>
{%- endfor -%}

    These six types add nothing beyond {{ validator }}'s own object_type/type/message — there is no value or field_id to read, because the rule is a fixed format check rather than a comparison. type already names the format (email, url, phone, number, decimal, alphanumeric), so it doubles as the hint text.

    {{ 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}
    Example Require a field to equal, or not equal, a fixed valueeq_validator and not_validator both compare against a literal value, never another field — they are opposite tests of the same shape.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "eq_validator" -%}
		<li>Must equal "{{ v.value }}"</li>
	{%- elsif v.object_type == "not_validator" -%}
		<li>Must not equal "{{ v.value }}"</li>
	{%- endif -%}
{%- endfor -%}

    Both types read only value — there is no field_id, unlike gt_validator/lt_validator's optional field comparison. eq_validator also has an unused invert property that would make it behave like not_validator instead of needing a separate type, but the two ship as distinct typed objects.

    {{ 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}
    Example Read a validator that compares to a value or another fieldgt_validator and gte_validator compare against either a literal value or another field — field_id is set only when comparing to a field, so value is the fallback.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "gt_validator" -%}
		<li>Must be greater than {{ v.field_id | default: v.value }}</li>
	{%- elsif v.object_type == "gte_validator" -%}
		<li>Must be {{ v.field_id | default: v.value }} or greater</li>
	{%- endif -%}
{%- endfor -%}

    Unlike the form-field condition versions, these validators can compare to either a fixed value or another field's value: field_id is present only in the field-comparison case, so default falls back to value for the fixed-threshold case. gte_validator differs from gt_validator only by including the boundary itself.

    {{ 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}
    Example Read a validator that compares to a value or another fieldgt_validator and gte_validator compare against either a literal value or another field — field_id is set only when comparing to a field, so value is the fallback.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "gt_validator" -%}
		<li>Must be greater than {{ v.field_id | default: v.value }}</li>
	{%- elsif v.object_type == "gte_validator" -%}
		<li>Must be {{ v.field_id | default: v.value }} or greater</li>
	{%- endif -%}
{%- endfor -%}

    Unlike the form-field condition versions, these validators can compare to either a fixed value or another field's value: field_id is present only in the field-comparison case, so default falls back to value for the fixed-threshold case. gte_validator differs from gt_validator only by including the boundary itself.

    {{ 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}
    Example Read a validator that compares to a value or another field, on the low sidelt_validator and lte_validator compare against either a literal value or another field — field_id is set only when comparing to a field, so value is the fallback.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "lt_validator" -%}
		<li>Must be less than {{ v.field_id | default: v.value }}</li>
	{%- elsif v.object_type == "lte_validator" -%}
		<li>Must be {{ v.field_id | default: v.value }} or less</li>
	{%- endif -%}
{%- endfor -%}

    Mirrors gt_validator/gte_validator on the other side of the comparison: field_id is present only when comparing to another field, so default falls back to the literal value otherwise. lte_validator differs from lt_validator only by including the boundary itself.

    {{ 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}
    Example Read a validator that compares to a value or another field, on the low sidelt_validator and lte_validator compare against either a literal value or another field — field_id is set only when comparing to a field, so value is the fallback.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "lt_validator" -%}
		<li>Must be less than {{ v.field_id | default: v.value }}</li>
	{%- elsif v.object_type == "lte_validator" -%}
		<li>Must be {{ v.field_id | default: v.value }} or less</li>
	{%- endif -%}
{%- endfor -%}

    Mirrors gt_validator/gte_validator on the other side of the comparison: field_id is present only when comparing to another field, so default falls back to the literal value otherwise. lte_validator differs from lt_validator only by including the boundary itself.

    {{ 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}
    Example Enforce a selection-count validator's limitmaxitems_validator and minitems_validator both count selections on a list field; value holds the limit, same shape as their condition counterparts.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "maxitems_validator" -%}
		<li>Choose {{ v.value }} or fewer</li>
	{%- elsif v.object_type == "minitems_validator" -%}
		<li>Choose at least {{ v.value }}</li>
	{%- endif -%}
{%- endfor -%}

    These are the submit-time enforcement counterpart to maxitems_condition/minitems_condition's show/hide side. Unlike the condition versions, the validator versions have no field_id — only value, since a validator always checks the field it is attached to, never a different one.

    {{ 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}
    Example Enforce a character-count validator's limitmaxlength_validator and minlength_validator both count characters in a text value; value holds the limit.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "maxlength_validator" -%}
		<li>{{ v.value }} characters or fewer</li>
	{%- elsif v.object_type == "minlength_validator" -%}
		<li>At least {{ v.value }} characters</li>
	{%- endif -%}
{%- endfor -%}

    Same shape as maxitems_validator/minitems_validator — object_type, type, message, and value — but counting characters in a string instead of selections in a list.

    {{ 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}
    Example Show the upload size limit from a maxsize_validatormaxsize_validator is the only typed validator that limits an uploaded file rather than a text, number, or list value.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "maxsize_validator" -%}
		<li>File must be under {{ v.value }}</li>
	{%- endif -%}
{%- endfor -%}

    Same shared shape as every other validator (object_type, type, message, value) but only meaningful on a file-upload field; there is no matching minsize_validator.

    {{ 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}
    Example Enforce a selection-count validator's limitmaxitems_validator and minitems_validator both count selections on a list field; value holds the limit, same shape as their condition counterparts.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "maxitems_validator" -%}
		<li>Choose {{ v.value }} or fewer</li>
	{%- elsif v.object_type == "minitems_validator" -%}
		<li>Choose at least {{ v.value }}</li>
	{%- endif -%}
{%- endfor -%}

    These are the submit-time enforcement counterpart to maxitems_condition/minitems_condition's show/hide side. Unlike the condition versions, the validator versions have no field_id — only value, since a validator always checks the field it is attached to, never a different one.

    {{ 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}
    Example Enforce a character-count validator's limitmaxlength_validator and minlength_validator both count characters in a text value; value holds the limit.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "maxlength_validator" -%}
		<li>{{ v.value }} characters or fewer</li>
	{%- elsif v.object_type == "minlength_validator" -%}
		<li>At least {{ v.value }} characters</li>
	{%- endif -%}
{%- endfor -%}

    Same shape as maxitems_validator/minitems_validator — object_type, type, message, and value — but counting characters in a string instead of selections in a list.

    {{ 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}
    Example Require a field to equal, or not equal, a fixed valueeq_validator and not_validator both compare against a literal value, never another field — they are opposite tests of the same shape.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "eq_validator" -%}
		<li>Must equal "{{ v.value }}"</li>
	{%- elsif v.object_type == "not_validator" -%}
		<li>Must not equal "{{ v.value }}"</li>
	{%- endif -%}
{%- endfor -%}

    Both types read only value — there is no field_id, unlike gt_validator/lt_validator's optional field comparison. eq_validator also has an unused invert property that would make it behave like not_validator instead of needing a separate type, but the two ship as distinct typed objects.

    {{ 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}
    Example Show a required-format hint for a validatoralphanumeric_validator, decimal_validator, email_validator, number_validator, phone_validator, and url_validator all share the same shape — a format check with no extra properties beyond message.
    Liquid
    {%- for v in form_field.validators.validators -%}
	<li>Must be a valid {{ v.type }}.</li>
{%- endfor -%}

    These six types add nothing beyond {{ validator }}'s own object_type/type/message — there is no value or field_id to read, because the rule is a fixed format check rather than a comparison. type already names the format (email, url, phone, number, decimal, alphanumeric), so it doubles as the hint text.

    {{ 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}
    Example Show a required-format hint for a validatoralphanumeric_validator, decimal_validator, email_validator, number_validator, phone_validator, and url_validator all share the same shape — a format check with no extra properties beyond message.
    Liquid
    {%- for v in form_field.validators.validators -%}
	<li>Must be a valid {{ v.type }}.</li>
{%- endfor -%}

    These six types add nothing beyond {{ validator }}'s own object_type/type/message — there is no value or field_id to read, because the rule is a fixed format check rather than a comparison. type already names the format (email, url, phone, number, decimal, alphanumeric), so it doubles as the hint text.

    {{ 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}
    Example Show the pattern a regex_validator requiresregex_validator tests the field value against value, a regular expression, and can invert the test to require a non-match instead.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "regex_validator" -%}
		<li>Must match pattern {{ v.value }}</li>
	{%- endif -%}
{%- endfor -%}

    value holds the raw regular expression, not a pre-parsed pattern object. invert (unused here) reverses the test to require the value not match the pattern, mirroring how contains_condition's invert works on the show/hide side.

    {{ 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}
    Example Compare a validator against another fielddifferent_validator and same_validator both compare this field to another field by field_id, requiring the values to differ or match.
    Liquid
    {%- for v in form_field.validators.validators -%}
	{%- if v.object_type == "different_validator" -%}
		<li>Must differ from {{ v.field_id }}</li>
	{%- elsif v.object_type == "same_validator" -%}
		<li>Must match {{ v.field_id }}</li>
	{%- endif -%}
{%- endfor -%}

    Both types read field_id, never a literal value — they always compare against another field on the same form, not a fixed string. same_validator also has invert (unused here), which reverses the check to "must differ" instead.

    {{ 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}
    Example Show a required-format hint for a validatoralphanumeric_validator, decimal_validator, email_validator, number_validator, phone_validator, and url_validator all share the same shape — a format check with no extra properties beyond message.
    Liquid
    {%- for v in form_field.validators.validators -%}
	<li>Must be a valid {{ v.type }}.</li>
{%- endfor -%}

    These six types add nothing beyond {{ validator }}'s own object_type/type/message — there is no value or field_id to read, because the rule is a fixed format check rather than a comparison. type already names the format (email, url, phone, number, decimal, alphanumeric), so it doubles as the hint text.