USDM Examples

Example 1: A parallel two-arm design

This is the canonical "hello world" of USDM: a Phase 1, two-arm, parallel design with three epochs (Screening, Treatment, Follow-up). It exercises exactly the relationships covered in USDM Relationships.

The design needs: 2 StudyArms, 3 StudyEpochs (chained with previous/next), 6 StudyCells (one per arm/epoch pair), and 4 StudyElements (Screening, Drug, Placebo, Follow-up — Screening and Follow-up are reused across both arms). Download the complete worked JSON below to see every id and cross-reference filled in.

Example 2: Schedule of Activities with a PK sub-timeline

A common real-world complication: a protocol footnote says "PK blood samples: predose, 1h post-dose, 24h post-dose" for a single visit. Flattening that into the main timeline as three separate visits would be wrong — it's really one visit (Dosing Day) with a nested sequence of sample timepoints. USDM's answer is a sub-timeline: a second ScheduleTimeline, referenced from the main timeline's ScheduledActivityInstance (or directly from the Activity), with its own independent set of instances and timings.

Inside the sub-timeline, the dosing instance acts as the anchor (type = Fixed Reference, value P0D), the predose sample is Before dosing by PT30M with a 10-minute lower window, and the two post-dose samples are After dosing by PT1H and P1D respectively. This is exactly the pattern used for triplicate ECGs, serial PK profiles, and repeated vitals measurements in cross-over designs — define the sequence once as a reusable sub-timeline, then reference it wherever it recurs.

Example 3: A conditional visit (decision branching)

Suppose a protocol footnote reads: "If subject does not have mutation X, Visit 8 is not required." In USDM this is modeled with a ScheduledDecisionInstance inserted into the main timeline in place of a plain ScheduledActivityInstance. It carries a defaultCondition (the normal next step) and one or more ConditionAssignments describing alternative routes — for example, "no mutation X" → skip directly to the follow-up scheduled instance, bypassing Visit 8 entirely.

This same mechanism handles oncology-style treatment cycles: a decision instance checks "eligible to continue cycle?" and either loops back to the start of the cycle's activities or exits to the next timeline segment when the stopping condition is met.

Download the worked examples

Example 4: A cross-over design with a reusable PK profile

Cross-over trials are a good test of USDM's reuse features because the same assessment profile typically repeats identically in every treatment period. Consider a two-period cross-over where each period requires an identical set of PK sample timepoints relative to that period's own dosing event. Rather than defining the PK sub-timeline twice, you define it once as a named ScheduleTimeline, then reference it from the ScheduledActivityInstance (or Activity) representing dosing in both Period 1 and Period 2. Each reference re-triggers the same relative timing pattern (predose, 1h, 24h) against that period's own local anchor — the sub-timeline's internal timings never need to know which period they're being used in, because they're all relative, not absolute.

Example 5: Multiple cohorts sharing a single StudyDesignPopulation

A common complex-design pattern from the Implementation Guide: a Phase 2 basket-style design with three cohorts, where most eligibility criteria apply to the whole population, but two criteria (say, EX02 and EX03) apply only to two of the three cohorts. USDM handles this by letting each EligibilityCriterion be referenced from either the StudyDesignPopulation (if it applies to everyone) or from the specific StudyCohort instances it actually applies to — never both. This lets a single set of unique criterion text definitions (stored independently) serve a design with any number of cohorts, with each cohort's specific eligibility profile expressed purely through which criteria it references.

What these five examples have in common

Every example on this page follows the same underlying discipline: define shared content once, and reference it from every place that needs it. Whether that's a reused Study Element (Example 1), a reused sub-timeline (Examples 2 and 4), a decision instance instead of duplicated branches (Example 3), or a shared eligibility criterion pool (Example 5), the pattern is identical. If you find yourself copy-pasting the same block of USDM JSON to represent something that's conceptually the same thing occurring twice, that's usually a signal to introduce a reference instead — it's very rarely what a well-formed USDM design actually needs.

Common authoring mistakes across all five examples

• Flattening a sub-timeline into the main timeline. The PK sample sequence in Example 2 should never become three separate top-level visits — that loses the fact they're all part of one dosing encounter.
• Hard-coding what should be a decision. If a visit only sometimes happens, model it with a ScheduledDecisionInstance and condition rather than simply omitting the visit for some arms and hoping downstream tooling infers the logic correctly.
• Duplicating criteria text per cohort. When the same eligibility rule genuinely applies to two of three cohorts, reference the one existing EligibilityCriterion from both cohorts — don't create near-duplicate criterion text for each.
• Forgetting the anchor. Every timeline, including every sub-timeline, needs its own Fixed Reference anchor — a sub-timeline is not automatically anchored to the main timeline's anchor.

From example to your own protocol

The fastest way to internalize these patterns is to pick one visit from a real protocol you know well and model it fully — Encounter, ScheduledActivityInstance, Timing, and the Activities it contains — before attempting a whole study. Once one visit is right, extending to a full Schedule of Activities is mostly repetition of the same pattern, not new modeling concepts.

Frequently asked questions