Requirements¶
Requirements says what must exist before the rule is answerable at all.
If a requirement is not met the rule is skipped for that dataset. A skip is its own outcome — not a pass, not a finding, not an error — and it is reported as such.
Requirements:
Variables:
All: ["AESTDTC"]
Where Scope answers "is this rule about this dataset?", Requirements answers
"can this rule say anything useful about it?"
⛔ The one rule that matters more than the syntax¶
A requirement is for a thing whose absence means there is nothing to check — never for a thing whose absence is the defect.
A rule that reports a missing AEENDTC must not require AEENDTC. Requiring it skips the
rule on exactly the datasets it exists to judge, and a skip looks like a clean result.
# ⛔ WRONG — this rule can never fire
Requirements:
Variables:
All: ["AEENDTC"]
Check:
expression: 'empty(AEENDTC)'
Nothing errors. Nothing warns. The rule simply never reports, on every study, forever. This is the most expensive mistake in this chapter, and it is invisible from the outside.
Require what the check needs in order to ask its question. Never what the check is asking about.
Variables — four facets, ANDed¶
Requirements:
Variables:
All: ["AESTDTC", "AEENDTC"]
Any: ["AEDECOD", "AETERM"]
None: ["AEENDY"]
All_Or_None: [["VISITDY", "TV.VISITDY"]]
All four, and Scope, must hold together.
All — every entry must be present¶
The common case. Use it for the columns the check reads in order to function.
Any — an AND of ORs¶
Any is a list of groups. Each group is satisfied when at least one of its entries is
present, and all the groups must be satisfied.
Any: ["AEDECOD", "AETERM"] # ONE group: either will do
Any: [["AEDECOD", "AETERM"], ["AESTDTC", "AESTDY"]] # TWO groups: one from each
A flat list is one group. A list of lists is one group per inner list. That distinction is the whole feature, and it is easy to write the wrong one by accident.
Four shapes are rejected at load rather than interpreted:
| you write | what happens |
|---|---|
Any: ["A", ["B","C"]] |
load error — flat and nested mixed in one list |
Any: ["A"] |
load error — a group needs two or more entries; a one-entry OR is an All |
Any: [] |
load error — zero groups is unsatisfiable |
Any: AESEV |
load error — a bare scalar, not a list |
A group's failure names the group, not a variable. A group is unmet only when every entry in it is absent, so no single entry is at fault — which is why the skip reason reads differently from an
Allmiss.
None — no entry may be present¶
The rule runs only when none of the listed columns exists. Use it for a rule whose question is meaningless once a richer column is available.
⚠
Noneis rare. Measured 2026-09-25, 43 authored rules use it (e.g.CDISC-SEND-0378-A), against some 1 660 usingAll. PreferAllorAnywhere either expresses the same thing.
All_Or_None — every entry present, or none of them¶
All_Or_None is a list of groups, spelled exactly like Any. A group is satisfied when
all of its entries are present or none is. A group that is only partly present skips the
rule, and the reason names both halves:
Requirements.Variables.All_Or_None group 1 [VISITDY, TV.VISITDY] is only partly present — present: [TV.VISITDY], absent: [VISITDY]
It exists for one shape: a join key that is optional on both sides. VISITDY is permissible
in SV and in TV, so a valid study can carry it on both sides, on neither, or on one. Joined on
both, or dropped on neither, the rule is right. Carried on one side only, no row matches and every
planned visit is reported. Neither All (skips the "neither" study, which should run) nor leaving
the column undeclared (floods the one-sided study) can say what this facet says:
Requirements:
Variables:
All: ["VISITNUM", "VISIT", "TV.VISITNUM", "TV.VISIT"]
All_Or_None: [["VISITDY", "TV.VISITDY"]]
Match_Datasets:
- Name: "TV"
Keys: ["VISITNUM", "VISIT", "VISITDY"]
Write the primary's side bare and the joined side qualified, as All does it. Groups may have
more than two entries; a three-entry group needs all three or none. An entry may sit in All
and in its group — the convention for a join's first key puts it in both, so All guarantees
the bare side and the group decides the joined side.
| study | All: [VISITDY, TV.VISITDY] |
undeclared | All_Or_None: [[VISITDY, TV.VISITDY]] |
|---|---|---|---|
| both sides carry it | runs | runs | runs |
| neither side carries it | skips | runs | runs |
| one side only | skips | floods | skips |
Wildcard entries are compared resolved. A glob, a /regex/ or a marker template resolves to
the set of concrete column names it matches, and an all-present group additionally needs those
sets to be equal — [["TRTxxP", "ADSL.TRTxxP"]] runs when no TRTxxP exists anywhere or when the
same ones exist on both sides, and skips when ADSL has TRT01P only while the primary has
TRT01P and TRT02P. A literal entry takes part by presence only, so two differently named
literals can be paired. Pattern entries in one group must therefore be the same pattern on
each side — [["TRTxxP", "ADSL.TRTxxPN"]] is not guaranteed to match the same names and is
rejected at load. Every pattern matches column names ignoring case (CIT §1), but this load-time
check compares the patterns as written: a glob may differ in case between the two sides; a
marker template or a /regex/ must be spelled identically (a regex's escapes and inline flags make
its spelling significant, and a template's markers are what make it a template), and a template
with its markers upper-cased (ADSL.TRTXXP beside TRTxxP) is a literal name no dataset carries —
also rejected.
The load-time rules are Any's — flat is one group, nested is several, two distinct entries per
group, no mixed shape, a warning on an entry repeated across groups — plus three of its own:
| you write | what happens |
|---|---|
None: ["VISITDY"] and All_Or_None: [["VISITDY", "TV.VISITDY"]] |
load error — None forbids it, so the group could only ever be all-absent |
All_Or_None: [["TRTxxP", "ADSL.TRTxxPN"]] |
load error — two pattern shapes in one group are not guaranteed to resolve to the same names |
All_Or_None: [["VISITDY:N", "TV.VISITDY"]] |
load error — the facet decides presence, and a column present with the wrong type is neither present nor absent |
An entry shared with Any is legal: "these travel together" and "one of these is present" are
independent claims. The facet is evaluated after All, Any and None, so a rule whose other
facets are unmet keeps reporting exactly the reason it always did.
⛔ A group column with no
All/Anypartner is not a declaration for a filter or_matched_. When both sides are absent the rule runs — that is the point — so aMatch_Datasetsfilter or a_matched_test that reads a column declared only in a group reaches the bind with the column missing, and the engine reports the unresolvable binding as an error rather than skipping. Declaring the column inAllorAnyis what makes such a read skip — and in the first-key shape above (the key inAlland in its group) it does, because the requirement skip runs before the bind is reached. A group alone is the wrong tool for a column the check must read.⭐ Every keyed join declares its key columns this way — one group per key column, the first key also in
All— and the corpus is held to it byJoinKeyDeclarationLintTest. The convention and its reasons are in Joins — Declare the key. The engine never applies it on its own: a rule without the declaration simply runs.
How the four facets are evaluated¶
These are the confirmed semantics of the requirement gate (owner, 2026-09-28; rulings register
entry CIT §2), exactly as it evaluates a rule against a dataset:
- Order:
All, thenAny, thenNone, thenAll_Or_None. The first unmetAllentry, the first unmetAnygroup, the first presentNoneentry or the first unmetAll_Or_Nonegroup decides — its reason is the skip reason, and nothing after it is inspected. - Every entry is an existence test, and every entry matches ignoring letter case. A literal is
a name lookup. A
--entry is first resolved against the dataset's variable prefix whenever it has one, of any length: the domain code (--SEQ→AESEQ), nothing at all for aSUPP/SQdataset (--QNAM→QNAM), or an associated-persons dataset's suffix (APMH:--SEQ→MHSEQ). Only a dataset with no domain to take a prefix from leaves it unresolved; it then matches nothing inAll,AnyandNone, and is undecidable inAll_Or_None. A glob, a/regex/and a marker template such asTRTxxPare patterns, satisfied when at least one column matches them in full (trt01pandTRT02Pboth satisfyTRTxxP). - A template entry never chooses the expansion. It asks whether some member of the family
exists; it does not choose or restrict the
xx/y/wthe check expands over. The other way round does hold: when the check is itself a template, each expansion rewrites the entries (all four facets) from its own binding before they are evaluated: - an unqualified entry is rewritten only when it is the very template the check names — it
becomes the column that expansion bound (
TRTxxP:NbecomesTRT01P:N); any other unqualified template entry keeps its "at least one member" meaning; - a qualified entry is rewritten when the check names the same template, and otherwise whenever
the binding supplies every marker it carries: a check over
TRTxxPwithAll: [ADSL.TRTxxPN]requiresADSL.TRT02PNfor itsxx = 02expansion —ADSL.TRT01PNdoes not satisfy it. A qualified entry whose markers the binding does not supply, or whose variable half is a glob or/regex/, stays as written. All— every entry must have at least one match, otherwise the rule is skipped, naming the first entry that has none.Any— evaluated per group, the groups ANDed; a group is met by its first satisfied entry and unmet only when none of its entries is satisfied — each one absent, present with the wrong type (a type suffix), or undecidable (the skip names the group and its position).None— the rule is skipped when any entry is present (a literal that exists, or a pattern that some column matches). When none of the listed variables is present, the requirement is met and the rule runs. That is why a negated family test belongs here (see Wildcards).All_Or_None— evaluated per group, the groups ANDed; a group is met when every entry is present or none is, and a partly present group skips the rule, naming both halves. Pattern entries are compared resolved (the same concrete names on every side); an entry that cannot be decided skips the group rather than counting as absent.- Qualified entries (
DS.VAR) keep every semantic above on their variable half and look in that dataset. InAllandAnythe dataset must exist and carry the variable — an absent dataset skips the rule, naming the dataset. InNonean absent dataset excludes nothing: the requirement is met. Both are subject to the supplemental-qualifier pivot below. When the run cannot resolve datasets at all, a qualified entry is undecidable and skips the rule in every facet,Noneincluded. - Supplemental qualifiers count. A qualified entry whose variable half is a plain name (not a
glob,
/regex/or template) is also found as a supplemental qualifier: a row ofSUPP<dataset>—SUPPAEforAE.AETRTEM, the entry's own dataset's supplement, not the supplement of the dataset the rule runs on — whoseQNAMequals the variable name, compared as a string, exactly (aQNAMcell is a value; rulings registerCIT §3). It is looked for before a missing dataset counts as unavailable:All: [AE.AETRTEM]in a study with noAEbut aSUPPAErowQNAM = AETRTEMis met and the rule runs, andNone: [AE.AETRTEM]skips the rule wheneverSUPPAEcarries thatQNAM, with or withoutAE. A type suffix on such an entry is checked againstSUPPAE'sQVALtype. - A type suffix (
:N/:C, onAllandAnyonly) makes a present column of the wrong type a mismatch of its own; see below.
What an entry may be¶
The same vocabulary on all four facets:
| entry | means |
|---|---|
AESTDTC |
that column, literally |
--STDTC |
the domain-prefix placeholder, resolved to the dataset in hand |
SUPPAE.QNAM |
a qualified entry — that column in that dataset |
AE* |
a glob |
/^AE.*DTC$/ |
a regular expression |
TRTxxP |
a marker template — at least one column of the family (TRT01P, trt02p, …) |
Any of these may carry a type suffix — AESTDY:N,
DM.AGE:N, "/^AE.*DTC$/:C" — on the All and Any facets, and on those two only.
⭐ Every entry matches a column name ignoring letter case — a literal, a
--placeholder, a qualified name, a glob, a/regex/and a marker template such asTRTxxPalike:trt01pin a SAS dataset satisfiesTRTxxPandTRT01Pequally, and the rule then reads it under its actual name. The metadata lookups keyed by a column's name ignore case the same way — the Define-XMLItemDefand value-level (VLM) metadata behindvar_*("DEFINE")/vlm_*, and the library's metadata for a variable the IG does not list. Write entries in the CDISC upper-case spelling regardless; never rely on case to tell two columns apart. A supplemental qualifier found through the SUPP-QNAM pivot is the exception: itsQNAMis a cell value and is compared exactly (CIT §3). ⛔ This is a decision, not a default (owner, 2026-09-28; rulings register entryCIT §1): if the case rule is ever revised, it is revised for every surface at once — never for one kind of entry alone.
A qualified entry is how you require a column in a dataset other than the one the rule is running on — usually one you are about to join.
⛔ A bare entry is also how a joining rule says that a bare name means the primary. When no dataset in the rule's scope defines
Xbut a joined dataset does, a bareXin the check fails the corpus build unlessXis declared: bare inAll, bare in anAnygroup, or paired[X, J.X]in anAll_Or_Nonegroup.None, and a qualifiedJ.Xalone, do not declare it. Usually the fix is to qualify the read instead — see Joins.
Demanding a type as well as presence¶
An All or Any entry may end in a type suffix, so the entry demands that the column is
numeric or character as well as present:
Requirements:
Variables:
All:
- "AESTDY:N" # must exist AND be numeric
- "AETERM:C" # must exist AND be character
Four spellings, case-insensitive, and the short and long forms mean exactly the same thing:
| suffix | demands |
|---|---|
:N · :Num |
a numeric column |
:C · :Char |
a character column |
An unmet type is a SKIP, not a finding. The rule stands down for that dataset and the reason
names both the demanded and the actual type. This is the whole point of the feature: without it, a
rule inapplicable to a character --ORRES had only one behaviour available, and it was an
ERROR.
Use it when the rule's arithmetic or comparison only makes sense on one type. A check that does
num(--STRESN) > 0is not applicable to a character--STRESN; saying--STRESN:Nturns that from an error into an honest "not applicable".
The type is the dataset's own¶
The suffix reads DataTableColumnMeta's declared type — what the delivered data says.
⛔ Never the CDISC Library's type, and never Define-XML's. Those are different questions and the language names them apart:
var_type("LIBRARY")andvar_type("DEFINE"). If your rule is about what was promised rather than what was delivered, the suffix is the wrong tool.
A type the engine cannot classify does not block. The entry fails only on a type that positively contradicts it, so an unclassifiable column is still met.
Two cases resolve the type elsewhere:
- A qualified entry —
DM.AGE:N— takes the type from the qualifier's dataset. For a split domain, it is the type every member carrying the column agrees on; where the members disagree, the entry makes no type demand rather than guessing. - A variable delivered through the SUPP-QNAM pivot takes that
SUPPxxtable'sQVALtype, because that is how its values actually arrive.
⛔ None and All_Or_None do not accept a suffix¶
None: ["AESTDY:N"] # load error
All_Or_None: [["AESTDY:N", "DM.AGE"]] # load error
In None it would have to mean "no numeric variable of that name may be present" — which a
variable of the other type also satisfies, making the requirement meaningless. In
All_Or_None the facet decides presence, and a column that is present with the wrong type is
neither present nor absent. The loader rejects both by name.
⚠ Two entries differing only by suffix are one entry¶
Any: ["AVAL:N", "AVAL:C"] # load error
An Any group needs two or more distinct entries, and the suffix is folded when distinctness
is counted — so this is the degenerate one-column group in disguise. Read it aloud and it is just
"AVAL is present", which is an All entry.
Malformed suffixes are rejected, not guessed¶
X:, X:Z, X:NN, X:Numeric, X:Character and A:B:C are all load errors. Only a valid
trailing tag is stripped, so a colon-bearing entry is never silently read as a column named X.
The tag is removed before the entry's regex test and before the qualifier split, so it composes
with every other entry form — "/^AE.*DTC$/:C" and "TRTxxPN:N" both work.
An entry without a suffix is unchanged¶
Adding the feature changed nothing for entries that do not use it — same matching, same skip reasons, same message text.
Datasets — a whole dataset must be present¶
Requirements:
Datasets: ["DM"]
The named datasets must be present in the run. Presence is widened: a split domain counts as
present, so requiring LB is satisfied by LB1 and LB2 without naming them.
Use it when the check reaches into another dataset — a join, or a cross-dataset reference — and cannot answer anything without it.
Variable_Universe — which variables the rule iterates¶
Variable_Universe: "Define"
Data (the default when the key is absent) or Define.
It decides which set of variables a rule iterates when it walks variables rather than rows:
Data— the columns the dataset actually has. The right choice when the rule is about delivered data.Define— the variables Define-XML declares. The right choice when the rule is about what was promised: a variable declared and not delivered is visible to aDefinerule and invisible to aDataone.
Choose
Defineonly when the mismatch between promise and delivery is the point. A rule that checks values cannot use it — Define-XML declares variables, not data.
skipIfLibraryDefined¶
skipIfLibraryDefined: true
When true, the rule stands down if the CDISC Library already enforces the same constraint, so a
sponsor does not receive the same finding twice from two authorities.
Set it when your rule restates something the Library defines. Leave it absent otherwise.
Supp_Merge¶
Supp_Merge: false
Every rule reads its dataset's supplemental qualifiers as values of the parent record: a bare
name the domain does not carry resolves to the SUPP<domain> row that qualifies the record — the
same subject (USUBJID) and pool (POOLID, each blank when absent), plus IDVAR = IDVARVAL.
A blank IDVAR qualifies every record of the subject, or of the pool when USUBJID is blank and
POOLID populated; a row naming neither a subject nor a pool qualifies nothing. SENDIG makes
USUBJID and POOLID exclusive, so pooled records (blank USUBJID) never read another pool's
qualifiers, and a domain without pools reads exactly as it would keyed on USUBJID alone. The
merge serves the dataset the rule evaluates, never a dataset it reads through domain=: in
read_value(DSTERM, domain=DS, filter=…) a SUPPDS qualifier is not a column of DS. On PC
the check reads PCCALCN per record, empty(PCCALCN) is true for a record no SUPPPC row qualifies
(or whose QVAL is blank), var_exists("PCCALCN") is true as soon as any SUPPPC row carries the
name, the finding reports the qualifier's value, and a requirement naming the qualifier — bare, or
qualified such as AE.AETRTEM — is met when the SUPP-- dataset delivers it. That is the default,
and it needs no key.
A qualifier is not a variable of the domain: the variable-inventory checks (column order, variable count, lengths, the per-variable rules) see exactly the columns the domain file carries. Supplementals are the place for non-standard variables (owner, 2026-09-29), and a rule about the domain's variables must not report them.
Write Supp_Merge: false only when the rule must see the raw dataset — a rule about the
supplemental mechanism itself. It turns off both halves at once: the qualifier reads and the
existence pivot, so the rule then reads and reports exactly what the domain file carries. The
domain's own column always wins over a same-named qualifier; a SUPP-- primary is never merged.
Not yours to write¶
Requirements.Library Requirements.Define Requirements.Dictionary
These three record whether the rule needs a CDISC Library provider, a sponsor Define-XML overlay, or an external dictionary. The loader derives them from what your check actually references.
Writing them by hand is at best redundant and at worst a claim that contradicts what the rule does. State a dependency by referencing the thing, not by declaring the requirement.
Next: The check — the expression itself.