You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 22 Next »

CDISC, in continued collaboration with TransCelerate’s Digital Data Flow Project, has updated the USDM reference architecture, which will serve as a standard model for the development of a Study Definitions Repository. The Repository is a novel central component aimed at facilitating the exchange of structured study definitions across clinical systems using technical and data standards. CDISC invites you to submit comments on the draft v3.0 of the Unified Study Definitions Model (USDM) during the 30-day Public Review period.

The focus of Phase 3 is:

  • Representation of draft ICH M11 CeSHarP (Clinical electronic Structured Harmonised Protocol) elements in USDM
  • Addition of elements to the USDM to demonstrate automated population of selected SDTM Trial Design datasets
  • Addition of elements to the USDM to demonstrate automated population of selected Clinical Trial Registry fields
  • Updates to the USDM to cater for more Complex Studies/Cohort Studies
  • USDM Model Enhancements

Deliverables include a logical data model, supporting Controlled Terminology, API specifications, and an associated Implementation Guide. 

Public Review Dates

Public Review Comment Period Start: Tuesday  

Public Review Comment Period End: Thursday 

Comments received after may not be addressed during the public review period but will be deferred to the next version of the USDM.

Please direct any questions to John Owen  (jowen@cdisc.org)

Instructions for Public Review

  1. Familiarise yourself with the Digital Data Flow Project:
    1. Listen to the  Webinar linked in the Public Review Webinar section below.
    2. If needed, familiarise yourself with the DDF project and USDM using the information found in the Other USDM Resources section below.
  2. Review the USDM materials (UML diagram, Controlled Terminology, API, USDMIG) provided in the Location of Materials for Public Review section below
    1. Either review the materials on-line in the USDM GitHub and USDMIG WIKI sites.
    2. Or download the zip file.
  3. Enter any review comments into JIRA using the instructions in the following sections below:

    1. Instructions to create a JIRA comment for the USDM Implementation Guide section

    2. Instructions to create a JIRA comment for the UML, CT and API Deliverables section

Location of Materials for Public Review

There are two ways to view the USDM materials for Public Review.

The first is to use the table below to navigate to the CDISC USDM GitHub and CDISC USDMIG Wiki site using the table below.

USDM ArtefactLocationNotes
USDM UML Logical Model
  • The public review version of the UML diagram is available on the USDM GitHub site
  • An informative version of the USDM UML is available here
  • A list of UML model changes between USDM v2.0 and USDM v3.0 is available here
  • Smaller sub views of the model can be found here
  • If you are unfamiliar with UML, Section 5.6 of the BRIDG Users Guide might be used as a model for a “Basics of UML” guide for DDF

Unified Study Definition Model (USDM) Class Diagram

The USDM Class Diagram is a UML class diagram that functions as the Study Definitions logical data model (LDM). The class diagram as LDM depicts the classes and attributes that represent data entities and the relationships between those entities needed to support a conformant Study Definitions application. The class diagram includes a data dictionary that defines each of the classes and attributes to provide the semantics needed to implement the model consistently.

The purpose of the LDM is to provide a normative standard to the solution implementer in order for them to create and implement a physical model. The LDM does not attempt to be inclusive of every class, attribute, and relationship implemented by any given solution. Instead, the LDM describes all elements for a conformant solution based on Release 1 and 2. It provides input into the solution architecture with the expectation that every effort will be made to ensure the solution architecture aligns with the RA LDM. The LDM represented by the class diagram may be implemented in a variety of physical data stores, including relational databases, property graph databases, RDF triple stores, document databases, and others. The semantics represented in the LDM and its data dictionary support a uniform understanding of the Study Definition data elements to improve interoperability. The LDM will be used to define the resources available in the API specification, and these resource definitions represent the data exchange format for applications implementing the API.

