USDM Implementation Handbook Explained

What is USDM-HB1?

USDM Implementation Handbook 1 (USDM-HB1 v1.0, Final, published June 2026 by the USDM Team) is CDISC's first use-case-specific implementation handbook built on top of USDM. Where the USDM Implementation Guide teaches the model itself, USDM-HB1 picks one concrete, high-value workflow and works through it end to end: leveraging USDM metadata to automatically construct the SDTM Trial Design Model (TDM) domains — TA, TE, TV, TI, and TS — directly from a digitized study design.

Why is a dedicated Implementation Handbook needed?

It's a fair question: CDISC already publishes the USDM Implementation Guide, a full data dictionary, and the CORE conformance rules. Why does automating one use case — SDTM Trial Design domains — need its own 46-page document on top of all that?

Because the IG and the handbook answer genuinely different questions, and neither can substitute for the other:

Without a handbook like this, three predictable things happen instead:

• Everyone reinvents the same wheel, slightly differently. Every sponsor or vendor that attempts USDM-to-TDM automation independently rediscovers the same tricky corners — how to derive TABRANCH, where TEDUR comes from, how to handle cross-version TI — usually after shipping a first version that got them wrong.
• "USDM support" stops meaning the same thing everywhere. Without a shared reference mapping and a shared set of validation rules, two tools that both claim to "generate SDTM from USDM" can produce meaningfully different, equally defensible output — which quietly undermines the entire point of a harmonised standard.
• Time-to-value stays slow. Rediscovering correct JSONata logic and the relevant CORE rule subset from scratch is exactly the kind of implementation cost DDF was created to eliminate (see Why was USDM created?) — a handbook exists so that cost is paid once, by CDISC, instead of repeatedly, by every implementer.

The "1" in USDM-HB1 is also a signal worth noticing: this is explicitly framed as the first in a series, not a one-off. The expectation is that future handbooks will take other high-value, well-scoped use cases — registry submissions, EDC set-up, feasibility — and give them the same end-to-end treatment, rather than leaving every implementer to work outward from the IG alone each time. If you read Why USDM Adoption Is Not Just a Technology Project, this is the pattern in miniature: a shared, concrete reference that lets Programming, Regulatory, and IT agree on the same implementation before anyone starts building, rather than three departments independently guessing at what "USDM-to-SDTM" should mean.

The business case: manual vs. automated

USDM-HB1 opens with a stark comparison of the current, document-based workflow against the USDM-driven future state:

The handbook is specific about why the manual version is risky, not just slow: TDM datasets are usually the first thing a regulatory reviewer looks at to understand a study's structure, so re-keying errors here create outsized compliance risk. It calls out three concrete benefits of automating the USDM-to-TDM handoff:

Crucially, the handbook frames this as a people-and-process shift as much as a technical one: "the protocol is no longer just a document; it is a structured dataset that informs the entire clinical lifecycle."

Who needs what

USDM-HB1 walks through requirements at three levels — business, user, and technical — and names six distinct stakeholder roles, each with a different reason to care:

On the upstream side, the handbook lists concrete must-haves for any "study design solution": a properly sponsor-scoped StudyIdentifier, eligibility criteria stored via EligibilityCriterion/EligibilityCriterionItem with inclusion/exclusion category and ordering, visual pathway tooling for arms/epochs/elements, full encounter/visit detail, objectives and endpoints, complete intervention details, and population/indication information — all things covered in depth on USDM Object Model and USDM Relationships.

The USDM → TDM mapping

The handbook's technical core is a field-level mapping from USDM classes to each TDM domain, maintained officially as sdtm_mapping.xlsx on CDISC's GitHub. At a structural level, it collapses to this:

Four of the five domains map cleanly from one or two USDM classes. TS is the exception — it pulls from titles, identifiers, objectives, interventions, population, and study design characteristics scattered across the whole model, which is why the handbook spends the most implementation detail on TS-specific logic (grouping, arrays, null flavors, Y/N booleans).

The handbook shows the mapping isn't just a spreadsheet lookup — it has to become executable logic. Its worked example, mapping the investigational intervention's label, translates a mapping-sheet entry into a JSONata query runnable directly against USDM API JSON:

study.versions.studyInterventions[role.code="C41161"].label

And for the notoriously fiddly sponsor STUDYID — which requires finding the one StudyIdentifier scoped to whichever Organization holds the sponsor StudyRole — the handbook gives the full chained query:

(study.versions)@$sv.$sv.studyIdentifiers[scopeId in $sv.roles[code.code="C70793"].organizationIds[0]].text

This is precisely the sponsor-role/identifier chain covered on USDM JSON Examples — seeing it appear again inside a real SDTM automation query is a good sign you've internalized the model correctly.

Domain-by-domain highlights

Validation: CORE rules that matter for TDM

USDM-HB1 doesn't just point at the full CORE rule set — it curates the subset that's specifically relevant to TDM generation, spanning both USDM-side and SDTM-side rules. A representative sample:

Every one of these should look familiar if you've worked through USDM Validation on this site — the sponsor-identifier rule (DDF00172) and the StudyCell completeness rule are exactly the checks our own downloadable sample study JSON was built and re-validated against.

Challenges: amendments, cycles, and complex designs

The handbook is refreshingly candid about where this automation gets hard:

• Amendments. A USDM API file, by definition, holds only one study version. Since TI must reflect every criterion ever effective for an enrolled subject, tooling has to ingest and diff every official version, not just the latest.
• Cycles. Oncology-style cycling (see USDM Examples for the decision-instance pattern) has no fixed upper bound at design time, so TV output has to be expanded per actual observed cycle at the end of the study, not fully pre-computed at design time.
• Unscheduled visits. These live in USDM as separate sub-timelines and must be explicitly excluded from TV, which per SDTMIG should only contain planned visits.
• Complex designs. Adaptive, multiphase, decentralized, and external-control-arm studies raise a genuine judgment call: model as one StudyDesign or several, and does that decision change how many submission packages get generated.
• Execution-dependent fields. A handful of TS parameters (actual enrollment, study start/end dates) simply don't exist until the study runs — the handbook recommends locking and validating the ~80% of TS that's design-only early, and revalidating only the execution-dependent remainder at the end.

How USDMPlay helps you actually do this

Reading a 46-page handbook is one thing; running the actual mapping against real, structurally valid USDM JSON is what makes it click. This is exactly the gap USDMPlay exists to close for the community:

Our stance is simple: the USDM ecosystem has excellent normative documents (the IG, this handbook, the CORE rules) but very few places where you can put your hands directly on a real, valid USDM JSON file and start running queries against it in minutes. That's the role USDMPlay plays in the community — not replacing CDISC's official materials, but sitting next to them as the hands-on practice ground: real downloadable JSON, worked examples for every major class group, and a growing library of query patterns lifted straight from real implementation handbooks like this one.

Frequently asked questions