Universal Field Validator — check-character & regex IDs, cross-field rules, uniqueness & dynamic choices (REDCap external module)

Version: the first version heading of the changelog, below any "Unreleased" section, is the current build, with its features, migration notes and verification limits. A release is tagged vX.Y.Z and installs as the folder universal_validator_vX.Y.Z; see "Version numbers" in Install and configure.

Opt-in event and repeat validation: see Event and instance references for qualified references, matching, collections, dates, record-local uniqueness, activation and rollback.

Live, as-you-type validation for any REDCap field with a structure. A mistyped participant ID costs hours of reconciliation later; this module catches it while the person who typed it is still looking at the field.

Documentation: https://nghareformer.github.io/redcap-universal-validator/ — one page per action tag.

Two validation families, one engine:

• Check-character IDs (the flagship): participant and specimen IDs minted with ISO 7064, Damm, Verhoeff, or Luhn check characters. Recomputing the check catches virtually every typo and mis-scan — including the ones a regex can never see, like a 3 typed as an 8.
• Any structured value (regex): study codes, lab numbers, device serials, legacy IDs, or anything else with a fixed shape. In stock REDCap a custom regex validation type has to be added server-wide by an administrator; here a project designer sets a pattern per rule, and typists get progressive "what's still missing" guidance instead of a bare error.

Configured entirely through REDCap's settings screen or field annotations — no code pasting, no JavaScript Injector. IDs minted by the companion QR/ID generator validate identically here, in Excel, and in the browser (same verified engine).

What it does

• Single-value fields — recomputes the check character and/or tests the format, with a green "verified" or red "typo?" message under the field. Format errors and check-character errors are reported separately, so the person knows which kind of mistake they made and where. A "should end in X" hint naming the expected check character is available per rule (suggestFix) but OFF by default — a visible expected character can entice staff to force-fit a mistyped ID instead of re-scanning it.
• Several ID formats in one field — a rule may declare a list of alternates, each with its own pattern and its own check algorithm (or none). A value, or a token inside a pooled box, is valid if any one of them accepts it — so a shipment holding IDs from four studies, three of which carry a check character and one of which does not, validates in a single field without giving up the check character on the three that have one.
• Pooled fields — splits a box holding several IDs (space/comma-separated, or jammed together with no separator) into individual IDs at the boundaries where the check character verifies, then shows one chip per member with warnings for leftover junk, duplicates, and wrong pool size.
• Configurable enforcement per rule — informational (message only), advisory (warn and confirm before saving), or compulsory (block the browser form/survey save until fixed). Compulsory blocks human form saves in the browser; it cannot stop an API or data-import write (see the safety net below), and it never traps a read-only field the user cannot fix.
• Server-side safety net — a redcap_save_record hook re-checks the saved value on the server with the same rule semantics as the client (single and pooled fields, check character, format pattern, regex-only) and logs any invalid value to the module log, scoped to the instrument that was actually saved. It fires after the write, so treat it as detection/audit, not a hard reject; the client Compulsory block is the primary control for human form entry. Coverage caveat: whether this hook fires for Data Import Tool and API writes depends on your REDCap version and how those imports are performed — do not assume import/API writes are audited until you have verified it on your own instance (the step is in docs/TESTING.md). A rule the server cannot evaluate leaves a uvalidate-unconfigurable entry and a hook failure leaves a entry, so neither can pass silently. Each problem is logged once. A save of a value the log already reports for that record and field writes no new entry (see the user guide, Part 7). Raw identifiers are not stored in the log by default — a keyed, project-scoped hash is (HMAC-SHA-256 with a module-held secret), configurable per project down to logging nothing. When the setting cannot be read, or holds a value this version does not know, the log uses the strict mode (): the record ID as its keyed hash and no value. A keyed hash is pseudonymization, not anonymity: treat the module log as identifying data in access and retention policies. The audit trims a value the way the browser does and checks values with characters outside printable ASCII too. Where JavaScript and PCRE regex read such a value differently (for example "." against a carriage return, or against a no-break space), the value is reported in a entry for a manual check, never passed as valid.

Three ways to configure (pick per rule — they mix freely)

One rule = one kind of validation, applied to any number of fields. Every rule kind — Single value / Pooled (check-character or regex), Constraint (@UVASSERT) and Required (@UVREQUIRED) — is available in all three channels; the dialog's "What this rule checks" selector picks the kind:

1. The settings dialog — pick fields with the field picker (click its + to add more fields to the same rule) and choose the method and enforcement.

2. Fast entry — type field names into the rule's fast-entry box, separated by commas or spaces. Unknown names show a configuration error instead of failing silently.

3. @UVALIDATE field annotations — tag fields where you already design them: the Action Tags box in the Online Designer, or the field_annotation column of the data dictionary CSV. Tagging 50 fields is one spreadsheet column and one upload:

   @UVALIDATE                                            default check (ISO 7064 Mod 37,36)
   @UVALIDATE=verhoeff                                   pick the algorithm
   @UVALIDATE={"algorithm":"none","pattern":"FC[0-9]{4}","blockSave":"hard"}
   @UVALIDATE={"type":"pooled","expectedIds":3}          pooled field, warn unless 3 IDs
   

   Several ID formats in one field. Give the rule a list of alternates instead of one pattern/algorithm; a value is valid if any entry accepts it. Each entry carries its own pattern and algorithm, and a pooled rule also needs lengths on every entry so the parser knows where one member ends and the next begins:

   @UVALIDATE={"type":"pooled","strip":"-","blockSave":"hard","alternates":[
     {"label":"GHIT",      "pattern":"FC[1-9]-[0-9]{4}",        "algorithm":"none","lengths":[8]},
     {"label":"START4KIDS","pattern":"SK[1-9]-[0-9]{4}[0-9A-Z]","algorithm":"3736","lengths":[9]},
     {"label":"DARETB",    "pattern":"DT[1-9]-[0-9]{5}[0-9A-Z]","algorithm":"3736","lengths":[10]},
     {"label":"SCREENTB",  "pattern":"ST[1-9]-[0-9]{5}[0-9A-Z]","algorithm":"3736","lengths":[10]}]}
   

   Entry keys: pattern (required), algorithm, source, strip, lengths, label. Anything not given falls back to the rule-level value. The label names the family in messages and on the chips. Up to 8 entries and 32 format/length combinations per rule; when alternates is used the rule-level pattern, idLengths, idMinLen and idMaxLen must be left unset, because each entry carries its own.

   Check-bearing entries own their shape. A value that matches the pattern of any check-bearing entry must pass that entry's check character; a format-only entry ("algorithm":"none") is tried only when no check-bearing pattern matches, whatever the declaration order. A format-only entry may share a length with a check-bearing one as long as their patterns cannot match the same value, as with - codes that carry a check character beside legacy / codes that do not, all six long.

Conditional validation — the optional when key

Any rule, in all three configuration channels, may carry a condition; the rule validates only while the condition is true:

@UVALIDATE={"algorithm":"verhoeff","when":"[specimen_type]='2'"}
@UVALIDATE={"algorithm":"none","pattern":"FC[0-9]{4}","when":"[consent(1)]='1' and [site]<>'9'"}