The class diagram references both CDISC and non-CDISC industry standards and terminology systems where relevant. It will be developed for compatibility with all other existing CDISC Standards that model protocol concepts, to ensure consistent terminology and relationships are used in USDM. Where the class diagram references external standards, CDISC will document these connections in order to help explain to the user community the provenance of the links. For example, the Study Definition class diagram includes references to new CDISC Biomedical Concepts, CDISC foundational standards, as well as CDISC controlled terminology. The data dictionary built into the class diagram will include references to the CDISC Library for retrieval of all CDISC content. Content from other standards and terminology systems will be incorporated where appropriate into the LDM, such as HL7, LOINC, Common Protocol Template, ICH M11, and others, either directly or through external linking, with the intention of extending interoperability in the future to data exchange standards such as HL7 FHIR. The class diagram also depicts essential elements of a study protocol including but not limited to study objectives, endpoints, and the schedule of activities (SoA).

USDM Controlled Terminology
  • The public review version of the Controlled Terminology (CT) is available on the USDM GitHub site


  • A list of CT changes between USDM v2.0 and USDM v3.0 is available here
  • The link to the left takes you to the USDM GitHub - Click on the view raw link or the download icon (top right) to download the Excel file

CDISC Controlled Terminology to Support USDM

The use of standardized terminology is an essential element of interoperability. CDISC currently leads the Protocol Terminology project which develops the semantics for commonly used research protocol entities. CDISC works in collaboration with the NCI Enterprise Vocabulary Services and CDISC volunteer subject matter experts to develop this controlled terminology package. The Protocol Terminology project supports the CDISC foundational standards for the Protocol Representation Model (PRM) and Clinical Trial Registry XML (CTR-XML). New control terminology needed to support the Reference Architecture will be developed with reuse of terminology already developed for the protocol terminology package and other CDISC controlled terminology packages as appropriate. This updated Reference Architecture controlled terminology package will be published as a standalone package alongside other CDISC Controlled Terminology.

USDM API Specification
  • The public review version of the API Specification is available on the USDM GitHub site

Application Programming Interface (API) Specification

A standardized API provides a standard interface for a common set of core services that must be supported by all conformant solutions. A standard API will enable application developers to build solutions that can use the core services of any conformant Study Definition. Data standards, controlled terminology, data exchange standards, and APIs work together to create an optimal environment for interoperability between conformant systems.

A Study Definition REST API will be specified using the OpenAPI Specification (OAS) version 3.0. As a machine-readable format, OAS can be used to generate not only interactive documentation, but also source code to aid developers creating software implementing the specification. The CDISC Library and ODM v2.0 also publish API specifications using these formats. The CDISC Library, ODM v2.0, HL7 FHIR, and the DDF Study Definition API form a growing set of standard APIs to improve interoperability and automation in clinical trials. Much like the CDISC Library API, the Study Definition API will support a range of media types including JSON and XML.

In addition to providing an interface for applications to retrieve study design information, the Study Definition API enables clients to create, update, and remove Study Definition content assuming the user’s role permissions support the activity. Thus, the API provides access to Study Definition services such that alternative user interfaces and applications can be developed to extend or exchange information with any given Study Definition tool.

USDM Implementation Guide

USDM Implementation Guide

A CDISC Implementation Guide will guide the organization, structure, and format of CDISC standards and provide users with the information required to successfully implement a CDISC standard. The USDM Implementation guide will therefore inform users about implementation of the Unified Study Definition Model (USDM) Class Diagram, CDISC Controlled Terminology to Support USDM, and Application Programming Interface (API) Specification. The USDM Implementation Guide should be used alongside the other deliverables in order to fully understand and enable users to implement the USDM model.

The second way is to download the single USDM.zip file

Public Review Webinar

  • We invite you to register and attend the DDF Public Review Webinar on Thursday 11:00am-12:30pm US Eastern Time, where representatives from the TransCelerate Biopharma and CDISC DDF teams will present on the updates made to the USDM during this phase of development, as well as providing information on how to provide public review comments.
  • A recoding of the webinar will be posted here

Other USDM Resources

The list below contains useful information if you are new to Digital Data Flow and the Unified Study Definitions Model (USDM) including:

  • How to find introductory information on DDF
  • Overview of the USDM
  • Biomedical Concepts in the USDM
  • Current developed test data
  • Using your own study using the test data tools

This page contains useful resources to help you get started with the Digital Data Flow (DDF) and the Unified Study Definitions Model (USDM).

What do you want to doNotes
I am new to DDF and want to find out more information

