USDM API and implementation

USDM is a model. What tools actually exchange is the JSON its API specification defines. This page covers that API, the rules that turn the model into a file, what else ships with the standard, and the order to tackle things in if you are building something that reads or writes USDM.

The API in one paragraph

The USDM API is published as an OpenAPI specification alongside the model. It is deliberately small: it moves a whole study at a time between systems, and defines nothing finer-grained. Version 4.0 has five operations.

MethodPathWhat it does
POST/v4/studyDefinitionsCreate a study, with everything in it, in one request.
GET/v4/studyDefinitions/{studyId}Return a whole study.
PUT/v4/studyDefinitions/{studyId}Replace a whole study.
GET/v4/studyDefinitions/{studyId}/historyReturn the history of a study.
GET/v4/studyDesignsReturn the study designs of a study.

Most people never call these endpoints. They meet the API as a file: the request and response body is the JSON document usually called a USDM file, and the specification is the nearest thing to a USDM JSON schema. The specification and the model are in the CDISC DDF-RA repository.

How the model becomes JSON

The logical model is a web of classes that refer to each other. A JSON document is a tree. The API specification sets the rules for getting from one to the other, and they explain most of what looks odd in a file.

  • Every object appears once. However many things use it, an object is written in one place and everything else refers to it.
  • It is nested in its natural parent. Where one class clearly owns another, the child is written inside the parent under the model’s attribute name.
  • Everything else points by id. Other relationships to the same object become strings holding its id, and the attribute name gains an Id or Ids suffix.
  • Shared things live higher up. Objects with no single owner, such as study interventions and biomedical concepts, are collected on the study version and referred to from the design.

An endpoint shows both forms. It is nested inside its objective, and the estimand that is about the same endpoint holds only its id.

One endpoint, nested once and referenced once
{
  "id": "Objective_1",
  "name": "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"
}

{
  "id": "Estimand_1",
  "name": "PRIMARY_ESTIMAND",
  "variableOfInterestId": "Endpoint_1",
  "analysisPopulationId": "AnalysisPopulation_1",
  "interventionIds": [
    "StudyIntervention_1",
    "StudyIntervention_2"
  ],
  "instanceType": "Estimand"
}

What the API adds to the model

  • instanceType on every object, naming its class.
  • A wrapper around the study carrying usdmVersion, which is required, and systemName and systemVersion, which are optional and say what wrote the file.
  • extensionAttributes on every object, for content the standard does not define. See the extension example.

What a sender is expected to include

Beyond the attributes each class requires, the guidance that comes with the API asks for three things in a file sent between systems: exactly one study version, at least one study design in it, and one study identifier issued by the organization that holds the sponsor role. The last is how a receiver knows which identifier is the protocol number.

Conformance rules

A JSON schema can say that an attribute is a string. It cannot say that a timeline needs an anchor, or that a code must come from a particular codelist. CDISC publishes conformance rule specifications for USDM for that purpose, as it does for its other standards. They became one of the five parts of the standard with version 4.0, and cover versions 3.0 and 4.0.

Biomedical concepts: the data layer

A schedule of activities says that vital signs are taken at Week 2. It does not say which values are recorded. Biomedical concepts fill that in, and they are what make it possible to derive a data collection build from a study design.

  • A BiomedicalConcept is one observation, such as systolic blood pressure, complete with everything needed to use it.
  • Its properties are the things recorded about it: the result, the unit, the position, the method. A study can switch an optional property off, and can narrow the allowed responses.
  • A category groups concepts, so one activity can stand for a whole panel.
  • A surrogate is a placeholder for something that is collected but has no standard concept yet.

Activities point at all three by id. Biomedical concepts are optional, so a file can be valid USDM and say nothing about the data an activity collects. If you are receiving files, ask whether they are included before planning anything that depends on them.

Mappings that ship with the standard

The release includes spreadsheets mapping USDM to the things a study definition most often has to become. They are in the mappings folder of the DDF-RA repository.

  • SDTM trial design datasets: Trial Arms, Trial Elements, Trial Visits, Trial Inclusion/Exclusion Criteria and Trial Summary.
  • ICH M11: the elements of the harmonised protocol template.
  • The TransCelerate Common Protocol Template.
  • Trial registries: ClinicalTrials.gov and the EU CTIS application.

Registry coverage is partial, because some of what a registry asks for does not exist when a study is designed. For ClinicalTrials.gov it breaks down like this:

ClinicalTrials.gov sectionAvailable from USDM
Study identificationYes
Sponsor and collaboratorsYes, with review
Study designYes
Arms, groups and interventionsYes
Outcome measuresYes
EligibilityYes
Contacts, locations and investigatorsLimited
Study descriptionNo, though protocol text can be used
Study status, oversight, conditions and keywordsNo
IPD sharing statement, referencesNo

Open resources

  • The standard itself. Model, API specification, controlled terminology and implementation guide, in the cdisc-org/DDF-RA repository.
  • A reference implementation. TransCelerate’s Study Definitions Repository is an open-source system that stores and serves study definitions through the API. Check which USDM versions the release you use supports.
  • Class libraries. Community-maintained packages on PyPI, usdm and usdm4, implement the model’s classes in Python.
  • On this site. A complete example file, the class reference, the attribute index and the file inspector.

If you are implementing USDM: an order to work in

  1. Decide which direction you are building

    Writing USDM from your own data and reading someone else's are different jobs. A writer controls the shape of the file. A reader has to accept whatever shape arrives.

  2. Pin the version, and check it on every file

    Build against one version of the model and read usdmVersion before anything else. Attribute names moved between 3.0 and 4.0, and a reader that guesses will silently miss data.

  3. Parse against the class model, not a sample file

    A sample shows one tool's habits. The model says what is required, what is optional and what each reference may point at. The object model reference on this site is generated from it.

  4. Resolve every reference before you use it

    Index objects by id, then check that each Id and Ids attribute points at something that exists and is the right kind of thing. Files from exports and converters do contain dangling references.

  5. Treat text as markup

    Criteria, objectives, endpoints and narrative sections may hold XHTML, tags and references to other objects. Decide early whether you render it, resolve it or reduce it to plain text.

  6. Work the schedule out, do not read it off

    Visit order comes from following the timeline, and visit days come from adding up timings from the anchor. Neither is stored as a number you can read directly.

  7. Run the conformance rules

    A file can match the JSON schema and still be wrong. The conformance rules are where the standard says what correct means beyond structure.

  8. Carry what you do not understand

    Keep extension attributes and unknown content intact when you pass a file on. Dropping them breaks whoever put them there.

Keep going