Guide to: Validators

required

On a free text input, at least one non-whitespace character must be present. On a multiple-choice or drop-down field, it enforces at least one item to be selected 

<cml:radios label="Sample radio buttons:" validates="required">
  <cml:radio label="Radio 1" />
  <cml:radio label="Radio 2" />
  <cml:radio label="Radio 3" />
</cml:radios>

integer

Requires an integer value, e.g., 10, -5

<cml:text label="A number" validates="integer"/>

positiveInteger

Requires a positive integer value, e.g., 10, 5

<cml:text label="A positive integer" validates="required positiveInteger" />

numeric

Requires an integer or floating-point value, e.g., 10, 1.5, -2.4

<cml:text label="A numeric number" validates="required numeric" />

digits

Allows only numbers and punctuation, e.g., "10:10-99", "100(2)"

<cml:text label="A number" validates="required digits" />

integerRange

Ensures that the contributor inputs an integer within a given range. This should only be used in combination with the integer validator. Note: The values are inclusive.

<cml:text label="A number between 1 and 100, inclusive" validates="integer integerRange:{min:1,max:100}"/>

internationalPhoneNumber

Requires that a phone number is entered in for the correct country and the number is formatted correctly

<cml:text name="phone" validates="required internationalPhoneNumber" />

Which is the same as:

<cml:text name="phone" validates="required internationalPhoneNumber:{country:'CH',formatOnInput:false,outputFormat:'itnl'}" />

The options for this validator are as follows, with default values in parentheses:

• country ('US') validate for this country's phone number conventions, accepts a two-letter country code or the string 'detect'. If 'detect' is specified, the validator will attempt to auto-determine the country for the given phone number, but the number must be in loose e164 format, including country code, e.g. "+1 (510) 123-4567", "15101234567", "1 510-123-4567".
• formatOnInput (true): auto-format the number as it is typed into the text input, as with a cell phone dialer. Valid values are true and false (no quotation marks).
• outputFormat ('local'): how to format the valid phone number for output upon successful validation. Accepted values are local, itnl, e164, or a two-digit country code. A summary of these options follows:
  • local: format the number as it would be dialed from within the specified country, e.g. "(510) 123-4567"
  • itnl: format the number for international dialing, e.g. "+1 510-123-4567"
  • e164: format the number in international E164 format. e.g. "+15101234567"
  • CH, CA, FR, etc: format the number to be dialed from the country specified by a two-digit country code. If we were validating US numbers and used outputFormat CH, the output would be formatted for dialing a US number from Switzerland, e.g. "00 1 510-123-4567"

email

Requires a valid-looking email address, e.g., "bob@example.com"

<cml:text label="Enter email here" validates="required email" />

url

Requires a valid-looking URL, e.g., "http://crowdflower.com." This validator performs some normalization of the entered URL to make it more useful for test question creation but also submits the user's original input. The normalization includes removing "www.", removing index pages such as "index.html" and "home.html," and adding a trailing slash when needed. The url validator accepts the following optional restrictions:

• google - Requires a google.___ domain
• non-google - Forbids a google.___ domain.
• non-search - Forbids most major search domains (Google, Bing, Yahoo, Ask, Lycos, and AOL Search.)
• domainonly - Strips the entry of everything except the domain.

Examples:

<cml:text label="Non-Google Site" validates="required url:['non-google']" /> 
<cml:text label="Domain Only" validates="required url:{domainonly:true}" />

The url validator submits the following additional data:

• {fieldname}_contributor_input - the raw contributor input.

urlImage

Requires a URL for a valid image. This validator executes an asynchronous request to validate that the URL points to a valid image. This validator does no "cleaning" of the contributor's input.

<cml:text label="Enter image URL here" validates="required urlImage" />

stateAbbr

Requires a valid US state abbreviation, e.g., "CA", "NY"

<cml:text label="Enter state abbreviation here" validates="required stateAbbr" />

zipcode

Requires a valid US zip code, e.g., "94103"

<cml:text label="Enter US zipcode here" validates="required zipcode" />