Visit TransCelerate's Digital Data Flow Web Page. Here you will find a host of assets available to help you understand the vision of he Digital Data Flow initiative including the key deliverables from the project:

  • CDISC Unified Study Definitions Model (USDM) and API specifications – the foundational standards to create a common, digital data model and method for exchanging protocol information
  • Study Definitions Repository (SDR) Reference Implementation and associated source code available in open source – a functioning, example approach to connect systems that produce protocol information with those that consume it to drive study operations – in the form of a reference implementation that stores and facilitates the exchange of protocol information
  • Engagements with implementers (sponsors, vendors, CROs) who play a critical role in leveraging standards in their software and their protocol digitization approach

There is an introductory video to the initiative as well as other useful general information, webinars, videos and sponsor company transformation tools.

I want a high level overview of what the USDM isOn TransCelerate's Digital Data Flow there is an introductory video on the USDM
I want to find out more information on the current USDM development activities Listen to the DDF USDM Phase 3 Introductory Webinar which provides an overview of activities in Phases 1 and 2 as well as the development plan for Phase 3
How do I become an SME on the CDISC DDF USDM Development TeamVisit the CDISC DDF Web Page and navigate to the participate tab for instructions on how to sign-up.
I want to find the latest official release information of the USDMVisit the CDISC DDF Web Page and navigate to the release information tab for information on the latest official release (V2.0 release June 2023). The files tab will allow you to download the latest released version of the USDM from Phase 2.
I want to find out more information on how Biomedical Concepts fit into the USDM

Watch the USDM and Biomedical Concepts webinar that was conducted on  to provide users with information on how Biomedical Concepts fit into the USDM.

Also refer to the slides from this webinar.

I want to see some examples of how study designs are represented in the USDM

You can visit the CDISC USDM GitHub and in the examples folder there are several examples of study protocols, a corresponding Excel representation of the study design and a JSON output in USDM format. See below for more information about the example test data and how you can create your own to help in your understanding of the USDM.  

I want to use my own study to show how this is represented in the USDM

CDISC has created several examples study designs for reference. There are tools available that can help you create an example of how your own study can be represented in USDM. Follow the steps below to help you get started with using the available tools.

  • Please note that the tools below are not a validated study builder tools and are developed only as an aid to help user start to understand the USDM model and the corresponding JSON representations. 
  • The tools do not 100% replicate the full breadth of the study design
  • Development work in ongoing and the tools and Excel utilities will evolve
  • If using your own study design do no expect a 1:2:1 100% match - the USDM is transforming the way we develop study designs and protocols


  1. Listen to the Webinar that CDISC conducted for attendees of the EU PHUSE Connect 2023 Workshop in Mastering the USDM (also the slides form this webinar)
  2. Review the Slides from the workshop to help understanding of more complex areas of the model such as Inclusion/Exclusion criteria, timelines, biomedical concepts, and footnotes
  3. It is also helpful to have an understanding of the USDM model, the USDM Model Information Graphic provides a visualization of the UML and in combination with the DDF Miro Board  (P: CDISC-DDF-SME) - you can follow the arrows to walkthrough the model to aid your understanding.
  4. CDISC has developed an Excel tool that can be used to plug in your own study design information and convert to JSON - Please note that this tool is not a validated study builder and is developed only as an aid to help user start to understand the USDM model and the corresponding JSON representations. You can download a partially complete Excel file as a starter - this will help you understand where some of the study design components fit into the Excel sheet by seeing an already completed example (this is based on the Example LZZT CDISC Pilot Study) . Note that this version of the Excel file was based on a draft version of the USDM, as development is still ongoing the Excel tool will be updated to represent additional features added during he draft releases. A starter version of the spreadsheet is also available here (also refer to the "usefulInfo" sheet).

    1. Web Tools (no need to install - these will run from a web browser)

  5. Once the Excel file is downloaded there are several resources to help understand the structure of the Excel tool and how to go about starting to complete the Excel tool for yourself
    1. The utility readme file will provide some additional information about the set-up of each of the excel worksheets - head to the Format of the Workbook Section.
    2. The following infographic will also help is showing the relationship between the various worksheets - this allows you to start understanding how the worksheets link and what information you need to provide in the linked worksheets for the tool to work.
    3. You can then start to complete the Excel workbook for your study design working though worksheet by worksheet and using the information to a. and b. above to help understand what is required.
  6. Once you have completed the Excel tool (or in fact partially completed) you can then use the Python web tool to up load and check your Excel file - Note that instructions to do this are in the Webinar (forward to 22mins 6 Seconds)
    1. Review/fix your any errors that have been reported and rerun the upload.
    2. Download and review the JSON output to see how the study design is represented in JSON
    3. Review the timeline graphic that is produced to help understand how the study timeline is created
    4. View a representation of your study design in M11 format (warning draft development ongoing)
    5. Delete your Excel file from the server
  7. Contact the CDISC USDM team if you have any questions on the Excel tool or if you are unsure how to represent certain study design information in the Excel tool
    1. Link to the PHUSE Follow-up  Webinar and review the webinar slides on  

    2. Example files used in the follow-up webinar

  8. CDISC will be conducting workshops in the future to help users Master the USDM so keep a look out for workshops at PHUSE US Connect and the EU/US CDISC Interchanges.


