Forms rules validate the structure of form definitions including the events, forms, sections, and questions that make up a Form spec. Use them to enforce consistency in your form library or to catch problems in a study's in-progress form metadata before the data itself gets validated.
Two scopes: Standard Level and Study Level
Every Forms rule runs at one of two scopes, set on the Assignments tab. The scope determines what your rule sees and when it executes.
Scope | What it does | Use it when |
Standard Level | Runs against your custom Form standards. | Doing QC on your form library or enforcing house conventions across all Form standards. |
Study Level | Runs against a study's form spec as it's configured to a Form standard. | Validating a study's events, forms, sections, and questions during study set-up. |
For how a Forms rule gets assigned to standards and studies, see Understanding rule properties and assignments, which jumps straight to the Forms section.
The Standard Level data model
At a high level, a Standard Level Forms rule operates on a Form standard and the objects within it: events, forms, sections, and questions. Use the conceptual view below to orient yourself, then refer to the detailed data model for the exact tables and columns available in your rule.
Conceptual model
Detailed data model
The full Standard Level form data model is below. These tables are available in addition to the Standard tables (datasets, variables, and value-level metadata). See the table glossary for what each table represents.
Foreign-key columns appear in blue. The 1 and N markers indicate the cardinality of each relationship.
Note Form tables and Standard (SDTM) tables are not inherently linked. A Form standard is a source spec of an SDTM standard, but there is no foreign key joining the form tables to the standard tables. To relate a question to its SDTM target, join on the question's sdtm_target value, as shown in Example 4 below.
The Study Level data model
A Study Level Forms rule queries a study's form spec, the in-progress form metadata for a study. A study form spec is configured to a Form standard and is a source spec of the study's SDTM (Define) spec; the events, forms, sections, and questions applied to the study may differ from the standard's. The study tables below mirror the standard tables but represent the study's configured form spec.
Conceptual model
Detailed data model
The full Study Level form data model is below. See the table glossary for what each table represents.
Foreign-key columns appear in blue. The 1 and N markers indicate the cardinality of each relationship.
Note At the Study Level, events and forms are linked through the meta.study_event_form_mapping junction table rather than directly. The study form spec also carries its own controlled terminology in meta.study_form_code_list and meta.study_form_term, separate from the standard's recommended CT.
Note The Form Study tables and the Form Standard tables are not inherently linked. A study's events, forms, sections, and questions should match the standard they are configured from, but there is no foreign key joining the study_* tables to the standard_* tables. To compare them, join on the columns that identify each object in the UI (for example form_oid, form_section_oid, and name for questions), rather than on an internal id. See Example 6.
Pointing the finding: Tab and Column
The Tab and Column control where a finding takes the user. When someone clicks View Issue from the Issues tab, the validator opens the Tab you selected and highlights the cell identified by the Column. You set both in the rule's Logic section, alongside the Language.
Tab — "Select the tab being validated." The tab that View Issue opens: Events, Forms, Sections, Questions, Codelists, or Terms.
Column — "Select the column being validated." The cell that gets highlighted when the user clicks View Issue.
For a finding to land on the right row of that Tab, your SELECT statement must return the Tab's key column(s). For example, to point findings at the Forms tab, include oid in the SELECT:
Tab being validated | Must be in the SELECT |
Events |
|
Forms |
|
Sections |
|
Questions |
|
Codelists |
|
Terms |
|
Examples
Below are example rules for Target = Forms. Examples 1-4 run at the Standard Level; Example 5 and 6 run at the Study Level.
Example 1 - every question must have a description
SELECT form_oid, form_section_oid, name, description FROM meta.standard_question WHERE description IS NULL
Returns questions that have an empty description.
Example 2 - form IDs must be uppercase
SELECT f.oid FROM meta.standard_form f WHERE upper(f.oid) <> f.oid
Returns forms where the form ID is not uppercase.
Example 3 - *TESTCD codelist terms must be uppercase
SELECT t.code_list_oid, t.coded_value FROM meta.term t WHERE (UPPER(t.code_list_oid) LIKE '%TESTCD%' OR UPPER(t.code_list_oid) LIKE '%TC') AND UPPER(t.coded_value) <> t.coded_value
Returns terms in codelists whose ID (code_list_oid) contains "TESTCD" or ends in "TC" where the term value is not uppercase. This is similar to Example T2 for Terminology.
Example 4 - question length must match its target SDTM variable
SELECT q.form_oid, q.form_section_oid, q.name, q.length,
v.dataset_name AS 'SDTM Domain', v.name AS 'SDTM Variable', v.length AS 'SDTM Length'
FROM meta.standard_question q
JOIN meta.standard_variable v
ON substr(q.sdtm_target, 1, 2) = v.dataset_name
AND substr(q.sdtm_target, instr(q.sdtm_target, '.') + 1) = v.name
WHERE v.length <> q.length
Returns questions whose length doesn't match the length of the SDTM variable the question targets.
Example 5 - study forms must declare a source dataset
SELECT oid, name FROM meta.study_form WHERE source_dataset_name IS NULL
Returns study forms that have not been mapped to a source dataset. source_dataset_name is the form's link to the SDTM domain it feeds.
Example 6 - study question length must match the standard
SELECT sq.form_oid, sq.form_section_oid, sq.name,
sq.length AS 'Study Length', stq.length AS 'Standard Length'
FROM meta.study_question sq
JOIN meta.standard_question stq
ON sq.form_oid = stq.form_oid
AND sq.form_section_oid = stq.form_section_oid
AND sq.name = stq.name
WHERE sq.length <> stq.length
Returns study questions whose length differs from the matching standard question. The study and standard question tables are not inherently linked, so they are joined on the fields that identify a question across both: form_oid (Form), form_section_oid (Section), and name (ID), the columns that appear in the UI, not an internal id.
Table glossary
Each table is one kind of object you can write a rule against. The same set of objects exists at both scopes: the standard_* tables describe a Form standard, and the study_* tables describe a study's configured form spec.
Standard Level tables
Table | Represents |
| Events in a Form standard. |
| Links events to the forms that appear on them. |
| Forms in a Form standard. |
| Form sections, linked to their parent form. |
| Questions, including the SDTM target mapping ( |
| Form-level codelists (Codelists tab). |
| Terms within those codelists (Terms tab). |
| Measurement units available to questions. |
| Assigns measurement units to questions. |
Study Level tables
Table | Represents |
| Events in a study's form spec. |
| Links events to the forms that appear on them. |
| Forms in a study's form spec. |
| Form sections, linked to their parent form. |
| Questions, including |
| The study's form-level codelists (Codelists tab). |
| Terms within those codelists (Terms tab). |
| Measurement units available to questions. |
| Assigns measurement units to questions. |