The Configure dialog offers the same thing as an "Only validate when" box on each rule (fast-entry fields share the rule's box). Fields whose tags differ only in when become separate rules; identical tags still group.

The condition language is a REDCap-style subset — not byte-for-byte REDCap logic:

Supported	Rejected when the rule is saved
[field] and [checkbox(code)] references	functions (datediff(...), …)
'text' / "text" / number literals	smart variables ([record-name], …)
= <> != > < >= <=	[event][field] prefixes, unless extended references are on
and / or / not in any letter case, parentheses	&&, || and ! (write and, or, not)
dates as '2026-03-01', times as '08:30', numbers with a decimal point	a date, time or number written another way ('01-01-2000', '12,5'), and two compared fields of different kinds (a date and a datetime)
	arithmetic and piping
	a module tag inside REDCap's @IF(...): the module does not read @IF, so put the condition in when

One condition may mix and, or and not. not binds tightest, then and, then or, as in REDCap; parentheses change the grouping. An unquoted @UVASSERT or @UVREQUIRED condition is read whole, up to the end of the line or the next action tag.

Semantics worth knowing before relying on it:

• Comparisons are numeric when both sides look numeric ([age]>'9' with age 10 is true, not a lexicographic accident), and string comparison when neither side does. Text ignores letter case by default (2.1.0-rc.1): [status]='active' is true for Active and ACTIVE, in a when, in a branch selector and in an @UVASSERT test alike. Add "caseSensitive":true to any tag's JSON (or tick "compare text case-sensitively" in the Configure dialog) when case carries meaning; the flag covers every condition of that rule. Only the letters A-Z are folded, so accented letters keep their case (É still differs from é): the browser and the server lowercase other letters differently, and both must reach the same verdict. When the two sides are in different domains — one numeric, one not, both non-empty — = and <> still answer by string identity, but < > <= >= are false whichever way round you ask: ordering across domains produced cycles ('2' <= '10', '10' <= '1e1' and '2' > '1e1' were all true at once). An empty side is different again: empty is absence, so an ordered comparison against it has no answer, and what that means depends on which question is being asked. In an @UVASSERT test a value nobody has entered cannot violate a constraint, so the comparison passes: [end]>=[start] and [start]<=[end] both hold while start is blank, and so does not([end]<[start]). In a when gate or a branch selector it means the module cannot tell whether the rule applies, so the rule stays inert: when:"[age]<=18" does not fire on a record whose age is blank. = and <> are unaffected either way — [field]<>'' is still how you ask whether a field has been filled in. A missing or empty field reads as ''; a checkbox reference reads '1'/'0'.

• Referenced fields on the same instrument react live: pick the right dropdown option and the gated field's verdict appears or clears immediately — including a Compulsory save block. A calc field updates without DOM events, so a calc ref refreshes at the next event on any watched field — the manual check for this is in .

The dialect is specified normatively in php/Logic.php; the browser twin lives in js/engine.js, and tests/when_fixture.json locks the two together (see Verification below).

Branched validation — several conditional rules on ONE field

Since 0.9.0, a field may be covered by MORE THAN ONE rule, provided the sharing is gated: every sharing rule carries a when, except at most ONE rule without a condition, which becomes the else branch. The rule whose condition is true validates the field; if none is true, the else branch does; if there is no else either, the field is simply not validated at that moment.

Field annotation (two tags in one box), or two dialog rules covering the field:
@UVALIDATE={"algorithm":"verhoeff","when":"[specimen_type]='2'"}
@UVALIDATE={"algorithm":"none","pattern":"FC[0-9]{4}"}          <- the "otherwise"

Rules worth knowing:

• All configuration channels mix freely — a dialog rule and an @UVALIDATE tag may legally share a field, as long as the sharing is gated.
• Rejected at save time (a configuration error, never silent): two when-less rules on one field; two rules whose conditions say the same thing, however written (keyword case, spacing, quote style, parentheses, the order of and/or members and of a comparison's sides aside); a single-value rule and a pooled rule sharing a field.
• Overlapping conditions are a runtime conflict: if two conditions are ever true at once, the field shows a "Validation conflict" notice naming both conditions, validates nothing, and NEVER blocks the save; the server logs the same conflict to the module log. Mutually exclusive conditions (='2' vs <>'2') can never conflict.
• A rule with a configuration error switches off the else branch of its tag on that field. The broken rule validates nothing and shows its error; it may be a conditional rule whose condition cannot be read, and the else applies only when no condition is true. The other conditional rules still apply. Up to 2.3.0-rc.2 the else became the field's only rule: with event references switched off, a site cascade's last list applied to every site.
• blockSave and suggestFix are per branch — e.g. Compulsory for blood specimens, informational otherwise.
• The branch semantics are specified normatively in php/Branching.php; browser and audit implement the same table (see Verification).

Cross-field constraints — the @UVASSERT tag

Stock REDCap cannot block a bad relationship between fields at entry: branching only hides, a range check only warns, and Data Quality runs in batch. @UVASSERT closes that gap — the field is invalid unless a condition holds, checked live and enforced with the same message/confirm/block modes as everything else:

@UVASSERT="[end_date]>=[start_date]"
@UVASSERT={"assert":"[dose]<=[max_dose]","message":"Dose exceeds the protocol maximum","blockSave":"hard"}
@UVASSERT={"assert":"[sex]='2'","when":"[pregnant]='1'","message":"Pregnant participants must be recorded female"}

• The condition uses the same dialect as when ([field]/[checkbox(code)] refs, = <> != > < >= <=, and/or/not, parentheses). ISO dates and numbers compare correctly; the evaluator is the one parity-locked engine, used here as the test rather than a gate. A field validated as a number, a calc and a slider are read as the number they hold (a saved 12,5 is 12.5), and two numbers compare by value, so 02 equals 2. A condition holds printable ASCII only, so [city]='Yaoundé' is refused; compare the code a choice field stores instead. A field marked with a Missing Data Code gives no answer to <, >, <= and >=, as a blank field gives none, so [end_date]>=[start_date] with the start marked UNK is no violation. = and <> read the code as written.
• An empty field is inert — requiring a value is @UVREQUIRED's job, not a constraint's. Confirm-a-value ("type it twice") takes "exact":true: @UVASSERT={"assert":"[id]=[id_confirm]","exact":true}. Then = and <> compare the two entries character for character, so 00123 does not confirm 123 and +237677123456 does not confirm 237677123456.
• Text is compared without regard to case (2.1.0-rc.1), like every condition in the module: @UVASSERT="[answer]='yes'" accepts Yes and YES. Add "caseSensitive":true when case carries meaning, such as codes where ab12 and AB12 are different answers: @UVASSERT={"assert":"[code]='AB12'","caseSensitive":true}. The flag covers both the assert and the when of that tag. "exact":true counts case too, in the assert only.
• message is your own wording, shown on failure (a generic line is used if you omit it — recommended to set one, since only you can word an arbitrary relationship). Under Multi-Language Management it may be a map of language id to text, {"default":"End is before start","fr":"La fin précède le début"}, on this tag and every other tag that takes a message; the page shows the language on screen (Messages in several languages).

Conditional required — the @UVREQUIRED tag

REDCap's own required flag is unconditional and only warns. @UVREQUIRED adds the two things it lacks: a condition and a real block:

@UVREQUIRED                                              always required
@UVREQUIRED="[consent]='1'"                              required only while consented
@UVREQUIRED={"when":"[consent]='1'","message":"Phone needed for consented participants","blockSave":"hard"}

• A blank field shows the notice while the requirement is in force. Blank means empty or holding only spaces, tabs, line breaks, no-break spaces, other Unicode spaces (U+2000 to U+200A, U+3000) or invisible characters (Unicode's Default_Ignorable_Code_Point, such as a zero-width space, a byte-order mark, a soft hyphen or a Hangul filler): the page, the audit and the scan use one test, pinned by tests/blank_fixture.json. The requirement turns on and off live as referenced fields change. Filling the field clears the notice — deliberately no green "OK", because required mode never judges the value. Pair it with @UVALIDATE or @UVASSERT for that (modes compose, each with its own save-block state: on a blank field only @UVREQUIRED fires; on a filled-but-wrong value only the value checks fire).
• Works on Text, Notes, dropdown, radio, yes/no, true/false, SQL and slider fields. Not calc — the person entering data cannot fill a calc, so requiring one would trap them (the same reasoning as the read-only exemption: a read-only field, a @READONLY radio or autocomplete dropdown included, shows the notice but never blocks the save).
• A field REDCap hides is not required. While branching logic or @HIDDEN hides the field's row there is no notice and the save goes through, as with REDCap's own required flag; the notice comes back as soon as the row is shown. The audit and the scan read the field's branching logic in the condition dialect above and skip a blank field while that logic is false. Branching logic outside the dialect (functions, smart variables, [event][field] prefixes) leaves a blank field unchecked there and is logged as a rule problem, never as a missing value.
• Several @UVREQUIRED tags with different when conditions branch; two conditions true at once is a visible conflict that never blocks.
• On a survey shown one section per page, a condition over a field of another page reads the answer saved when the page was drawn, since REDCap draws only the current page's fields. [consent]='1' on page 2 reads the consent given on page 1.
• The server audit logs a blank-while-required save as type: required, reason: required-blank (a blank carries nothing identifying, so this entry is safe in every privacy mode).
• A survey response is judged once it is complete. REDCap saves each page a respondent leaves, so the audit does not log a page not reached yet, or a field left for Save & Return Later: on a survey save it judges @UVREQUIRED only when the instrument's status is Complete. The scan still lists blank fields of open responses. On the page, Previous Page and Save & Return Later are not held by a blank required field, as with REDCap's own required flag; a value check (, , ...) still holds them, because the page's values are saved either way. The button names and the modes that wait are listed in (, ).

No duplicates across records — the @UVUNIQUE tag

REDCap has no native field-level uniqueness. @UVUNIQUE checks the value against every other record when it is entered or changed (a CSRF-protected module AJAX call, no page reload), with the usual message/confirm/block enforcement:

@UVUNIQUE                                                unique across the project
@UVUNIQUE=event                                          scope: project | dag | event
@UVUNIQUE={"with":["site"],"message":"Specimen already registered","blockSave":"hard"}
@UVUNIQUE={"also":["study_id_scan"]}                     also look in other fields

• with makes the key composite — the value plus those fields together must be unique (a specimen ID within its site). Scopes: project (default), dag (unique within each Data Access Group), event (within the same event of a longitudinal project). A with value is read from the same entry as the tagged field, so the rule is refused when a with field is collected in no event that also collects the tagged field, or sits on a repeating instrument the tagged field is not on. Up to 2.3.0-rc.2, such a with field read as blank: SP-9 at site 1 and SP-9 at site 2 counted as duplicates. A with value on another form that the module cannot read for one record leaves that check as could not check; the save audit logs it as a rule problem instead of comparing a blank. A Missing Data Code in a with field is compared as a value like any other, so SP-8 at site UNK in two records is a duplicate; a code in the tagged field itself is never one.
• also looks for the value in up to 5 other fields too. With @UVUNIQUE={"also":["study_id_scan"]} on study_id_typed, an ID typed there counts as used when another record holds it in study_id_typed or in study_id_scan. Scope and with apply to a match in an also field the same way: the with values must match in the same entry as that field. The check runs one way: to stop a scanned ID that was already typed in another record, put @UVUNIQUE={"also":["study_id_typed"]} on study_id_scan as well. The record being checked is never compared with itself, so a value typed in both fields of one record is not a duplicate; use @UVASSERT for that ({"assert":"[study_id_scan]=''"} on the typed field allows typing only when nothing was scanned). Each also field must exist, hold one value, and store values the way the field does: both text, both dates of the same kind, or both numbers with the same decimal mark. Every @UVUNIQUE tag on one field must list the same also fields, and also cannot be used with "scope":"record". A placement that could never match is refused when the rule is read: an also field and a with field on two different repeating instruments, an also field on an instrument no event collects, or, under "scope":"event", an also field in no event with the tagged field. Staff are told which field the value was found in, unless the record is in another Data Access Group; they get an answer only when they may open the forms that hold the fields. The list of fields is not sent to the page. Each field adds entries to the Validation scan's duplicate groups, one per tagged field and per /scope/letter-case combination of the tag's branches.

Dynamic choice filtering — the @UVCHOICES tag

REDCap's @HIDECHOICE hides options statically; @UVCHOICES shows or hides individual options of a radio, dropdown or checkbox field based on the live values of other fields — a country → region → site cascade in one field instead of one near-duplicate field per country:

@UVCHOICES={"when":"[country]='1'","show":["101","102","103"]}
@UVCHOICES={"when":"[country]='2'","show":["201","202"]}

@UVCHOICES={"when":"[legacy_entry]<>'1'","hide":["9"]}

@UVCHOICES={"when":"[pilot(1)]='1'","show":["s01","s02"],
            "message":"Only pilot sites during the pilot phase.","blockSave":"hard"}

• JSON form only. Exactly one of show (whitelist — every other code of the field hides) or hide (blacklist) per tag, plus optional when, message, blockSave. Codes must exist in the field's own choice list — an unknown code is a configuration error naming the real codes, and so is a hide of every code, which would leave nothing to pick (hide the question with branching logic instead). A when may read the field itself, such as [symptoms(0)]='1' on the symptoms checkbox. A list holds up to 10,000 codes, so the field's own list is the limit in practice. Up to 2.3.0-rc.2 the limit was 200, which left a 600-site list whose region holds 250 sites impossible to write either way.
• Branches like every other mode. Repeat the tag with different when conditions (plus at most one without, as the fallback). Exactly one true condition filters; none (and no fallback) shows everything; more than one true is a visible conflict — the filter is not applied and the save is never blocked on a configuration problem. Conditions may reference fields on other instruments; the server reads their saved values. A comparison of such a field with a fixed value reaches the page as its answer only, true or false. A comparison with a field on the form needs the saved value on the page to follow what is typed: a user with REDCap rights to the other instrument gets that value, and on a survey or without those rights the page gets the answer as of page load (the rule of 1.6.0). On a survey shown one section per page, a condition over a field of an earlier page reads its saved answer in the same way.
• A hidden selection is never cleared. If the stored/selected choice becomes hidden (the user changes the country after picking a site), the module keeps it visible — dropdowns keep the option in place, greyed and marked data-uv-stale, but still enabled so the browser submits it — flags the field invalid with your message, and applies blockSave (off/confirm/hard). Silently erasing an entered value is the one thing this mode refuses to do; fix it by picking one of the shown choices.
• Out-of-list values are out of scope. A value that is not in the field's choice list at all (e.g. a missing-data code like -99) is never flagged. Nor is a project Missing Data Code that is also one of the field's codes: the page and the server both leave such a field alone.
• Works on radio, dropdown and checkbox fields; not yes/no, true/false, sql, or matrix fields (matrix rows render different markup — the tag is refused there rather than half-working). Dropdown filtering physically removes and re-inserts s because Safari ignores CSS hiding on options. Configure via field annotation only in this version.

Dates within a window — the @UVWINDOW tag

REDCap's date validation takes a fixed minimum and maximum and only warns. @UVWINDOW checks a date against a window counted from another date of the same record, from today or from a fixed date, or against a calendar period, and/or that it is not after today or not before it:

@UVWINDOW={"from":"[visit_date_bl]","window":[21,35]}
@UVWINDOW={"from":"[dob]","window":[0,null],"notFuture":true}
@UVWINDOW={"from":"[dose_given_at]","window":[0,6],"unit":"hours","blockSave":"hard"}
@UVWINDOW={"notFuture":true}
@UVWINDOW={"notPast":true}
@UVWINDOW={"from":"today","window":[-7,0]}
@UVWINDOW={"period":"month","offset":-1}

• JSON form only. window is [earliest, latest] in whole units from the from date, both ends included; null leaves an end open and negative bounds count back. unit is days (default), weeks, months or years, and also minutes or hours on datetime fields. from is a field, today, now or a Y-M-D date. period (week, month, quarter, year) is the period holding today or the from date, moved by offset; weeks start on Monday unless the project setting "First day of the week for @UVWINDOW" or weekStart says Sunday. Optional when, message, blockSave.
• Judged on the day it was saved. A part counted from today or now, a period without from, and notPast are judged on the form only for a new or changed value, and after saving against the day REDCap's log shows the value was saved; a value the log does not show is reported as not checked. notFuture uses the save day after saving too; on the form it still flags a saved date after today, and a saved date that passes shows no "OK". Use them for timeliness; count clinical windows from a date in the record.
• Date fields only: Text fields with date, datetime or datetime-with-seconds validation, in any display format. The from field must be the same kind of date. The message names the allowed dates in the field's own format.
• Today is the server's date. The page gets the server clock and moves it forward while it stays open, so a wrong computer clock cannot accept tomorrow's date and a form left open past midnight moves to the next day. A computer clock moved forward while the form is open moves it too; the post-save audit reads the server clock and still logs the date. The project setting Time zone for @UVWINDOW "notFuture" sets the time zone, when it differs from the server's.
• Blank checks nothing. A blank field is not checked, and a date still being typed shows no verdict. A blank from date leaves the window part unchecked; notFuture and notPast still apply.
• Other forms and events. A from date on another form is read when the page opens and the window part is advisory (it never blocks); and keep their . On a survey, or without rights to that form, the value never reaches the page: the browser checks only and , and staff see a note that the window is checked on save. With event and instance references enabled, may name another event: . Its window part is advisory on the page, and and keep their . A , or a branch selector, that reads a value from another form or event makes the whole rule advisory, and included. On a multi-page survey, put the field on the same page as the date it anchors, or the window is checked only after the save.

Values that must already exist — the @UVEXISTS tag

REDCap can check that a value has the right shape, not that it refers to something that is real. @UVEXISTS checks, as the value is entered, that it is already saved in the project: a record ID, or a value of another field such as the specimen ID on the collection form.

@UVEXISTS=record
@UVEXISTS=[specimen_id]
@UVEXISTS={"in":"[specimen_id]","event":"enrolment_arm_1","scope":"dag",
           "match":{"site_code":"[site]"},"blockSave":"hard"}

• in is record (a record ID of this project) or one field reference (a value saved in that field, in any record). event looks in one event, by its unique name. scope is project (default), dag (records of the same Data Access Group; records in no group form one group) or event (the event of the entry being checked). match looks only at saved entries whose target field equals a field of this record, {"target":"[field of this record]"}, up to 5 pairs; the target values must sit in the same entry as the searched value (one event row, or one repeat instance with its event row). Optional when, message, blockSave, surveys, return and where (below).
• Comparison of stored values. Trimmed, with A-Z letter case ignored (sp-1 finds SP-1) unless the rule sets "caseSensitive":true. When the searched field holds numbers (an integer or number Text field, a calc or a slider), values compare by value: 7 finds 007. A date is compared as REDCap stores it (Y-M-D), whatever format the field shows, so the searched field and the field itself must be stored the same way: both dates, both datetimes to the minute, both datetimes to the second, both times of the same precision, or neither a date nor a time. Two number fields must use the same decimal mark. Dropdown and radio values are compared by code. @UVEXISTS=record never finds the record being edited.
• Reads only the records that hold the value. The module asks its value index which records hold the value searched (in any spelling the rule accepts), confirms them against the data table, then reads those records through REDCap and judges them. A not found reads no record. Where the index cannot answer, the module reads the searched field's rows of every record from the data table; where that cannot be read either, the searched fields of every record through REDCap, as before. A lookup in another project ("project") and a survey lookup with where skip the index (see Lookups on large projects).
• in on this form. When the searched field is on the tagged field's own form, the page sends what that field holds now, and the record being edited counts with that value, as it will once saved: a household head who types the same ID in both fields is . A rule with , , or answers when only the record being edited holds the value, and the post-save audit decides.

Numbers within plausible limits — the @UVRANGE tag

REDCap's number validation takes one minimum and one maximum and only warns. @UVRANGE checks a number against two levels of limits: a usual range, outside which the value is unusual, and a plausible range, outside which it is a typing slip:

@UVRANGE={"soft":[12,17.5],"hard":[3,25],"unit":"g/dL"}
@UVRANGE={"soft":[null,140],"softBlock":"off","hard":[40,250],"unit":"mmHg"}
@UVRANGE={"soft":[12,15.5],"hard":[3,25],"unit":"g/dL","when":"[sex]='2'"}

• JSON form only. soft and hard are [low, high], both ends included; null leaves an end open, and the soft limits must lie inside the hard ones. Outside soft, the note is amber and softBlock decides (off or confirm, default confirm). Outside hard, or not a number, the note is red and hardBlock decides (confirm or hard, default hard). blockSave is refused. Optional unit, when, message.

• Number fields: Text fields with no, integer or number validation (including comma decimals), calc fields and sliders. A calc field and a read-only field never block a save.

• Exact. Limits and values are compared as decimals, digit by digit, so 17.50 equals 17.5, and a limit is kept exactly as written, quoted or not. 1.5E1 is 15, as REDCap's number validation reads it. Thousands separators and units typed into the box are not numbers. Blank checks nothing, and so does a missing data code (UNK, -99).

• Branch by group. Several @UVRANGE tags with when give different limits by sex, age group or anything else on the form. Tags that name different growth references on one field all apply, and the worst result decides.

• The note waits. It appears when the field is left, not while a number is being typed.

• Audited. The post-save audit logs type: range with reason soft-low, soft-high, hard-low, hard-high, not-a-number or, for a growth reference, not-positive, plausible-low or plausible-high, whatever softBlock says; a growth finding carries its reference, and its z-score only where values are kept raw (a raw audit log, a scan that stores raw values). The Validation scan counts the same findings; its report (see below) labels them "Unusual value", "Implausible value", "Not a number" or "Not a positive measurement", with the limits in the detail line. Configure via field annotation only.

• Growth references. With , the limits apply to the value's z-score for the child's sex and age (or length or height), computed the way WHO's own software computes it:

How far a number may change — the @UVDELTA tag

@UVASSERT can say that a weight is not below the previous one. It cannot say how far the weight may move. @UVDELTA compares a number with an earlier value and flags a change larger than its limit:

@UVDELTA={"vs":"previous-event","maxPct":10,"unit":"kg"}
@UVDELTA={"vs":"[weight_screening]","max":5,"unit":"kg","blockSave":"confirm"}
@UVDELTA={"vs":"first-event","maxPct":15,"direction":"down"}
@UVDELTA={"vs":"previous-instance","max":0,"direction":"down"}

• JSON form only. vs names the earlier value: previous-event, previous-instance, first-event or first-instance (this field there), or any one field reference such as [weight_screening] or [baseline_arm_1][weight]. The shorthands and a reference to another event or instance need event and instance references on. max limits the change in the field's unit and maxPct as a percent of the earlier value; give one or both. direction (both, up or down) says which changes the limits apply to. Optional unit, when, message, blockSave.
• Number fields: Text fields with no, integer or number validation (including comma decimals), calc fields and sliders. The vs field must hold numbers too: a Text field with no, integer or number validation, a calc or a slider, whichever kind the tagged field is.
• Exact. The change is worked out as an exact decimal, and the percent test is |change| × 100 against maxPct × |earlier value|, with no division and no rounding. A number with an exponent is written out in full, so 1e80 against 1e100 is a real change. A value longer than 4,096 digits written out is reported as too long to compare, never judged. A limit is at most 64 characters. Long numbers are charged to the record's evaluation budget in the audit and the scan. An earlier value of 0 has no percent, so maxPct does not apply to it; "maxPct": 0 is refused for that reason (use "max": 0 for "no change").
• Nothing to compare with. A blank value, a blank earlier value and a missing data code on either side check nothing. On the first visit or the first instance there is no earlier value.
• Checked at every event. Each entry resolves its shorthand on its own, so the tag is checked at every event that holds the form, arm by arm. An event shorthand is refused when no arm has two events with the form, or when an event it names holds the form more than once (the form repeats there, or the whole event repeats); the refusal gives the shorthand's own event with an instance, [previous-event-name][weight][last-instance] or [first-event-name][weight][first-instance], when one works from every event, and no example otherwise. An instance shorthand is refused unless the form repeats at every event that holds it. A reference that always names this same entry, such as , is refused. So is one that could not be read on any save of some entry: an event, named or not, that does not hold the form; an instance of a form that does not repeat where the reference lands ( on a form held once); a relative instance ( and the like) at an event where the field's own form is held once; no instance of a form that repeats where it lands, unless it is the field's own row (its own repeating form, or a form of the same repeating event); and a relative event that finds no event from anywhere the field is entered. The refusal quotes the reference as written. When a reference is found that every event where the field is entered can read, the refusal ends with it; otherwise it lists the events and instances it tried and says none of those works. The search tries the event as written, the previous and first events (with another form, also the last), events named outright, and this event. It never offers the next event, nor, on the field's own form, the last event or a later visit named outright, since each compares with a later entry; this holds for the event as written too. For the field itself the instance must read an earlier entry where the event lands: only at the field's own event, and an instance numbered after the first only at another, at either (tried last), and never , nor at another event. It offers nothing with the and direction of another tag on the field when neither tag has a condition, or when both have one and the two could be true at once. Written back, two such tags without a condition are refused, and so are two whose conditions say the same thing, however written (keyword case, spacing, quote style, parentheses, the order of / members and of a comparison's sides aside, and letter case when neither tag is ). Two other conditions that are true at once are a runtime conflict, and the field validates nothing while both hold. Two conditions count as never true at once only when each tests one field, written without an event or instance (each checkbox box counts as its own field), for equality with a value, alone or as part of an , and no value equals both as conditions compare values. For example, and qualify, while and (numbers compare by value), and (unless both tags are ), and , and , and and do not. A tag without a condition is the fallback beside tags that have one, so the two may share a . A refused tag earlier on the field counts with the reference its own refusal suggests. A tag that failed to parse counts with the , direction and condition its JSON names, read with single or curly quotes as double quotes and without a trailing comma. Nothing is suggested beside it, and the refusal says to fix that tag first, when even that cannot be read, when the JSON names a key the tag does not take (letter case counts, so is one), or when its , or is not text or would be refused. A reference to another event or instance counts as read, since turning references on fixes it; a its do not define does not, since the is still refused with references on. So the suggestions for one field can be written back together. When the other tags hold every reference that would work, the refusal says so. An event is named outright only when every event of the field's form is in its arm: an event of another arm holds a value only for a record entered in both arms. Written by hand, such an event is accepted. A form designated at no event is said to be so.

Values entered once — the @UVWRITEONCE tag

Some answers are entered once and then left alone, such as a consent date, a randomisation arm or a baseline weight. REDCap's @READONLY stops everyone, including the first entry. @UVWRITEONCE leaves the field open until its first save of a value and locks it from then on:

@UVWRITEONCE
@UVWRITEONCE={"roles":["Data manager"]}
@UVWRITEONCE={"roles":["Data manager","PI"],"since":"2026-11-01","message":"Ask the data manager to correct this date."}

• Locked by the first save. The first save of a value that is not blank and not a missing data code locks the field, whoever makes it. A blank or a code locks nothing, so a field marked "unknown" can still be filled in later.
• Roles. roles names the user roles whose members may still change or clear the value, by the name the User Rights page shows or by the unique role name, up to 20. Letter case does not matter ("STRASSE" matches "Straße", "ÉQUIPE" matches "équipe", and "İDARE" matches "idare"), though the dotless "ı" stays a letter of its own, so "dırector" is not "director". Invisible format characters such as a zero-width space are ignored, and a run of spaces counts as one. With PHP's intl extension a name typed with combining accents also matches one typed with composed letters; without intl the two spellings differ. Each must be a role of the project. A member's change moves the lock to the new value, and clearing it releases the lock. A user whose rights in the project have expired, or whose account is suspended, holds no role. An administrator who is not a user of the project holds none either, so the lock stops them as it stops everyone else. Roles are read when the audit or the scan runs, not as they were at the save, because REDCap's log names who saved but not the role they held, and it records a change of role only as free text this check does not read. So a change counts as the role's while its maker holds the role, and as a violation once they leave it. REDCap logs a field only when its value changes, so a member who wants to keep a value that someone outside the roles saved saves the field twice: another value, then that one.
• since. A date written YYYY-MM-DD, which starts at 00:00 in the project's time zone. Saves before then lock nothing, the value held at that moment is locked from then on, and the page locks nothing before that day. Use it when the tag is added to a project that already holds data.
• Field types. Text and Notes fields (dates included), dropdown, radio, yes/no, true/false, slider and SQL fields. Not a calc or a checkbox field, nor a field with @CALCTEXT, @CALCDATE, @SETVALUE, @PREFILL or @DOWNLOAD-COUNT, whose value REDCap writes again by itself, nor a field with @RICHTEXT or an ontology search (BioPortal, FHIR or any other service), whose widget keeps its own copy of the text, nor a field another rule returns a value to.
• On the page. For everyone outside the roles the field keeps the value it opened with, with a short note under it. A text box is read-only, the radio buttons are disabled and their "reset" link hidden, the enhanced radio buttons take no clicks, the slider is disabled, and the date picker is kept from opening, with its button and REDCap's Today and Now buttons hidden. Nothing the form posts is disabled, since REDCap would then save the field blank: a dropdown or SQL field takes no clicks instead, and one whose saved code is no longer one of its choices gets that code back as an option. A change made with the keyboard or a script is undone, and the note says so. The lock touches only the field's own controls: a field embedded in its row keeps its own buttons. A survey respondent holds no role. When the user roles cannot be read the field is locked for everyone, and the note says the role could not be checked. When the saved value cannot be read the field is not locked; staff see a note saying so, and the audit still checks a change. Another rule on a locked field still shows its note. It holds the save only when it also reads a field of this form that the person can change, and only once that field has been changed on the page, a checkbox option by option. A calc, or a field with or , stands for the fields it is worked out from on this event and instance, through other calcs too. The value each field opened with is read after REDCap's own start-up on the page, once its calcs, branching and action tags have filled their fields. So a field REDCap fills as the page starts (, , , ) counts only once the person changes it, and so does a field with or . A field with or never counts, since REDCap fills it later, once the browser gives its position. A tag name inside another tag's quoted text, as in , is not read as the tag; outside quotes it is. A violation already saved when the page opened, or one between two locked fields, never holds it, whether the person clicks Save or presses Enter. A person's own first answer is locked as soon as it is saved, so after Save & Stay, or Next on a multi-page survey, going back finds it locked. The roles and never reach the page.

Values saved with a reason — the @UVJUSTIFY tag

Some values break a rule and are still right, such as a weight above the range the protocol expected for a patient who really weighs that much, or a visit outside its window because the clinic was closed. A rule that holds the save then leaves the person two choices, a wrong value or an unsaved form. @UVJUSTIFY names a second field where the reason is written. Once that field holds a reason, the field's broken rules no longer hold the save, and the audit and the scan report those findings apart from the open ones:

@UVRANGE={"hard":[30,250]} @UVJUSTIFY={"reason":"[weight_reason]"}
@UVWINDOW={"from":"[visit_date_bl]","window":[21,35],"blockSave":"hard"} @UVJUSTIFY={"reason":"[visit_late_why]","message":"Say why the visit was outside its window."}

• reason (required) names one field of the same form: a Text or Notes field, or a dropdown, radio or SQL field whose choices are the reasons you allow. Not the field itself, and no event or instance. The person must fill it in, so the module refuses the record ID field, a field REDCap fills in itself (@CALCTEXT, @CALCDATE, @DEFAULT, @SETVALUE, @PREFILL, @NOW, @TODAY and their -SERVER and -UTC forms, @USERNAME, @APPUSERNAME-APP, @LATITUDE, @LONGITUDE, @DOWNLOAD-COUNT, @LANGUAGE-CURRENT-FORM, @LANGUAGE-CURRENT-SURVEY), a field with any form of @READONLY, a field with @HIDDEN, @HIDDEN-FORM or @HIDDEN-SURVEY, which hide it where the reason is written (@HIDDEN-APP and @HIDDEN-PDF are allowed), a field that carries @UVJUSTIFY itself, which would let two fields stand for each other, a field with @UVWRITEONCE, whose reason could never be cleared, and a field another rule's "return" writes into. A tag name inside another tag's value, such as a message or a placeholder, refuses nothing.
• message is the note under the field that asks for the reason (a map of language ids to texts is accepted, as for the other tags). Without it the note reads "Fix this value, or say why it is right in" the reason field's label.
• Which rules. A reason stands for every rule of @UVALIDATE, @UVASSERT, @UVREQUIRED, @UVCHOICES, @UVWINDOW, @UVRANGE, @UVDELTA and @UVEXISTS on the field, from annotations and from the Configure dialog alike (php/modes.json "justify"). Each keeps its own when and blockSave. Never @UVUNIQUE, since a reason does not make a duplicate identifier safe, and never @UVWRITEONCE, since a reason gives no role. A @UVJUSTIFY on a field none of those rules checks, a bare @UVJUSTIFY and a second one on the field are configuration errors.
• What counts as a reason. Any value that is not blank by the test @UVREQUIRED uses: spaces, tabs, line breaks, no-break and other Unicode spaces, zero-width characters, byte-order marks, soft hyphens and other invisible characters alone give none. A missing data code gives none either, so a reason field marked "unknown" still asks for one. On the form, a reason field the person cannot see gives no reason: its row hidden by branching logic, or, for a reason field embedded in another field's label, the row it sits in. A reason stands until someone clears it, so a later, different broken value of the field saves under the same reason. Clear the reason field when the value changes for another reason.

The Validation scan — checking data that is already saved

Off until an administrator and the project both turn it on. The scan runs only while the system setting scan-system-enable-durable and the project setting scan-enable-durable are both on. Both are off by default. Until then the page shows a notice and reads no record. Live form validation, the save-time audit and the live uniqueness check run either way.

Live validation guards the form. It cannot reach values that arrived through the Data Import Tool or the API (the save-hook audit did not run for a Data Import Tool import on REDCap 17.0.6, and may not run for the API), or records entered before a rule existed. The Validation scan project page closes that gap. It runs every configured rule, of every tag and every settings rule kind, over every saved record and lists each violation, with a CSV export.

Operators: docs/INSTALL.md covers the tables, the upgrade, the crons and switching the module off.

Who may use it

The page is the "Validation scan" link on the project's left menu, shown to users with design rights. Every request from it, from Start to the download, re-checks three things.

• Design rights on the project.
• Full Data Set export rights. A run stores record values, so a user with a lower export level cannot start a scan, follow one, read its findings on screen or download them. The refusal names the export level it read. This holds for the screen and the file alike.
• Every instrument the scan reads. A rule that reads an instrument the user cannot open refuses the whole report rather than narrowing it, so no finding, count or label from that instrument is shown. Stop asks only for the instruments the rules sit on, so a user barred from an instrument that another field's rule reads can still stop a run. When the rules cannot be read just now, for example because the growth reference folder cannot be opened, the page shows no counts, and Stop asks for every instrument of the project instead.

A user in a Data Access Group scans that group only. A group whose name cannot be resolved is refused, because a scan of zero records is not a clean project. A group-scoped run shows no counts until it has confirmed which records belong to the group, and a group user is never shown a whole-project run.

How a run proceeds

Start lists the records, then checks them in batches of about three seconds, one request per batch, sent by the open page. The open page is what drives a scan. Closing it pauses the run, and Continue on a later visit carries on from the last batch saved. The page names each phase.

1. Listing the records to check. The record list is frozen a few seconds per request, so no request has to outlast PHP's time limit, however large the project.
2. Checking records. Every rule runs over every listed record, through the same dispatch the save-time audit uses (ruleFindings), so the two agree on what a violation is.
3. Checking what changed while it ran. Records created, edited or deleted during the scan are found in REDCap's log, up to a fixed point, and read again. An edited record is judged on its new values, and a deleted record leaves the run with its findings.
4. Looking for duplicate values. @UVUNIQUE needs every record, so duplicates are decided once all of them are read, within each rule's scope (project, group or event).
5. Building the summary. The counts by rule, instrument, issue and group that the findings page filters on.

The run then reads Finished. Stop asks it to end, and the page reads Stopping until it has, after which the run is reported as cancelled. A project has one active run at a time. A second tab opened on it watches, and its Continue button makes that tab the one driving the scan; the run's lease lets only one tab work it at a time. The server scans at most scan-system-max-concurrent-projects projects at once (2 by default), and a batch refused because the server is full is retried at growing intervals, up to 30 seconds.

When the project has an @UVWINDOW rule, the run freezes the date and time it was planned, in the time zone of window-timezone, and every record of the run is judged by that clock, catch-up included. A record read after midnight is judged as of the same day as the rest. The page, the findings page and the file say "Dates were judged as of" that day. On a record changed since the run was planned, a notFuture date whose save the project log cannot show may have been saved after that day. If it is later than that day but not in the future when the record is read, it is reported as not checked ("the day this value was saved is not known"), not as a date in the future.

What a finished run says

Five sentences say how much of the project a finished run covered. Each is a different claim.

The page says	It means
"Every record was checked, including changes made while it ran."	The run read every record, and every change up to a fixed point in REDCap's log.
"Every record on the opening list was checked. This server cannot prove the project did not change during the scan."	The run read its whole list, but could not prove nothing changed after it, or records changed that @UVEXISTS answers depend on.
"Some records could not be checked. This is not a complete picture of the project."	The run stopped early, or a record could not be read, held still, or examined in full.
"This scan has no record left to report on: ..."	Nothing was in scope, or every record was deleted or left the group while it ran.
"The scan failed, so it describes nothing."	The run failed.

A group-scoped run that was stopped, or expired, says so in its own words in place of the third sentence. Before it confirmed which records belong to the group it shows no counts and says "This scan was stopped before it confirmed which records belong to this Data Access Group, so it is not a complete picture of the group." After that it shows its counts and says "This scan was stopped after it confirmed which records belong to this Data Access Group, so its counts are for the group. It ended before every check had run, so it is not a complete picture of the group."

A run that an upgrade of this module ended, because the new version judges some values differently, says so in place of the last sentence, on the page and in the answer to the request that ended it: "This module was upgraded while this scan was running, and the new version judges some values differently, so the scan was ended rather than finished half under each version. Start a new scan."

A run ends as complete, partial, cancelled, failed or expired. Only a complete run can certify the project: every record checked through the fixed point, every finding kept, no open finding (a finding saved with a reason, @UVJUSTIFY, is not open), and every rule evaluated. A run that reached the limit on stored detail adds "Some findings were not kept, because the scan reached the limit this project allows." Every finished run that does not certify the project carries "This result does not certify the project." or says how many rules could not be evaluated. A run that failed, was cancelled or expired reached no decision at all, and the page reads that as not certified. It never reads it as clean, or as a sign that something was found.

An incomplete report says so three ways. The banner "INCOMPLETE SCAN - this report does NOT certify the project as clean" opens it, on the page and in the file. A terminal row, saying the scan did not cover the whole project, closes its rows; in the file it is a data row whose first cell is INCOMPLETE SCAN, so it survives deleting the comment lines or sorting the sheet. The download's file name carries a suffix, which the page states beside the download link, so a copy forwarded under its own name still says it. Renaming the file removes that mark and leaves the other two. An incomplete run's suffix starts with _INCOMPLETE and adds _CANCELLED, _FAILED, _EXPIRED, _MANIFEST_ONLY, _NO_RECORDS or _TRUNCATED as they apply. A complete run that may not be called clean gets _NOT-CERTIFIED and no banner.

The finding count. For each record, a run counts the findings of the reading it holds for that record, the stored ones and any the detail limit left out. A record that catch-up sends back to be read again keeps its findings until the new reading replaces them, and then counts once, from the new reading. If the record cannot be read again, its findings are closed and it counts nothing. A record deleted while the run went on, or moved out of the run's group, counts nothing, and its findings are closed with it. Duplicate values are counted as the run publishes each duplicate group near its end, so the count shown while a run works can rise at the end. The findings saved with a reason (@UVJUSTIFY) are counted the same way, apart from the open ones: the panel gives them as "and N saved with a reason". The findings page and the downloaded file list them among their rows, in the "Saved with a reason" column, and say how many there are: "This report holds 12 findings, 3 of them saved with a reason." on the page, and a justified_rows line beside expected_rows at the head of the file.

For a reader outside any group, the panel's count, the findings page's total and the rows of the downloaded file agree, whether the run finished or was cancelled, failed or expired. The panel adds the findings the detail limit left out, which have no row. While a run works, its count is the findings it holds so far, counted the same way. A run that existed before the upgrade to schema version 8 is counted the old way (see docs/INSTALL.md).

The detail limit. A run stores at most scan-max-detail-findings findings and scan-max-detail-bytes bytes of detail (1,000,000 and 512 MiB by default, never more than scan-system-max-detail-findings and scan-system-max-detail-bytes). Past either limit it keeps counting and stops storing, labels itself truncated, and cannot certify the project. Duplicate values are not held to the limit.

Rule problems. A rule the scan cannot evaluate is counted as a rule problem, with its reason, and a run with a rule problem does not certify the project.

The findings page

Under the panel, the page shows the current report of the reader's own scope: the newest run that completed, that no later whole-project run has replaced, and that retention is not removing. For a user outside any group that is a whole-project run; for a group user, a run of their group. A newer run that was stopped, failed or expired leaves that report current, and the page names it beside the report with a button that opens its findings. With no complete run, the page opens the newest finished one. A whole-project run that completes replaces every earlier report, group runs included, so a group user whose group's last report was replaced is told so and asked to start a scan of the group, rather than shown an empty report. The findings appear when no run of the reader's is going, and open by themselves when a run the tab is watching finishes. Earlier runs are not listed. The summary above the table says what the run covered: a run over one group says "This scan covered Data Access Group north only, not the whole project.", whoever reads it, as its file does. It also gives the day the run's dates were judged as of, as the panel does for a run it watched.

A group user's report is shown only while the group still holds what the run held. The page and the file are refused, until a new scan of the group, when the change log shows a record moved into or out of the group since the run, and when a record of the run, on the page or in the file, is now in another group or no longer in the project under its name: "a record this scan held for your Data Access Group has since been renamed or deleted, so its results no longer describe your group. Run a new scan." A rename and a deletion look the same to the module, so a deleted record refuses the report too.

Findings come 50 to a page, in the order they were stored, with "Next page" and "Previous page". The table's caption gives the page, and a line above it gives how many findings the whole report holds. Four filters narrow the table: Instrument, Reason, Check and Data Access Group. Each lists "All" and then the values the run's summary counted, with their counts; a filter with nothing to offer is not shown, and changing one starts again on page 1. A page can come back empty while later pages still hold matches. The page then reads up to four more pages, saying it is looking further, and says "No findings match these filters." only when nothing more matches. Every cell is plain text.

An incomplete report shows its banner above the table and its terminal row below it, and beside the download it says that the file name ends in the run's suffix. A group-scoped run that never confirmed its group shows only the sentence saying why, with no table, filters or download. The button "Download the whole report as a CSV file" is offered only beside a report the page has just read, and it names how many findings the report holds. The file is always the whole report: the filters narrow the table on the page, never the file.

The columns are Issue, Record, Data Access Group, Event, Instrument, Instance, Field, Field label, Value, Check, Reason code, Rule, Rule name, What is wrong and Wording from. A column that does not apply to the project's shape is absent. A classic project has no Event column, and a project without groups has no Data Access Group column. When the event map cannot be read the Event column stays, with raw event ids, and the report says why. The What is wrong sentence comes from php/messages/catalog.json, which only the server reads. The form words its own messages in js/engine.js, often with live values, so for most checks the form's sentence and the report's differ. tests/messages_fixture.json holds each pair, and its two suites fail when either side changes without the fixture. Instruments, fields and events are named as they were when the run was planned, from a snapshot kept with the run. A run planned before snapshots were kept shows today's names and says so.

The CSV file

The download is pages/export.php, which streams the stored run a page at a time and runs no scan of its own. The button posts a form with the run id and the page's redcap_csrf_token, which the module framework checks. Any other request method, such as a link, a bookmark or an address typed into the browser, is refused with HTTP 405 and a plain-text # EXPORT REFUSED answer before the run is read. It asks the same questions as the findings page. The file is UTF-8 with a byte-order mark. It opens with # lines about the report (schema, project, run, when it was generated, scope, coverage, whether it certifies, values, labels, a column legend and how many rows to expect), then a header row of column keys, then the findings. It ends on # export_complete=1 with the row count. A download cut off partway has no such line, and one whose rows could not all be read ends on a row saying rows were lost. Cells are quoted and formula-defused, and record ids follow the privacy mode the audit log uses (log-values). A refused export is plain text that starts # EXPORT REFUSED, and is never offered as a file.

Values

Whether a finding shows the offending value is the project's choice in scan-value-storage. The choices are locations only (the default), values with the fields REDCap marks as an Identifier withheld, and every value. The choice in force when a run is planned decides what the run stores. The choice in force when the report is read decides what is shown, so a tighter setting hides values at once. Redaction fails closed. A data dictionary that cannot be read withholds every value, and a field flagged as an Identifier when the run was planned, or flagged since, is withheld. A stored value keeps at most its first 255 bytes, marked when cut, for at most scan-value-retention-days days (30 by default, never more than scan-system-max-value-retention-days). A finding with no value to show, such as a blank required field, shows an empty cell.

Upkeep and retention

Two crons keep the scan's tables bounded. Each pass works in slices for a quarter of its run-time limit, carries on where the last pass stopped, and writes a scan-cron entry to the module log.

• uv_scan_reap_abandoned runs every 15 minutes. It ends a run that has made no progress for scan-system-stale-run-hours hours (24 by default) as expired, removes worker places above the concurrency limit, and closes the previous findings of each project whose latest whole-project run finished complete. Pressing Start ends an abandoned run of its own project at once.
• uv_scan_expire_values runs every hour. It clears stored values that a tightened privacy setting revoked, in the runs planned under the looser setting (a run planned under the setting now in force keeps its own), deletes finished runs older than scan-run-retention-days days (90 by default, never more than scan-system-max-run-retention-days), and clears stored values past their retention window.

Switching the module off

Disabling the module on the server stops every scan in progress and frees every worker place. Each stopped run finishes as cancelled, says the module was disabled, and keeps what it had examined. Nothing is deleted unless scan-system-drop-tables-on-disable is on; with it on, every uv_ table is dropped, with every stored scan, finding and audit row and the value index of the live lookups. Disabling the module for one project stops that project's run the same way. With scan-system-enable-durable off, a disable stops nothing, since no scan can run then.

Methods supported

ISO/IEC 7064 Mod 37,36 (default), Mod 11,10, Mod 97,10, Mod 11,2, Mod 37,2, two letters-only variants, plus Damm, Verhoeff, Luhn, four digit-only weighted-modulus schemes (GS1 Mod-10, ABA Mod-10, ICAO MRZ Mod-10, and ISBN-10 weighted Mod-11), and "none" (format/regex only). The method must match how the IDs were minted.

The four weighted-modulus schemes run over a digit payload and each add one check character (weighted_mod11 may emit X). The three Mod-10 schemes catch every single-digit error at any length but miss adjacent swaps of digits differing by 5. weighted_mod11 catches every single-digit error and every adjacent swap only up to 9 digits (the ISBN-10 domain): at 10+ digits the position carrying weight 11 goes blind to substitutions, so prefer Mod 11,2 or Mod 97,10 for longer numbers.

How it works

A REDCap admin installs the module once; each project enables it and adds rules on the settings screen. On every form and survey the module reads its settings, builds a config object, and injects js/engine.min.js, the minified build of js/engine.js (the verified engine), or the source itself while the minified copy was built from another version of it or the project's debug setting is on. A bundled growth table the page may read whole travels as its own script under js/growth/, which the browser caches. Nothing is hard-coded per project and no third-party module is required.

REDCap settings  ->  UniversalValidator.php  ->  window.INSPIRE_VALIDATOR_CONFIG
                                              ->  js/engine.js (verified engine)
                     redcap_save_record       ->  php/CheckCharacter.php (server guard)

Lookups on large projects: the value index

REDCap keeps no index on saved values, so a lookup that reads the data table reads one row per record: 3 to 9 seconds at 100,000 records on a test server whose database had 128 MB of memory for its tables, and 33 to 39 seconds at 400,000. The module therefore keeps its own index of the fields that @UVUNIQUE and @UVEXISTS search, in four tables (uv_lookup_key, uv_lookup_field, uv_lookup_sync, uv_lookup_record). They are created when the module is enabled or upgraded and when its system settings are saved, whether or not the Validation scan is on.

• Built once per field. A build reads all the field's rows once and stores one key per value and record: a hash of the value as lookups compare it (trimmed, letter case folded, numbers by value). A field of up to 20,000 saved values is built by its first lookup (one field a request). A larger one is built by the module's cron uv_lookup_index, which runs every 5 minutes: the first lookup marks the field, and until the cron has built it the lookups read the data table, as before. While the cron reads a field, the project's other fields keep answering. Where the cron has not run for 15 minutes, a lookup builds a field that has waited as long itself.
• Kept current from the log. Every value REDCap saves writes a row to the project's log. Before it answers, a lookup reads the records the log names since the last lookup and indexes them again. It also counts the log rows of the last hour again, range by range, and reads a range again when its count grew, so a row that becomes visible late (an import that commits after later saves) is still seen.
• Confirmed before use. The records the index names are checked against their current rows in the data table before any is used, so a stale key costs one row read and never a wrong answer.
• Rebuilt when it cannot be shown current: after a change to the data dictionary, a log pruned into the last hour, a move to another log or data table, more than 20,000 changed records in one stretch of the log (or 5,000 to index again), and every 7 days. After a burst of changes the rebuild waits 7.5 minutes. While a field is not built, its lookups read the data table. The cron rebuilds each field a day before its 7 days are up, and the field answers throughout: from its old keys and the new ones until the new build is complete.
• What it does not see on its own: a value written to the data table with no log row (another module's direct SQL, for example), and a log row that becomes visible more than an hour after later rows. The 7-day rebuild picks both up. The Validation scan reads the data table and is not affected.
• Not used for a lookup in another project (@UVEXISTS with "project") and a survey lookup with where; those read as before.
• Size. One row of uv_lookup_key per saved value of a searched field, about 100 bytes with its indexes. The cron drops the keys of a field no lookup has asked for in 30 days.
• Off switch. The system setting Live lookups — turn OFF the value index makes every lookup read the data table again.

Verification

Both runtimes are checked against one fixture generated by the Python source of truth (qrcode_generation/check_characters.py) — and not only the raw check-character primitive, but the full runtime path the module actually uses:

• tests/parity_js.cjs / tests/parity_php.php — recompute every fixture row across all three sections: compute (the primitive, 574 rows across 15 algorithms), normalize (Unicode dash folding / case / strip), and scheme_ops (append + validate = normalize → source → compute → compare, including every weighted scheme through digits_only and a weighted_mod11 X check tail). 918 rows total.
• tests/pooled_js.cjs / tests/pooled_php.php — recompute the pooled-field parser for every case in tests/pooled_fixture.json (frozen from the verified browser parser), so the server pooled auditor can never drift from the client.
• tests/risky_js.cjs / tests/risky_php.php — lock the catastrophic-regex (ReDoS) gate to one shared pattern list in both runtimes (nested quantifiers AND repeated alternation/optional groups such as (a|aa)+), and prove the server never turns a PCRE engine failure into a false invalid-ID log.
• tests/when_js.cjs / tests/when_php.php — lock the when condition dialect (parse errors, evaluation verdicts, referenced-field extraction, caps) to tests/when_fixture.json in both runtimes, so the browser gate and the server audit can never disagree about a condition. tests/when_dom_js.cjs drives the browser gate itself: live dropdown/radio/checkbox flips, the server-folded constants, fail-open on an unparseable condition, and the guarantee that a gated-off rule never blocks a save. tests/hook_php.php additionally asserts that no record value ever reaches the page (SEC-005), on data-entry forms and survey pages alike.
• tests/when_fuzz_php.php — the cases nobody thought of: gen_when_fuzz.cjs builds 4048 seeded conditions (valid ones from the grammar, plus mutated and hostile ones), freezes what the browser twin does with each, and the PHP engine must agree on every accept/reject, verdict and referenced-field list. This is what catches a numeric-vs-string comparison quietly drifting between the runtimes on inputs like 1e3, 0x10 or " 2 ".
• tests/branching_php.php and tests/branch_dom_js.cjs — implement the SAME branched-validation scenario table on both sides (active branch, else branch, conflicts, per-branch blockSave/suggestFix, illegal-sharing wording), with the resolver semantics specified in php/Branching.php; tests/hook_php.php additionally drives branch selection through the whole server audit. tests/pooled_dom_js.cjs locks pooled chip severity (invalid and junk red, duplicates amber) with their non-color marks.

CI (.github/workflows/parity.yml) runs the JS suite on Node 20, the PHP suite on PHP 7.4, 8.1 and 8.3 (the declared floor is exercised, not just stated), php -l-lints the PHP, checks the pooled fixture is regenerated, and builds a release-shaped package to verify its layout. If either engine drifts, CI fails. See tests/README.md.

Install

See docs/INSTALL.md, or the install page on the documentation site.

Develop

node tests/parity_js.cjs      # JS engine vs fixture (compute + normalize + scheme_ops)
php  tests/parity_php.php      # PHP port vs fixture (PHP 7.4+, needs mbstring + ctype)
node tests/pooled_js.cjs      # JS pooled parser vs pooled_fixture.json
php  tests/pooled_php.php      # PHP pooled parser vs pooled_fixture.json
node tests/risky_js.cjs       # JS ReDoS gate vs risky_patterns.json
php  tests/risky_php.php       # PHP ReDoS gate + server-behavior checks
node tests/when_js.cjs        # JS "when" evaluator vs when_fixture.json
php  tests/when_php.php        # PHP "when" evaluator vs the same fixture
node tests/gen_when_fuzz.cjs  # regenerate the seeded when-fuzz fixture
php  tests/when_fuzz_php.php   # PHP "when" engine vs the JS twin (4048 fuzz cases)
node tests/when_dom_js.cjs    # "when" gate DOM contract (live refs, folded consts, fail-open)
php  tests/branching_php.php   # branch resolver (shared fields -> branch rules)
php  tests/registry_php.php    # mode registry (php/modes.json): frozen maps, coverage, bad file
node tests/gen_mode_registry.cjs # rewrite the generated blocks in js/engine.js after editing php/modes.json or php/growth_outputs.json
node tools/build_engine_min.cjs  # rebuild js/engine.min.js after editing js/engine.js (--check: fail if stale; needs npx)
node tests/engine_min_js.cjs     # js/engine.min.js names the current source, and every browser suite passes on it
node tests/branch_dom_js.cjs  # branched validation DOM contract (active/else/conflict)
node tests/constraint_dom_js.cjs # @UVASSERT constraint DOM contract (assert test, compose, branches)
node tests/required_dom_js.cjs   # @UVREQUIRED required DOM contract (blank, when-gate, compose)
node tests/unique_dom_js.cjs     # @UVUNIQUE unique DOM contract (transport, fail-open, cache)
php  tests/unique_also_scan_php.php  # @UVUNIQUE lookups in the durable scan: settled, re-read by form, never findings
node tests/window_js.cjs         # @UVWINDOW verdict vs window_fixture.json
php  tests/window_php.php         # @UVWINDOW verdict, PHP twin, same fixture
node tests/window_dom_js.cjs     # @UVWINDOW DOM contract (messages, clock, snapshot, guard)
php  tests/window_module_php.php  # @UVWINDOW hooks, page fold, audit, scan, clock and time zone
php  tests/value_stamps_php.php   # @UVWINDOW save days read from a mock of REDCap's log
php  tests/clock_zones_php.php    # old time zone names, with and without tzdata-legacy
php  tests/exists_php.php         # @UVEXISTS grammar, hooks, endpoint, audit and scan index
php  tests/exists_cross_php.php   # @UVEXISTS in another project: agreement, rights, probe log, budgets
node tests/exists_dom_js.cjs      # @UVEXISTS DOM contract (asks on change, could-not-check, cache)
php  tests/exists_return_php.php  # @UVEXISTS "return": grammar, setup checks, endpoint values, save write, rights
node tests/exists_return_dom_js.cjs  # @UVEXISTS "return": fields filled, emptied or left on the page
php  tests/exists_where_php.php   # @UVEXISTS "where": grammar, setup checks, entry tests, confirm read, audit, scan
node tests/exists_where_dom_js.cjs   # @UVEXISTS "where": the filtered line, whereMessage and languages, surveys
php  tests/lookup_php.php         # @UVEXISTS/@UVUNIQUE comparison key vs lookup_fixture.json
node tests/lookup_js.cjs          # the same comparison key, JS twin, same fixture
node tests/range_js.cjs          # @UVRANGE verdict vs range_fixture.json
php  tests/range_php.php          # @UVRANGE verdict and grammar, PHP twin, same fixture
node tests/range_dom_js.cjs      # @UVRANGE DOM contract (note on leave, per-level block, calc)
php  tests/range_module_php.php   # @UVRANGE eligible fields, audit, scan and report detail
node tests/delta_js.cjs          # @UVDELTA verdict vs delta_fixture.json
php  tests/delta_php.php          # @UVDELTA verdict and grammar, PHP twin, same fixture
node tests/delta_dom_js.cjs      # @UVDELTA DOM contract (live vs blocks, saved vs and calc never block)
php  tests/delta_module_php.php   # @UVDELTA hooks, page fold, audit across events and instances, scan
php  tests/delta_live_twin_php.php # @UVDELTA live run sheet: every answer, from the module
node tests/delta_live_twin_js.cjs  # @UVDELTA live run sheet: every note, from the engine
python3 tests/delta_mutations.py   # @UVDELTA: every mutation must make a named suite fail
php  tests/writeonce_php.php      # @UVWRITEONCE verdict and the log reader vs writeonce_fixture.json
node tests/writeonce_dom_js.cjs   # @UVWRITEONCE page lock (read-only, nothing posted disabled, a change undone)
php  tests/writeonce_module_php.php # @UVWRITEONCE hooks, roles, page, audit, scan
php  tests/writeonce_live_twin_php.php # @UVWRITEONCE live run sheet: every answer but I4, from the module
node tests/writeonce_live_twin_js.cjs  # @UVWRITEONCE live run sheet: every lock and note, from the engine
python3 tests/writeonce_mutations.py   # @UVWRITEONCE: every mutation must make a named suite fail
php  tests/justify_php.php        # @UVJUSTIFY reason given vs justify_fixture.json, grammar, registry flags
node tests/justify_js.cjs         # @UVJUSTIFY reason given, browser twin, same fixture
node tests/justify_dom_js.cjs     # @UVJUSTIFY page: a reason releases the modes it stands for
php  tests/justify_module_php.php # @UVJUSTIFY hooks, page config, audit, legacy and durable scan
php  tests/justify_live_twin_php.php # @UVJUSTIFY live run sheet: every answer, from the module
node tests/justify_live_twin_js.cjs  # @UVJUSTIFY live run sheet: every note, hold and dialog line, from the engine
python3 tests/justify_mutations.py   # @UVJUSTIFY: every mutation must make a named suite fail
node tests/growth_js.cjs         # growth references: z-scores and outputs vs growth_fixture.json, WHO golden, R pnorm/qnorm, mpmath outputs, two parity hashes
php  tests/growth_php.php         # growth references, PHP twin, same fixture, extra folder
php  tests/growth_outputs_php.php # @UVRANGE "return" catalog: outputs, key grammar, engine copy, bad file
node tests/growth_dom_js.cjs     # growth references DOM contract (inputs, notes, withheld, no block)
php  tests/growth_module_php.php  # growth references: grammar, dictionary, page tables, audit and scan
node tests/growth_return_dom_js.cjs  # @UVRANGE "return": values written into fields on the page
php  tests/growth_return_module_php.php  # @UVRANGE "return": the save writes them once; grammar, hook, branches; the scan reports stale ones
php  tests/growth_curve_php.php   # @UVRANGE "show": chart curves within 0.5 of the exact ones, payload, span, table rows
php  tests/growth_chart_module_php.php  # @UVRANGE "show": grammar, page curves and cap; --write refreshes growth_chart_fixture.json
node tests/growth_chart_dom_js.cjs  # @UVRANGE "show": the chart and the table on the page, parity with the server, MLM
node tests/missing_codes_dom_js.cjs  # Missing Data Codes on the page, every mode
php  tests/missing_codes_php.php     # Missing Data Codes in the audit, scan, endpoints and page config
php  tests/required_pages_php.php    # @UVREQUIRED: branching logic in the audit and scan, multi-page survey conditions
php  tests/unique_scope_php.php      # @UVUNIQUE: "dag" scope with ungrouped records, "with" placement, throttle answer, one read per save
php  tests/survey_shape_php.php      # survey page config: no condition text, snapshot names or reasons; only this page's configuration errors
node tests/pooled_dom_js.cjs  # pooled chip severity colors + marks
php  tests/annotation_php.php  # @UVALIDATE parser + shared rule validator
php  tests/hook_php.php        # redcap_save_record audit path (mocked framework)
php  tests/docs_claims_php.php # scan docs name only settings, tables, crons, pages and actions that exist
node tests/a11y_dom_js.cjs    # field DOM contract (a11y, debounce, survey, readonly)
node tests/config_notice_js.cjs     # page-level config-error notice; a config of another configShape is not read
node tests/dispatch_notice_js.cjs   # dispatcher config-error routing
node tests/gen_pooled_fixture.cjs   # regenerate pooled_fixture.json after a parser change

js/engine.js is vendored from the qrcode_generation repo with a set of documented deviations (config source, UI-layer security hardening, and the INSPIREUniversalValidator namespace); see js/README.md for the authoritative list, how to re-vendor without losing them, and how the cross-repo fixture contract keeps the two repos in sync. There is also a manual REDCap test checklist in docs/TESTING.md.

Where this fits

This is the free, open-source client of an open-core system: it catches typos in the form for anyone, and the paid server features (central ID minting, printable QR label sheets, pooled multi-site audit) live behind a hosted API the module can call. The module works fully on its own without any of that.

License

MIT — see LICENSE.

For complete, copyable region/site dropdown rules, see the region/site annotation. The action-tag examples cover single/pooled alternates, autocomplete choice filtering, cross-event references, and repeating-instrument matching.