Instructions to create a JIRA comment for the USDM Implementation Guide

Note that the USDM Implementation Guide has been developed in the CDISC WIKI and therefore JIRA comments can be made direct in the WIKI

Please see the USDM Implementation Guide (USDM-IG) v3.0 landing page and the Instructions for Reviewers section of the USDM IG

Instructions to create a JIRA comment for the UML, CT and API Deliverables


  • In the create issue pop-up box
    • Ensure that the Project is set to "Digital Data Flow (DDF)"
    • Issue type will default to "Review Comments" - Please feel free to change the category if appropriate, otherwise it is fine to leave as "Review Comments".
    • In the Summary Box please enter a brief description of the comment
    • In the Components box please enter the standard to which you are commenting (USDM, API, CT)
    • Please leave the Fix Versions box empty
    • In the Description box please provide a thorough description of your comment.
      • This should be detailed enough for the CDISC DDF team to be able to clearly understand the intent of your comment in order to be able to action the comment.
      • Please also include any suggested changes with a rationale.
      • Please include any links to external material (if appropriate)
    • Please Enter "Internal Review" the Review Period box .
    • Please leave the Label box blank.
  • Click the CREATE button
    • Note that if you want to create another JIRA issue please check the box near the create button
  • Once the JIRA issue is created you will see a confirmation message with a hyperlink to the JIRA issue

Please do not enter more than one issue into a JIRA ticket (unless they are closely related and need to be resolved together). This will ensure that we can link JIRA issues to future product backlog work.



  • Then Click the View all Issues Link

  • This will allow access to see all the issues that you have created - you can click on the individual issue to see the details and make any edits required.


  • In some instances the CDISC DDF team may request additional information - this can be done using the commenting feature within a JIRA issue.
  • Usually the CDISC team member will create a comment and tag people who they want to address their comment - This can be done by typing the "@" sign and then the JIRA username.
  • JIRA will notify you that there is a comment addressed to you from CDISC and a link to JIRA to open the JIRA ticket.
  • Comments are seen at the bottom of the JIRA ticket once it is open
  • You can reply to comments, add attachments, links etc.
  • This is often used to keep a record of the discussions used to resolve a JIRA ticket


QuestionAnswer
What should I do if I can not access JIRAContact jowen@cdisc.org to help resolve
What should I do created a JIRA ticket by mistake

Contact jowen@cdisc.org to request the JIRA ticket to be deleted

  • Please provide the JIRA ticket number
What should I do if I created a JIRA ticket in the wrong project

Contact jowen@cdisc.org to request the JIRA ticket to be deleted

  • Please provide the JIRA ticket number

Public Review Issue Summary

Provides an overview of Public Review Comments that have been received (note you must have a CDISC WIKI/JIRA account to access the Public Review Issues)

com.atlassian.sal.api.net.ResponseException: Could not parse json from Jira

See below for a detailed list of Public Review Comments

Provides more detail on Public Review Comments that have been received. If the same comment has already been made you may want to add a comment to the JIRA ticket to add your comments, or if you feel it is best to create a new JIRA ticket please do so (note you must have a CDISC WIKI/JIRA account to access the Public Review Issues).

Key Summary T Created Status Description CDISC Disposition Description CDISC Disposition
Refresh

  • No labels