Validation, edit checks and their severities

What this is, and who it is for#

A check is a rule a field applies to its own value: required, a minimum, a pattern, a normal range, a date limit. Checks are set on the field in the builder, frozen into the version, and run in two places that must agree: in the browser as the person types, and on the server when the record is saved, where they decide what is stored, what is refused and what opens a query. This page lists every check, how to set it, and the three things a failing check can do. Checks that look across fields or visits are not these; they are rules.

Where to find it#

Study → Build → Forms → a form → Open builder → select a field → Validation (and, for the normal range, the Normal range block on the same tab). A check of a table column is set in the column's Edit checks (Tables and repeating groups). You need form.design or study.write, and the form must be a Draft in a version in Build.

What you can do#

1. Select the field and open Validation.
2. Switch on Required, and set the limits that fit its type.
3. At the bottom, under When a check fails, choose what each check does: Query, Block or Warn. Only the checks the field actually has are listed.
4. Preview the form to see the messages (Preview and testing).

Every option#

Required#

The Required switch (with an optional message, This field is required by default) has no severity. It always does the same things:

• the form cannot be marked complete while the field is empty. In the data entry screen the one button, Submit form, saves and marks the form complete, so with a required field empty the screen lists the errors and saves nothing, and the server would refuse as well (This form cannot be marked complete — …, naming the fields);
• a save that does not ask for completion (from a program using the API) is accepted, leaves the record in progress, and an unanswered required field then has an automatic query titled Required value missing, which closes itself once the field is answered;
• a field hidden by its visibility condition is not checked.

A required Checkbox must be ticked (an unticked box is empty); a required Toggle must be answered (No satisfies it); a required Range needs a value in the boxes. A required table cell is checked the same way, per cell. A field hidden by its visibility condition is not checked.

Enlarge

The three severities#

Choose Block for a value that cannot be true (a weight of 10,000 kg). Choose Query for a value that is possible but should be confirmed (a laboratory result outside its normal range). Choose Warn for advice. Changing a check's severity in an amendment is a Controlled change and is shown in the amendment's summary.

Enlarge

The 19 checks#

A check is on the list for a field only when the field has it: its value is set (a minimum, a pattern) or its type implies it (an email's format). The Where column is where it is enforced: both means the browser and the server.

Also checked, with no severity of their own: a number field given something that is not a number; a date that is not a date; and an Other, specify choice with its free-text box left empty (the person must say what the other is, whether or not the field is required).

For a table column the set is narrower: Minimum, Maximum, Decimal places and Normal range for number and range columns, length and pattern for text columns, and the date checks for date columns. A column's normal range is a check only while the column's Auto-query when out of normal range switch is on.

The automatic query's name and wording#

An automatic query opened by a check is titled by what failed: Required value missing, Below the allowed minimum, Above the allowed maximum, Outside the normal range, Too many decimal places, Too short, Too long, Not in the expected format, Not one of the choices, Too few selections, Too many selections, File type not allowed, Date in the future, Date in the past, Date before the allowed minimum, Date after the allowed maximum. The checks format_email, format_phone, format_time and the Other, specify check have no such title in this release, so their queries are titled by the key (Edit check: format_email). Its text is the check's message. See Work with queries.

Pattern presets#

Under Pattern preset: Alphanumeric, Uppercase letters only, Lowercase letters only, Numeric digits only, Phone (international), Zip code (US 5-digit), Postal code (UK), Date DD/MM/YYYY, CDASH Subject ID, No special characters, Hex colour code, or Custom. A valid expression shows a green tick, an invalid one a red mark and Invalid regular expression — check syntax; the Test pattern box tells you at once whether a sample value matches.

What the system records#

• The check's settings and severities are part of the form's design revision and its snapshot; the snapshot's content hash covers them.
• A query opened by a check is query.raised with origin auto, the rule key and the priority; its closing is query.closed. A blocked save writes nothing about the value, because nothing was saved. A Warn leaves no trace.
• Every value that is saved is an audit entry with its earlier value and reason; the check does not change that.

What you cannot do, and why#

• Give Required a severity. A required field that could be saved and completed empty would not be required.
• Set a severity on a check the field does not have. Nothing would use it.
• Make a Warn leave a record. Warn is deliberately silent so it never creates work; use Query for that.
• Rely on the browser alone. A person using the API directly is checked by the server's checks, which are the authority.
• Set the checks of a form after its version leaves Build. The design is frozen from the submission to UAT.

Compliance Q&A#

Related#

Field properties · Units and normal ranges · Rules reference · Work with queries · Enter visit data · Preview and testing