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.

Download the JSONOpen it in the inspector →

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.

The top of the file
{  "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"  }}
  1. usdmVersion

    The version of the model this file follows. Required. Read it before anything else, because the JSON shape differs between major versions.

  2. systemName and systemVersion

    Optional. The tool that wrote the file. Worth recording: when two tools disagree, this says whose output you are looking at.

  3. study

    The one Study in the file. The API transfers a whole study at a time, so there is never a list here.

  4. 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.

  5. 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.

  6. 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.

In the protocolTitle page

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

StudyVersion_1, identity attributes only
{  "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"}
  1. versionIdentifier

    The protocol version this plan corresponds to.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

In the protocolTrial design

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.

One arm, one epoch, one element and the cell that joins them
{  "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"}
  1. StudyArm.type

    A coded arm type from CDISC terminology. The placebo arm in the same study carries Placebo Control Arm.

  2. 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.

  3. 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.

  4. transitionStartRule

    An element has a rule for when it begins. This one starts when the participant is randomized to EX-101.

  5. studyInterventionIds

    The treatment given during the element, by id. The intervention itself is held once, on the study version.

  6. 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.

In the protocolSchedule of activities, column heading

Week 2 Day 15 Window ± 2 days Clinic visit

Encounter_3 and Timing_3
{  "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"}
  1. 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.

  2. Encounter.scheduledAtId

    The link from the visit to its timing.

  3. Timing.type

    After, Before or Fixed Reference. Exactly one timing on a timeline is normally the fixed reference: the anchor, usually Day 1.

  4. 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.

  5. relativeToFrom

    Which ends of the two instances the duration is measured between. Start to Start is the usual choice for visits.

  6. 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.

  7. 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.

In the protocolSchedule of activities, one column

Week 2: Vital signs ✕ Adverse event review ✕ Concomitant medication review ✕

ScheduledActivityInstance_3 and one of its activities
{  "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"}
  1. epochId

    The epoch the instance falls in. This is what places the Week 2 visit under Treatment in the table header.

  2. encounterId

    Which visit this is. An instance does not have to have one: time points inside a visit are instances without their own encounter.

  3. activityIds

    The marks in the column. Each id is one X in the protocol's table.

  4. 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.

  5. 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.

In the protocolObjectives and endpoints

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.

Objective_1
{  "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"}
  1. text

    The wording of the objective. Text attributes may contain XHTML and parameter tags, so treat them as markup, not plain strings.

  2. Objective.level

    Primary, secondary or exploratory, as a code.

  3. endpoints

    Nested, because an endpoint belongs to its objective. Other objects that need an endpoint, such as an estimand, point to it by id.

  4. 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.

In the protocolInclusion criteria

2. Mean seated systolic blood pressure of 130 to 139 mmHg at screening.

EligibilityCriterion_2 and its item
{  "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"}
  1. category

    Inclusion or exclusion.

  2. identifier

    The number the criterion carries in the protocol. Inclusion and exclusion criteria are numbered separately.

  3. criterionItemId

    Points to the wording. The item is not inside the study design: it is in eligibilityCriterionItems on the study version.

  4. 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.

In the protocolStudy interventions

EX-101 10 mg tablet, taken by mouth once daily for 12 weeks.

StudyIntervention_1
{  "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"}
  1. role

    What part the intervention plays: experimental, placebo, active comparator, background, rescue and so on.

  2. duration

    How long it is given for, with a flag for whether that varies between participants.

  3. 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.

  4. 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.

In the protocolEstimands

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.

Estimand_1
{  "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"}
  1. analysisPopulationId

    The analysis population, defined once on the study design.

  2. interventionIds

    The treatments being compared.

  3. variableOfInterestId

    The endpoint the estimand is about, by id.

  4. 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.

The type of the placebo arm
{  "id": "Code_29",  "code": "C174268",  "codeSystem": "http://www.cdisc.org",  "codeSystemVersion": "2026-03-27",  "decode": "Placebo Control Arm",  "instanceType": "Code"}
  1. 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.

  2. code

    The concept code. For CDISC terminology this is an NCI Thesaurus C-code.

  3. codeSystem and codeSystemVersion

    Where the code comes from and which release. Without these a code is only a string.

  4. 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.

An encounter with one extension attribute
{  "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"}
  1. extensionAttributes

    Available on every class. It belongs to the API, not to the logical model.

  2. url

    Names the extension. Whoever defines it is expected to document what it means at or near that address.

  3. 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 previousId and nextId. 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. P14D after 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.

Keep going