USDM UML Tutorial

Why USDM uses UML

UML (Unified Modeling Language) is a general-purpose visual modelling language intended to provide a standard way to visualize the design of a system — a graphical notation for object-oriented systems. USDM's normative form is a UML class diagram: it is the single source of truth that the JSON API, the controlled terminology, and the Implementation Guide are all derived from and must remain consistent with.

The USDM UML includes classes, attributes and relationships. Attributes and relationships carry cardinalities indicating whether 0, 1, or many instances are allowed — and learning to read those cardinalities fluently is 80% of learning to read the diagram at all.

Reading cardinality

Example from the real model: StudyVersion.titles is [1..*] — a study version must have at least one title, and can have several (official title, short title, acronym). StudyArm.populations is [0..*] — an arm can reference zero or more population definitions.

Reading inheritance (the hollow triangle)

A plain arrow with a cardinality label is an ordinary relationship — one instance pointing to another. A line ending in a hollow triangle is inheritance: the class at the triangle end is the parent, and the connected class inherits all of its attributes and relationships.

The clearest real example: ScheduledActivityInstance and ScheduledDecisionInstance both inherit from the abstract ScheduledInstance class. That's why both classes share attributes like epoch and defaultCondition without redefining them — they're inherited, not duplicated. Similarly, StudyDesignPopulation and StudyCohort both inherit from the abstract PopulationDefinition class, which is why both carry plannedAge, plannedSex, and criteria.

Naming conventions that make the model predictable

Once you know the rules, you can often guess an attribute name correctly before looking it up:

• Class names are nouns — StudyArm, Encounter, Timing.
• Every class has id for unique identification within a study.
• Relationships use singular names for one-to-one (e.g. arm on StudyCell) and plural names for one-to-many (e.g. arms on StudyDesign).
• previous / next attributes appear consistently across many classes (StudyEpoch, Encounter, Activity, NarrativeContent, EligibilityCriterion) to encode ordering — always read the same way: "the instance that comes before/after this one."
• In the API, every UML relationship name gets an Id (singular) or Ids (plural) suffix when it becomes a cross-reference — so UML's previous becomes JSON's previousId. See USDM API Tutorial.

Worked example: reading the StudyEpoch class

StudyEpoch
• id: String
• name: String
• description: String [0..1]
• label: String [0..1]
• type: Code                 ← complex datatype, controlled terminology
• previous: StudyEpoch [0..1] ← relationship to itself (ordering)
• next: StudyEpoch [0..1]
• notes: CommentAnnotation [0..*]

Reading this top to bottom: every epoch has a mandatory id and name; description and label are optional single values; type must be a coded value drawn from the SDTM Epoch Type codelist (SCREENING, TREATMENT, FOLLOW-UP, and so on); previous/next optionally point to other StudyEpoch instances to establish ordering, with no gaps expected in a well-formed design; and any number of notes can be attached.

Where to get the official diagram

CDISC publishes the current USDM UML class diagram as a PNG (plus an "informative diagram" overlaying model and API features, in PDF and OmniGraffle format) on GitHub at cdisc-org/DDF-RA. A good first exercise, taken directly from CDISC's own training curriculum, is to download that PNG and manually locate each of the ten model areas within it before trying to trace any single relationship end to end.

Common UML reading mistakes, and how to avoid them

• Confusing a relationship with containment. An arrow only means "can reference"; it says nothing about whether the JSON nests the content or cross-references it — that's an API-layer decision covered in USDM API Tutorial, not something you can read off the UML diagram alone.
• Assuming every attribute is required. Always check the cardinality bracket. A large share of USDM's real-world flexibility comes from [0..1] and [0..*] attributes that are easy to skip past if you assume everything is mandatory.
• Missing inherited attributes. If a class diagram box looks unusually short, check whether it inherits from an abstract parent (see USDM Object Model) — the "missing" attributes are usually defined once on the parent instead of repeated on every child.
• Treating Code and AliasCode as interchangeable. Code is a single code/decode/system/version tuple; AliasCode wraps a Code plus optional alternates. Confusing the two is a common source of implementation bugs when populating controlled terminology fields.

A second worked example: reading the Timing class

Once StudyEpoch feels comfortable, the next-most-valuable class to practice on is Timing, because its cardinalities carry real business meaning rather than just structural bookkeeping:

Timing
• id: String
• name: String
• type: Code                              ← Before / After / Fixed Reference
• value: String                           ← ISO 8601 duration, e.g. "P28D"
• valueLabel: String [0..1]                ← human-readable text version
• windowLower: String [0..1]               ← ISO 8601, only if type ≠ Fixed Reference
• windowUpper: String [0..1]
• windowLabel: String [0..1]
• relativeToFrom: Code [0..1]              ← Start-to-Start / End-to-Start / Start-to-End
• relativeFromScheduledInstance: ScheduledInstance [1]
• relativeToScheduledInstance: ScheduledInstance [0..1]

Notice that relativeFromScheduledInstance is cardinality [1] (always required) while relativeToScheduledInstance is [0..1] — a direct reflection of the CORE rule that a Fixed Reference (anchor) timing only needs to point to itself, while a Before/After timing needs both ends populated.

Practice exercise

Before moving on to USDM Relationships, try this: using only the UML reading rules on this page, predict what cardinality StudyDesign.arms, StudyCell.elements, and Objective.endpoints should have, then check your answer against the Object Model page or the official USDM_CT.xlsx data dictionary. If your instinct was "at least one, possibly many" for all three, you've internalized the pattern correctly — that's [1..*] in every case.

Reading tables vs. reading the diagram

In practice, most day-to-day USDM work happens against a tabular rendering of the class model (like the USDM_CT.xlsx data dictionary or this site's data tables) rather than the raw UML picture, simply because text search is faster than visual search on a diagram with well over 100 classes. The UML diagram remains essential, though, for exactly one job the table can't do well: showing you at a glance which classes cluster together and how deep a reference chain runs before you have to actually open the tabular dictionary to check details. Treat the diagram as your map, and the data dictionary as your lookup table — you'll want both open side by side for any nontrivial modeling task.

Frequently asked questions