frAddress

Requires a valid address and returns French address components. The French address validator does not enforce a level of specificity in the address. (However, this can still be enforced via Test Questions). This validator uses the Google Maps API to return a valid, cleaned address in the French format: "123 Rue de Bercy, Paris, 75012, France".

Although this address validator is specifically geared towards addresses in France, it does not prevent contributors from entering addresses from other countries. Use Test Questions to ensure that contributors don't give you non-French addresses.

In addition to the full normalized address, this validator submits the following components as separate fields (these appear as extra columns in your CSV reports):

• {fieldname}_contributorInput - raw contributor input (before normalization)
• {fieldname}_street - street address (eg. "123 Rue de Bercy")
• {fieldname}_buildingLabel - building/unit label (eg. "Suite", "Unit")
• {fieldname}_buildingNumber - building/unit number (eg. "A", "1C")
• {fieldname}_city - town / city (eg. "Paris")
• {fieldname}_postcode - postal code (eg. "75012")
• {fieldname}_country - country (eg. "France")

Example:

<cml:text label="Enter French address here" validates="required frAddress" />

ukAddress

Requires a valid address and returns UK address components. The UK address validator does not enforce a level of specificity in the address. (However, this can still be enforced via Test Questions). This validator uses the Google Maps API to return a valid, cleaned address in the UK format: "123 Brookdale, Enfield, Greater London, N11 1, United Kingdom".

Although this address validator is specifically geared towards UK addresses, it does not prevent contributors from entering addresses from other countries. Use Test Questions to ensure that contributors don't give you non-UK addresses.

In addition to the full normalized address, this validator submits the following components as separate fields (these appear as extra columns in your CSV reports):

• {fieldname}_contributorInput - raw contributor input (before normalization)
• {fieldname}_route - street address (eg. "123 Brookdale")
• {fieldname}_buildingLabel - building/unit label (eg. "Suite", "Unit")
• {fieldname}_buildingNumber - building/unit number (eg. "A", "1C")
• {fieldname}_post_town - town / city (eg. "London")
• {fieldname}_postcode - postal code (eg. "N11 1")
• {fieldname}_country - country (eg. "United Kingdom")

Example:

<cml:text label="Enter state UK address here" validates="required ukAddress" />

clicked and validates-clicked

Requires the URL link or button to be clicked before submitting. This ensures that the contributor has visited the link provided.

This validator is applied to cml:html and the a tag.

<cml:html class="clicked">
<a class="clicked validates-clicked btn btn-info" href="{{link}}">Info Page</a>
</cml:html>

clean

Cleans the contributor's input. The contributor can never "fail" this validator as it does not actually validate anything, it simply cleans their input. You can use any combination of the following cleaners:

• trim - Removes leading and trailing whitespace.
• titlecase - Capitalizes all words that are not all uppercase nor most conjunctions.
• uppercase - Replaces all lowercase letters with uppercase letters.
• lowercase - Replaces all uppercase letters with lowercase letters.
• whitespace - Removes all whitespace from the input.
• multipleWhitespace - Replaces all consecutive whitespace with a single space. (For example, multiple spaces and newlines in a row will get replaced with a single space.)

Cleaners are processed in the order that they are defined.

Example:

<cml:text label="Please enter the correct location in 2-letter format." 
validates="required maxLength:2 clean:['uppercase']" />

In this example, the validator will check:

• 1. 'required' - that the field is not blank
• 2. 'maxLength:2' - that the field only contains 2 characters (i.e. UK)
• 3. 'clean:['uppercase','whitespace']' - "cleans" the answer, making it uppercase

You may define multiple cleaners under one clean validator.

In this example, the validator will "clean" the answer, making it lowercase and removing any whitespaces:

<cml:text label="Enter text here" validates="clean:['lowercase','whitespace']" />

<cml:hidden label="Some text" validates="required user_agent" />

Note: For more validators using Machine Learning Assisted Text Utterance Collection, please see the following articles:

• The Code Editor
• Model Details
• Free Trial