Terminology rules validate the structure and content of controlled terminology including the codelists and terms that standardize how values are coded across a study. Use them to enforce consistency in your terminology library or to catch problems in a study's applied terminology before the data itself gets validated.
Scopes
Every Terminology 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 |
Terminology Level | Runs against your custom Terminologies. | Doing QC on your custom codelists and terms. A Terminology-level rule can only be assigned to a custom Terminology, not to a non-custom CT. |
Study Level | Runs against a study's spec, which can use custom or non-custom controlled terminology. | Enforcing conventions on a study configured to a specific CT. You can assign the rule to a non-custom CT so it runs on any study that uses it. |
For how a Terminology rule gets assigned to terminologies and studies, see Understanding rule properties and assignments, which jumps straight to the Terminology section.
Terminology Level
At a high level, a Terminology Level rule operates on the controlled terminology including its codelists and the terms within them. 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
Each table is one kind of object you can write a rule against; the column labels in brackets are how the field surfaces in the UI on the Terminology.
Foreign-key columns appear in blue. The 1 and N markers indicate the cardinality of each relationship.
Study Level
A Study Level rule queries the terminology as it is configured to a study spec, the in-progress study metadata that sits on top of a standard and its controlled terminology. The terminology applied to the study may differ from the standard's recommended terminology.
Note For ADaM specs, only the SDTM controlled terminology configured to the data package is available to your rule. ADaM controlled terminology is not available.
Conceptual model
Detailed data model
Each table is one kind of object you can write a rule against; the column labels in brackets are how the field surfaces in the rule editor and in the Change Log.
Foreign-key columns appear in blue. The 1 and N markers indicate the cardinality of each relationship.
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.
[ Add screenshot here: the Logic section showing the Tab and Column dropdowns. ]
Tab — "Select the tab being validated." For a Terminology rule the options are Codelists and 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):
Tab being validated | Must be in the SELECT |
Codelists |
|
Terms |
|
Examples
Below are example rules for Target = Terminologies.
Example 1 - submitted terminology requests must record who and when
SELECT code_list_oid, coded_value, "Date Request Submitted", "Requestor"FROM meta.terminology_termWHERE "Terminology Request Submitted" = 'Yes'AND "Date Request Submitted" IS NULL OR "Requestor" IS NULL
Returns terms where Terminology Request Submitted = Yes but Date Request Submitted and/or Requestor are empty. Terminology Request Submitted, Date Request Submitted and Requestor are all examples of spec extensions.
Example 2 - *TESTCD codelist terms must be uppercase
SELECT t.code_list_oid, t.coded_value FROM meta.define_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 (coded_value) is not all uppercase.
Table glossary
At the Terminology Level, a rule queries the controlled terminology you are editing. At the Study Level, a rule can also query the full study spec and the standard the study is configured to, so you can validate terminology in the context of how it is used. The terminology_code_list and terminology_term tables appear at both scopes but mean different things: the terminology you are editing at the Terminology Level, and the terminology configured to the study at the Study Level.
Terminology Level tables
Table | Represents |
| Codelists of the custom Terminology you are editing (Codelists tab). |
| Terms within those codelists (Terms tab). |
Study Level tables
A Study Level rule can query three groups of tables, matching the diagram above.
Configured terminology (terminology_*) — the controlled terminology configured to the study; this is what a Terminology rule validates.
Table | Represents |
| Codelists of the controlled terminology configured to the study (custom or non-custom). |
| Terms within the study's configured controlled terminology. |
Study spec (define_*) — the study's in-progress spec.
Table | Represents |
| Datasets in the study spec. |
| Variables in the study spec. |
| Value-level metadata in the study spec. |
| Computational methods in the study spec. |
| Comments in the study spec. |
| Supporting documents in the study spec. |
| Codelists in the study's Define spec. |
| Terms within those Define-spec codelists. |
| External dictionaries referenced by codelists. |
Configured standard (standard_*) — the standard the study is configured to.
Table | Represents |
| Datasets in the configured standard. |
| Variables in the configured standard. |
| Value-level metadata in the configured standard. |
| Computational methods in the configured standard. |
| Comments in the configured standard. |
| Supporting documents in the configured standard. |