USDM Relationships

Arm × Epoch = Cell

The single most important relationship pattern in USDM is the Study Cell: it is the intersection of exactly one StudyArm and one StudyEpoch. If your design has 2 arms and 3 epochs, you have (at minimum) 6 Study Cells — every arm needs one cell for every epoch, and each arm/epoch combination should occur no more than once within a study design (this is an actual CORE conformance rule).

Cell → Element: what actually happens

A Study Cell by itself only says where in the design grid you are (which arm, which epoch). The content — the treatment strategy actually applied — lives in one or more StudyElement instances the cell points to. A Study Element carries a transitionStartRule and transitionEndRule (plain-text entry/exit conditions, e.g. "Signing of informed consent" → "Hospitalization for study treatment") and, optionally, references to one or more StudyInterventions actually administered during that element.

Elements are commonly reused: the same "Follow-up" element might be pointed to by the Follow-up-epoch cell of every arm, since the follow-up procedure doesn't differ by treatment assignment. This reuse is a deliberate design feature, not an edge case — it keeps the design DRY (define once, reference everywhere) exactly the way a well-normalized database would.

Encounter ↔ Epoch, and Encounter ↔ Timeline

A StudyEpoch is a period of time; an Encounter is an actual visit or contact that happens within that period. The connection between them is made through the timeline: each ScheduledActivityInstance in a ScheduleTimeline points to both an epoch and an encounter — which is exactly how USDM keeps the high-level design (arms/epochs) linked to the detailed visit-by-visit schedule.

Encounters also order themselves the same way epochs do — via previous/next — and separately carry their own scheduling detail through scheduledAt, a reference to a Timing instance.

Timing relationships: how two visits relate in time

Every Timing instance connects exactly two ScheduledInstances — a relativeFromScheduledInstance and a relativeToScheduledInstance — with a type (Before, After, or Fixed Reference) and a value in ISO 8601 format (e.g. P28D for 28 days, PT2H for 2 hours). Read it as: "the <relativeFrom> node is <value> <type: before/after> the <relativeTo> node."

Every schedule timeline must contain at least one anchor — a Timing with type = Fixed Reference — against which all other timings, directly or indirectly, relate. Windows (windowLower / windowUpper) describe how much variance around the exact value is acceptable, and must never be defined on an anchor timing itself. See USDM JSON Examples for a full worked Timing payload.

Ordering relationships: previous / next, everywhere

USDM repeats the same ordering pattern across many unrelated classes: StudyEpoch, Encounter, Activity, NarrativeContent, and EligibilityCriterion all use previous/next relationships to define presentation order. This is deliberate consistency: once you understand how ordering works for one of these classes, you understand it for all of them. Conformance rules reinforce the pattern — no instance may reference itself as its own previous or next, and the same instance can't be referenced twice as a previous or next within the same set.

Relationship cardinality cheat sheet

Pulling the exact cardinalities for the relationships covered on this page directly from the model, in one place:

Two relationship pitfalls worth calling out explicitly

Pitfall 1 — forgetting a cell. A CORE conformance rule states that each StudyArm must have one StudyCell for each StudyEpoch, and each arm/epoch combination must occur no more than once. It's easy, when hand-authoring JSON, to add a new epoch late in the design process and forget to add the corresponding cell for every existing arm — this is one of the most common validation failures in practice. See USDM Validation.

Pitfall 2 — anchoring a timeline incorrectly. Every schedule timeline must contain at least one anchor (a Timing with type = Fixed Reference), and that anchor's relativeFrom and relativeTo must point to the same instance, with no window defined. A frequent authoring mistake is giving the anchor a window (copied from a neighboring Before/After timing) or pointing its relativeTo at a different instance than its relativeFrom — both are explicit CORE rule violations.

How relationships chain together across a full visit

To see all five relationships covered on this page work together, trace a single visit end to end: an Encounter ("Day 8") belongs to a StudyEpoch ("Treatment") → that epoch, combined with a StudyArm ("Arm A"), identifies a StudyCell → that cell points to a StudyElement describing the treatment strategy in force → meanwhile, a ScheduledActivityInstance in the main ScheduleTimeline references both the Encounter and the Epoch directly, and is connected to the previous visit's instance via a Timing of type "After," value P7D. Every one of those seven objects is a small, independently-validatable piece — but together they answer the single question a Schedule of Activities exists to answer: what happens, to whom, and when.

Relationships you'll use less often, but should still recognize

Beyond the five core relationships above, a handful of secondary relationship patterns appear often enough to be worth naming: Activity.timeline connects an activity directly to a sub-timeline (used for repeated-measure sequences, see USDM Examples); StudyIntervention to Administration to AdministrableProduct forms the intervention chain used by dosing-detail modeling; and Condition.appliesTo plus Condition.context together locate exactly where a footnote indicator should appear and exactly what it applies to in the Schedule of Activities. None of these require new reading skills beyond what's already covered here — they're the same reference/cardinality/ordering patterns applied to different class pairs.

Frequently asked questions