USDM Validation

What are CORE rules?

USDM's UML diagram and JSON schema tell you what a valid shape looks like. They don't, by themselves, tell you whether the content makes sense — whether every arm has a cell for every epoch, whether there's exactly one primary objective, or whether a Fixed Reference timing has been given a window it shouldn't have. That's the job of CORE (Conformance Rules): a published, versioned set of business rules that CDISC's tooling can check automatically against any USDM JSON payload.

The rules themselves are published as a spreadsheet (USDM_CORE_Rules.xlsx) with one row per rule, each carrying: the rule's textual statement, its severity (Error/Warning), the entity or entities it applies to, the specific attribute(s) involved, and which USDM versions (3.0, 4.0) it applies to.

Error vs. warning

Categories of rules

Example rules, verbatim from the CORE rule set

Entity: StudyCell
"Each StudyArm must have one StudyCell for each StudyEpoch." (ERROR)
"Each combination of arm and epoch must occur no more than once within a study design." (ERROR)

Entity: Timing
"Each schedule timeline must contain at least one anchor (fixed time)." (ERROR)
"A window must not be defined for an anchor timing (i.e., type is 'Fixed Reference')." (ERROR)
"The value for each timing must be a non-negative duration specified in ISO 8601 format." (ERROR)

Entity: Objective
"Within a study design there must be exactly one objective with level 'Primary Objective'." (ERROR)

Entity: Endpoint
"Within a study design, there must be at least one endpoint with level primary." (ERROR)
"All primary endpoints must be referenced by a primary objective." (ERROR)

Entity: ScheduledDecisionInstance
"A scheduled decision instance must refer to a default condition." (ERROR)
"A scheduled decision instance is not expected to have a sub-timeline." (WARNING)

Entity: StudyRole
"There must be exactly one study role with a code of sponsor." (ERROR)
"A masking is expected to be defined for at least one study role in a study design with a blinding schema
 other than open label." (WARNING)

Notice the pattern: many rules read almost like plain English sentences, which is intentional — they need to be understandable by protocol authors and data managers, not only software engineers.

How to check your own USDM JSON

1. Start with schema/cardinality conformance — the universal "All" rules (relationships, data types, required attributes, cardinalities) catch the majority of structural mistakes first.
2. Check every StudyCell exists — for an n-arm, m-epoch design, confirm you have exactly n×m cells with no duplicates and no gaps.
3. Check your timeline has exactly the anchors it needs — at least one Fixed Reference timing, and no windows on any of them.
4. Check objective/endpoint cardinality — exactly one primary objective, at least one primary endpoint, and the cross-reference between them.
5. Check ordering chains — walk every previous/next chain and confirm there are no self-references or duplicate links.

A worked mini-audit: validating a two-arm design by hand

To make the rule categories concrete, walk through validating the Example 1 design from USDM Examples (two arms, three epochs) against just the StudyCell and Timing rule families:

1. Cell completeness: 2 arms × 3 epochs = 6 expected StudyCells. Count the actual StudyCell objects in the JSON. If you get 5, one arm/epoch combination is missing an ERROR-level violation.
2. Cell uniqueness: confirm no (armId, epochId) pair appears twice across the StudyCell array — a duplicate is also an ERROR.
3. Element completeness: confirm every StudyCell's elementIds array is non-empty.
4. Anchor presence: confirm at least one Timing in the main ScheduleTimeline has type = Fixed Reference.
5. Anchor cleanliness: confirm that anchor Timing has no windowLower/windowUpper values set.

Five checks, five minutes, and you've covered two of the highest-value rule families in the entire CORE set — because errors in Study Cells and Timing anchors are exactly the kind of mistake that silently corrupts downstream automation (a missing cell breaks SDTM TA generation; a malformed anchor breaks every relative timing calculation in the whole timeline).

Why some rules are warnings, not errors

The Error/Warning distinction reflects a judgment about certainty of harm, not importance. Compare two real rules: "Class relationships must conform with the USDM schema" is an ERROR because a schema violation makes the file literally unparseable by conformant tooling — there's no ambiguity. But "A standard code alias is not expected to be equal to the standard code" is only a WARNING, because while it's almost always a mistake (why alias a code to itself?), there's no schema reason it must be forbidden outright — a human reviewer should look at it, but automated tooling shouldn't necessarily reject the whole file over it.

CORE rules by the numbers

Frequently asked questions