USDM Implementation Guide Explained

What the Implementation Guide is for

The USDM Implementation Guide (USDM-IG) is CDISC's practical companion to the UML class model. Where the UML diagram tells you the abstract structure, the IG shows you, with worked instance-level diagrams, exactly how real study content — a sponsor entry, a two-cohort eligibility design, a bioequivalence intervention, a footnote — should actually be represented in USDM. It's written for the people who have to build things: protocol/content authoring tool vendors upstream, and EDC/CTMS/TMF consumers downstream.

Document structure

The 25 USDM Features sections (4.1–4.25)

Section 4 is where almost all the practical modeling guidance lives. Its subsections, in order:

Two subsections deserve special attention for anyone building tooling: 4.14 Study Timing is the densest section in the whole guide (covering timelines, timing, decisions/branching, profiles, unscheduled visits, and timeline exits), and 4.23 Addressing Footnotes is the most immediately useful for converting a real, messy protocol into clean USDM — it enumerates roughly ten recurring footnote patterns (sub-timelines, ordering, alternative visit schedules, conditional activities, additional timepoints, alternative encounter methods, measurement specification, alternative methods, instructions, windowing, eligibility, and complex combinations) each mapped to a specific modeling solution.

Mapping to other standards (Section 7)

The IG's stated design principles

Section 4.2 of the USDM-IG lists the guiding principles behind the whole model, and they're worth reading as a group because they explain a lot of otherwise-surprising modeling choices elsewhere in the guide:

• "Try not to reinvent the wheel. At the same time, improve." — hence the deliberate alignment with SDTM, BRIDG, PRM, and SDM-XML rather than a from-scratch model.
• "Do not recreate the paper world." — the model represents facts, not document formatting.
• "Be aware of model versus presentation." — a recurring theme across the Activity, NarrativeContent, and Timing classes, all of which separate the underlying data from how it's eventually rendered.
• "The model should not prevent implementors from extending the model." — the direct justification for the API's extension mechanism (see USDM API Tutorial).
• "Support the whole protocol document." — the reason NarrativeContent and unstructured content exist at all, rather than USDM covering only the "structured-looking" parts of a protocol.

How the IG documents each feature: the instance-diagram pattern

Nearly every one of the 25 subsections in Section 4 follows the same teaching pattern, which is worth recognizing so you can navigate the document efficiently: a short paragraph of prose explaining the concept, followed by a UML excerpt showing the relevant classes, followed by one or more instance diagrams showing realistic, filled-in example data. The IG is explicit and consistent in noting that every instance diagram shows only "a single use case" and does not necessarily include every required attribute or relationship — a caveat worth remembering before treating any one diagram as a copy-paste template.

Section 5's data dictionary: how to actually use it

Section 5 (USDM Data Dictionary) is a single long reference table, one row per class attribute, with columns for the attribute's data type, its NCI C-code, its CDISC preferred term, and its formal definition. It exists specifically so implementers don't have to reverse-engineer a definition from the UML diagram's short label — every attribute that isn't purely a relationship or identifier has a citable, versioned definition here. This table is also the authoritative cross-reference between USDM's internal naming and the underlying NCI Thesaurus concept codes used throughout CDISC Controlled Terminology.

Reading the IG efficiently: a suggested order

At 119 pages, the IG rewards a non-linear reading order for most practical purposes: (1) skim Section 2 (Fundamentals) once for scope; (2) read Section 4 fully, since it's the practical heart of the document; (3) treat Section 5 (Data Dictionary) as a lookup reference, not linear reading; (4) read Section 6 (API) once you're ready to actually produce JSON; (5) read Section 7 (Mappings) only for the specific target standard you're integrating with. This ordering mirrors the learning path on USDM Tutorial.

The appendices, briefly

The five appendices are short but worth knowing about: Appendix A lists the USDM development team, useful for understanding who to credit or contact through official CDISC channels; Appendix B is a glossary and abbreviations list covering both DDF-specific and general clinical-research acronyms; Appendix C lists the numbered references cited throughout the IG (ICH guidelines, ISO standards); Appendix D is the document's own revision history, tracking every prior IG version and its publication date; and Appendix E carries the standard representations, warranties, and disclaimers language required of a CDISC standards document.

What the IG assumes you already know

The USDM-IG is not a from-zero tutorial — it assumes working familiarity with clinical trial protocols and at least passing familiarity with CDISC standards concepts (controlled terminology, SDTM's general shape). If you're arriving with no CDISC background at all, start with What is USDM? and USDM Object Model on this site first, then return to the official IG once the backbone and ten model areas feel familiar — the IG's instance diagrams will make substantially more sense once you already recognize the classes they're built from.

Frequently asked questions