USDM JSON examples
One small study, taken apart. Each example puts the wording a protocol would use next to the USDM 4.0 JSON it becomes, with a note on every line that matters. All of them are cut from a single file that validates against the official USDM schema, so the pieces fit together.
The example study
EX101-201 is a fictional phase 2 study: 2 arms, 3 epochs, 6 visits, 11 activities, 190 objects in all. The sponsor, the product and the identifiers are invented.
1. The file and the study
Every USDM file starts the same way: an outer object that names the model version and holds one study. The study itself is small. Its versions carry the content.
{ "usdmVersion": "4.0.0", "systemName": "Concordare Learn USDM", "systemVersion": "1.0", "study": { "id": "Study_1", "name": "EX101-201", "label": "EX-101 in Stage 1 Hypertension", "description": "An illustrative study written for the Concordare Learn USDM guide. The sponsor, product and identifiers are fictional.", "versions": [ … 1 StudyVersion ], "documentedBy": [ … 1 StudyDefinitionDocument ], "instanceType": "Study" }}usdmVersion
The version of the model this file follows. Required. Read it before anything else, because the JSON shape differs between major versions.
systemName and systemVersion
Optional. The tool that wrote the file. Worth recording: when two tools disagree, this says whose output you are looking at.
study
The one Study in the file. The API transfers a whole study at a time, so there is never a list here.
versions
Each StudyVersion is the plan at a point in time. Titles, identifiers, designs and amendments all live in the version, not on the study.
documentedBy
The protocol as a document: its versions and its numbered sections of text. Structured design and prose sit side by side in one file.
instanceType
Every object names its class. It is how a reader knows what it is holding without relying on where the object sits.
2. Titles and identifiers
A study has several titles and several identifiers, and USDM keeps each with the thing that gives it meaning: a title with its type, an identifier with the organization that issued it.
Protocol title: A Phase 2, Randomized, Double-Blind, Placebo-Controlled Study of EX-101 in Adults With Stage 1 Hypertension
Protocol number: EX101-201 Registry: NCT00000000 Sponsor: Example Sponsor Inc. Version: 1.0
{ "id": "StudyVersion_1", "versionIdentifier": "1.0", "titles": [ { "id": "StudyTitle_1", "text": "A Phase 2, Randomized, Double-Blind, Placebo-Controlled Study of EX-101 in Adults With Stage 1 Hypertension", "type": { "code": "C207616", "decode": "Official Study Title", … }, "instanceType": "StudyTitle" }, { "id": "StudyTitle_2", "text": "EX-101 in Stage 1 Hypertension", "type": { "code": "C207615", "decode": "Brief Study Title", … }, "instanceType": "StudyTitle" } ], "studyIdentifiers": [ { "id": "StudyIdentifier_1", "text": "EX101-201", "scopeId": "Organization_1", "instanceType": "StudyIdentifier" }, { "id": "StudyIdentifier_2", "text": "NCT00000000", "scopeId": "Organization_2", "instanceType": "StudyIdentifier" } ], "organizations": [ … 2 Organizations ], "instanceType": "StudyVersion"}versionIdentifier
The protocol version this plan corresponds to.
StudyTitle.type
A title is typed by a code. This one is the official title; the next is the brief title. A file can also carry public and scientific titles and an acronym.
StudyIdentifier.scopeId
Points to the organization that issued the identifier. Here Organization_1 is the sponsor, so EX101-201 is the sponsor's protocol number.
A second identifier
The registry number is another StudyIdentifier, scoped to the registry organization. The same pattern holds for EU CT numbers and IND numbers.
organizations
Collapsed here: the sponsor and the registry, each with a type code. Roles in the study, such as sponsor, are separate StudyRole objects that point at organizations.
3. Arms, epochs, elements and cells
The study schema, the diagram near the front of a protocol, becomes four kinds of object. Arms are the rows, epochs are the columns, and a cell is the box where one arm meets one epoch.
Participants are randomized 1:1 to EX-101 10 mg or matching placebo. The study consists of a screening period, a 12-week double-blind treatment period and a 2-week safety follow-up period.
{ "id": "StudyArm_1", "name": "EX101_10MG", "label": "EX-101 10 mg", "description": "EX-101 10 mg once daily for 12 weeks", "type": { "code": "C174266", "decode": "Investigational Arm", … }, "dataOriginDescription": "Data collected from participants in this study", "dataOriginType": { "code": "C188866", "decode": "Data Generated Within Study", … }, "instanceType": "StudyArm"}{ "id": "StudyEpoch_2", "name": "TREATMENT", "label": "Treatment", "type": { "code": "C101526", "decode": "Treatment Epoch", … }, "previousId": "StudyEpoch_1", "nextId": "StudyEpoch_3", "instanceType": "StudyEpoch"}{ "id": "StudyElement_2", "name": "EX101_TREATMENT", "label": "EX-101 treatment", "transitionStartRule": { "id": "TransitionRule_2", "name": "EX101_START", "text": "Randomized to EX-101 10 mg.", "instanceType": "TransitionRule" }, "studyInterventionIds": [ "StudyIntervention_1" ], "instanceType": "StudyElement"}{ "id": "StudyCell_2", "armId": "StudyArm_1", "epochId": "StudyEpoch_2", "elementIds": [ "StudyElement_2" ], "instanceType": "StudyCell"}StudyArm.type
A coded arm type from CDISC terminology. The placebo arm in the same study carries Placebo Control Arm.
dataOriginType
Required on every arm. It says where the arm's data comes from, which is how USDM tells a randomized arm from a historical or synthetic control.
previousId and nextId
Epochs are ordered by a linked list, not by their position in the array. This is the Treatment epoch, between Screening and Follow-up.
transitionStartRule
An element has a rule for when it begins. This one starts when the participant is randomized to EX-101.
studyInterventionIds
The treatment given during the element, by id. The intervention itself is held once, on the study version.
StudyCell
The join: this arm, in this epoch, runs these elements. Two arms and three epochs make six cells, even where both arms do the same thing.
4. A visit and when it happens
A visit is an Encounter. Its planned day and its window are not on the encounter: they are on a Timing, which measures the distance to another point on the schedule.
Week 2 Day 15 Window ± 2 days Clinic visit
{ "id": "Encounter_3", "name": "WEEK_2", "label": "Week 2", "description": "Week 2 visit", "type": { "code": "C25716", "decode": "Visit", … }, "environmentalSettings": [ { "code": "C211570", "decode": "Clinic", … } ], "contactModes": [ { "code": "C175574", "decode": "In Person", … } ], "scheduledAtId": "Timing_3", "previousId": "Encounter_2", "nextId": "Encounter_4", "instanceType": "Encounter"}{ "id": "Timing_3", "name": "WEEK_2_TIMING", "label": "Day 15", "description": "Week 2 is planned 14 days after Day 1.", "type": { "code": "C201356", "decode": "After", … }, "value": "P14D", "valueLabel": "14 days", "relativeToFrom": { "code": "C201355", "decode": "Start to Start", … }, "relativeFromScheduledInstanceId": "ScheduledActivityInstance_3", "relativeToScheduledInstanceId": "ScheduledActivityInstance_2", "windowLower": "P2D", "windowUpper": "P2D", "windowLabel": "-2..+2 days", "instanceType": "Timing"}contactModes and environmentalSettings
How and where the visit takes place, as coded values. The follow-up contact in this study is a telephone call and has no setting.
Encounter.scheduledAtId
The link from the visit to its timing.
Timing.type
After, Before or Fixed Reference. Exactly one timing on a timeline is normally the fixed reference: the anchor, usually Day 1.
value
An ISO 8601 duration. P14D is 14 days. USDM stores the distance, not the day number: 14 days after Day 1 is Day 15, and a reader has to work that out.
relativeToFrom
Which ends of the two instances the duration is measured between. Start to Start is the usual choice for visits.
relativeFrom and relativeTo
Read it as a sentence: the from instance is 14 days after the to instance. Here the Week 2 instance is 14 days after the Day 1 instance.
windowLower and windowUpper
The allowed deviation either side, again as durations. windowLabel is the same thing in words, for display.
The schedule of activities guide goes through timing in full, including visits measured from the previous visit instead of from Day 1.
5. What happens at a visit
This is the part of USDM that surprises people. An activity does not know when it happens, and a visit does not know what happens at it. A third object, the scheduled activity instance, holds both.
Week 2: Vital signs ✕ Adverse event review ✕ Concomitant medication review ✕
{ "id": "ScheduledActivityInstance_3", "name": "WEEK_2_INSTANCE", "label": "Week 2", "epochId": "StudyEpoch_2", "encounterId": "Encounter_3", "activityIds": [ "Activity_4", "Activity_10", "Activity_11" ], "defaultConditionId": "ScheduledActivityInstance_4", "instanceType": "ScheduledActivityInstance"}{ "id": "Activity_4", "name": "VITAL_SIGNS", "label": "Vital signs", "description": "Seated blood pressure and pulse after 5 minutes of rest, mean of 3 readings.", "previousId": "Activity_3", "nextId": "Activity_5", "instanceType": "Activity"}epochId
The epoch the instance falls in. This is what places the Week 2 visit under Treatment in the table header.
encounterId
Which visit this is. An instance does not have to have one: time points inside a visit are instances without their own encounter.
activityIds
The marks in the column. Each id is one X in the protocol's table.
defaultConditionId
The next step on the timeline when nothing diverts the participant. Following it from the timeline's entry point gives the order of the visits.
Activity
The activity carries its name and description and nothing about timing. The same object is referenced from every visit where vital signs are taken.
6. Objectives and endpoints
Each row of the objectives and endpoints table is one Objective with its Endpoints nested inside it.
Primary objective: To evaluate the effect of EX-101 10 mg once daily compared with placebo on seated systolic blood pressure after 12 weeks of treatment.
Primary endpoint: Change from baseline in mean seated systolic blood pressure at Week 12.
{ "id": "Objective_1", "name": "PRIMARY_OBJECTIVE", "label": "Primary objective", "text": "To evaluate the effect of EX-101 10 mg once daily compared with placebo on seated systolic blood pressure after 12 weeks of treatment.", "level": { "code": "C85826", "decode": "Primary Objective", … }, "endpoints": [ { "id": "Endpoint_1", "name": "PRIMARY_ENDPOINT", "label": "Primary endpoint", "text": "Change from baseline in mean seated systolic blood pressure at Week 12.", "purpose": "Efficacy", "level": { "code": "C94496", "decode": "Primary Endpoint", … }, "instanceType": "Endpoint" } ], "instanceType": "Objective"}text
The wording of the objective. Text attributes may contain XHTML and parameter tags, so treat them as markup, not plain strings.
Objective.level
Primary, secondary or exploratory, as a code.
endpoints
Nested, because an endpoint belongs to its objective. Other objects that need an endpoint, such as an estimand, point to it by id.
Endpoint.purpose
Free text for what the endpoint is for, such as efficacy or safety.
7. An eligibility criterion
A criterion is split in two: the criterion as it appears in this study, and the wording, which is kept separately so it can be reused.
2. Mean seated systolic blood pressure of 130 to 139 mmHg at screening.
{ "id": "EligibilityCriterion_2", "name": "IN02", "label": "Inclusion 2", "category": { "code": "C25532", "decode": "Inclusion Criteria", … }, "identifier": "2", "criterionItemId": "EligibilityCriterionItem_2", "previousId": "EligibilityCriterion_1", "nextId": "EligibilityCriterion_3", "instanceType": "EligibilityCriterion"}{ "id": "EligibilityCriterionItem_2", "name": "IN02_ITEM", "text": "Mean seated systolic blood pressure of 130 to 139 mmHg at screening.", "instanceType": "EligibilityCriterionItem"}category
Inclusion or exclusion.
identifier
The number the criterion carries in the protocol. Inclusion and exclusion criteria are numbered separately.
criterionItemId
Points to the wording. The item is not inside the study design: it is in eligibilityCriterionItems on the study version.
EligibilityCriterionItem.text
The sentence itself. A reader that wants the criteria as a list has to join each criterion to its item.
8. An intervention and how it is given
The study interventions table becomes a StudyIntervention with one or more Administrations. Numbers carry their units as coded values.
EX-101 10 mg tablet, taken by mouth once daily for 12 weeks.
{ "id": "StudyIntervention_1", "name": "EX-101", "label": "EX-101 10 mg", "description": "EX-101 10 mg tablet taken by mouth once daily for 12 weeks.", "role": { "code": "C41161", "decode": "Experimental Intervention", … }, "type": { "code": "C1909", "decode": "Pharmacologic Substance", … }, "administrations": [ { "id": "Administration_1", "name": "EX-101 10 mg once daily", "duration": { "id": "Duration_1", "text": "12 weeks", "quantity": { "id": "Quantity_1", "value": 12, "unit": { "standardCode": { "code": "C29844", "decode": "Week", … }, … }, "instanceType": "Quantity" }, "durationWillVary": false, "instanceType": "Duration" }, "route": { "standardCode": { "code": "C38288", "decode": "Oral Route of Administration", … }, … }, "frequency": { "standardCode": { "code": "C25473", "decode": "Daily", … }, … }, "dose": { "id": "Quantity_2", "value": 10, "unit": { "standardCode": { "code": "C28253", "decode": "Milligram", … }, … }, "instanceType": "Quantity" }, "instanceType": "Administration" } ], "instanceType": "StudyIntervention"}role
What part the intervention plays: experimental, placebo, active comparator, background, rescue and so on.
duration
How long it is given for, with a flag for whether that varies between participants.
route and frequency
Coded from the same CDISC codelists SDTM uses, which is part of what lets trial design datasets be generated from the design.
dose
A Quantity: a value and a unit, where the unit is a code. 10 with the code for milligram, not the string 10 mg.
9. An estimand
USDM 4.0 carries the estimand attributes of ICH E9(R1). An estimand does not repeat the endpoint or the population. It points to them.
The primary estimand is the difference between EX-101 10 mg and placebo in mean change from baseline in seated systolic blood pressure at Week 12 in the full analysis set, regardless of treatment discontinuation and as if rescue medication had not been started.
{ "id": "Estimand_1", "name": "PRIMARY_ESTIMAND", "label": "Primary estimand", "populationSummary": "Difference between EX-101 10 mg and placebo in mean change from baseline in seated systolic blood pressure at Week 12.", "analysisPopulationId": "AnalysisPopulation_1", "interventionIds": [ "StudyIntervention_1", "StudyIntervention_2" ], "variableOfInterestId": "Endpoint_1", "intercurrentEvents": [ { "id": "IntercurrentEvent_1", "name": "TREATMENT_DISCONTINUATION", "label": "Treatment discontinuation", "text": "Study intervention stopped before Week 12 for any reason.", "strategy": "Treatment policy", "instanceType": "IntercurrentEvent" }, { "id": "IntercurrentEvent_2", "name": "RESCUE_MEDICATION", "label": "Rescue medication", "text": "Antihypertensive rescue medication started before Week 12.", "strategy": "Hypothetical", "instanceType": "IntercurrentEvent" } ], "instanceType": "Estimand"}analysisPopulationId
The analysis population, defined once on the study design.
interventionIds
The treatments being compared.
variableOfInterestId
The endpoint the estimand is about, by id.
IntercurrentEvent.strategy
How each intercurrent event is handled. Stopping treatment is handled by the treatment policy strategy here, rescue medication by the hypothetical strategy.
10. A coded value
The examples above show codes on one line to save space. This is what one looks like in full. Every coded attribute in a USDM file holds an object like this.
{ "id": "Code_29", "code": "C174268", "codeSystem": "http://www.cdisc.org", "codeSystemVersion": "2026-03-27", "decode": "Placebo Control Arm", "instanceType": "Code"}id
Each Code object has its own id, even when two attributes use the same term. To compare coded values, compare code and codeSystem, not id.
code
The concept code. For CDISC terminology this is an NCI Thesaurus C-code.
codeSystem and codeSystemVersion
Where the code comes from and which release. Without these a code is only a string.
decode
The human-readable term. It is carried for convenience; the code is what identifies the concept.
11. Carrying something USDM does not define
Every object can hold extension attributes. Each is identified by a URL that the party defining it controls, and holds exactly one value. This is the standard’s own way to carry information beyond the model without breaking tools that follow it.
{ "id": "Encounter_3", "name": "WEEK_2", "label": "Week 2", "type": { "code": "C25716", "decode": "Visit", … }, "extensionAttributes": [ { "id": "ExtensionAttribute_1", "url": "https://example.org/usdm/extensions/expected-visit-duration-minutes", "valueInteger": 45, "instanceType": "ExtensionAttribute" } ], "instanceType": "Encounter"}extensionAttributes
Available on every class. It belongs to the API, not to the logical model.
url
Names the extension. Whoever defines it is expected to document what it means at or near that address.
One typed value
An extension holds one value: a string, boolean, integer, id, quantity, range, code or a nested extension class.
Extensions are only as durable as the tools that pass the file along. A tool that reads a file into its own model and writes it back out can drop attributes it does not recognise, so check that before relying on one.
Six things that go wrong when reading real files
The example file is tidy. Files in the wild are produced by authoring tools, spreadsheet converters and exports, and they are not always. These are the assumptions that break most often.
- Reading the visit for its activities. The Encounter has none. They are on the scheduled activity instances that point to it.
- Trusting array order. Epochs, encounters, activities and criteria are ordered by
previousIdandnextId. Files are often written in order, and nothing requires it. - Treating text as plain text. Criteria, objectives and narrative sections can hold XHTML. Printing them raw shows tags; stripping them carelessly merges list items into one sentence.
- Assuming references resolve. Files produced by exports and converters do contain ids that point at nothing. Check every reference before following it.
- Ignoring the version. Attribute names changed between 3.0 and 4.0. A reader written for one will quietly miss data in the other.
- Reading a day number from a duration.
P14Dafter Day 1 is Day 15, and a timing can be relative to any instance, not only the anchor.
The file inspector checks for several of these on any file you open in it.