- Introduction
- Intended Audience
- Overview
- Other Information
- Changes for Release V5.0 (September 2025)
- Support
Digital Data Flow is TransCelerate’s vision to catalyze industry-level transformation, enabling digital exchange of study definition information by collaborating with technology providers and standards bodies to create a sustainable open-source Study Definition Repository.
The Study Definitions Repository is a potential solution that may help support use of CDISC’s USDM standard as well as end-to-end data flow.
This is a .NET 8 Web API project that is designed to expose APIs which upstream/downstream systems can utilize to store and retrieve study definitions from SDR. The latest Release of SDR (Release V4.0) supports study definitions conformant with USDM V2.0, USDM V3.0 and USDM V4.0.
Please refer to the DDF SDR API User Guide to get started.
NOTES:
- These materials and information are provided by TransCelerate Biopharma Inc. AS IS. Any party using or relying on this information and these materials do so entirely at their own risk. Neither TransCelerate nor its members will bear any responsibility or liability for any harm, including indirect or consequential harm, that a user may incur from use or misuse of this information or materials.
- An SDR is not mandatory to achieve end-to-end data flow but rather represents one potential solution that may support end-to-end data flow. Nothing in this document should be construed as a recommendation that companies use an SDR or this SDR. Companies are solely responsible for determining how to manage their own end-to-end data flow systems and processes.
- This SDR is not a commercial product, rather it is TransCelerate’s attempt to illustrate what might be possible in implementing the USDM developed by CDISC. TransCelerate does not endorse any particular software, system, or service. Users can use the USDM for any purpose they choose and can build their own implementations of the SDR using the resources available on the initiative’s GitHub page.
- As of September 2025, the DDF initiative is still the process of setting up operations, and any pull requests submitted will not be triaged at this point in time.
Before participating, you must acknowledge the Contribution License Agreement (CLA).
To acknowledge the CLA, follow these instructions:
- Click here to download and carefully read the CLA.
- Print the document.
- Complete and sign the document.
- Scan and email a PDF version of the completed and signed document to DDF@transceleratebiopharmainc.com.
NOTE: Keep a copy for your records.
The contents in this repository enable users to set up SDR Reference Implementation API with a Docker container through their own GitHub repositories and workflows. The deployment scripts (YAML Scripts) can be configured and executed from GitHub Actions, leveraging GitHub Secrets to configure target environment specific values.
It assumes a good understanding of Docker concepts and containerization for running the API application in a container. The audience for this document should:
- have clear understanding of C# and .NET Web APIs
- have basic understanding of MongoDB and MongoDB C# driver
- be familiar with Docker and container management
- have basic understanding of GitHub Actions, Secrets & Yaml Scripts
The SDR Reference Implementation implements the CDISC DDF Reference Architecture which includes the USDM model and API Specifications defined using the OpenAPI Specification (OAS). The API Layer of the SDR Reference Implementation complies with the OpenAPI Specification and follows the REST architectural style that uses HTTP requests to GET, POST and PUT data.
Refer to the DDF SDR RI System Maintenance Guide Document for setting up a development instance of SDR.
Our published Docker image is the recommended way to run an instance of the SDR API:
docker run \
-e ConnectionStrings__DefaultConnection='<CONNECTION_STRING>' \
-e ConnectionStrings__DatabaseName='SDR' \
ghcr.io/transcelerate/ddf-sdr-api:latestWhere the ConnectionString parameters point to a mongo-compatible database in which study information can be stored and retrieved from. Refer to the SDR Platform project for a ready-to-use containerized database solution.
Note
API to USDM Version mapping - SDR supports 3 major USDM versions at a given point in time along with all their minor versions. API endpoints are up-versioned for breaking changes in USDM (API V3 -> USDM 2.0, API V4 -> USDM 3.0, API V5 -> USDM 4.0).
The solution has the following structure:
├── TransCelerate.SDR.sln
├── TransCelerate.SDR.Core
│ ├── AppSettings
│ ├── DTO
│ ├── Entities
│ ├── ErrorModels
│ ├── Filters
│ ├── Utilities
│ └── TransCelerate.SDR.Core.md
├── TransCelerate.SDR.DataAccess
│ ├── Filters
│ ├── Interfaces
│ ├── Repositories
│ └── TransCelerate.SDR.DataAccess.md
├── TransCelerate.SDR.RuleEngine
│ ├── Common
│ ├── StudyV3Rules
│ ├── StudyV4Rules
│ ├── StudyV5Rules
│ ├── Utilities
│ ├── ValidationDependenciesCommon.cs
│ ├── ValidationDependenciesV3.cs
│ ├── ValidationDependenciesV4.cs
│ ├── ValidationDependenciesV5.cs
│ └── TransCelerate.SDR.RuleEngine.md
├── TransCelerate.SDR.Service
│ ├── Interfaces
│ ├── Services
│ └── TransCelerate.SDR.Service.md
├── TransCelerate.SDR.UnitTesting
│ ├── CommonClassesUnitTesting
│ ├── ControllerUnitTesting
│ ├── Data
│ ├── ServicesUnitTesting
│ └── TransCelerate.SDR.UnitTesting.md
└── TransCelerate.SDR.WebApi
├── Properties
├── Data
├── DependencyInjection
├── Controllers
├── Mappers
├── appsettings.json
├── Program.cs
├── Startup.cs
└── TransCelerate.SDR.WebApi.md
TransCelerate.SDR.Core - contains entities, DTOs and helper classes.
TransCelerate.SDR.DataAccess - contains code for communicating with MongoDB database.
TransCelerate.SDR.RuleEngine - contains code for model validations based on data conformance rules as well as integration with the CDISC Rules Engine.
TransCelerate.SDR.Service - contains code for service layer which is a bridge between API controller and repository.
TransCelerate.SDR.UnitTesting - contains code for unit testing (NUnit Framework).
TransCelerate.SDR.WebApi - contains API controllers, mappers and the startup for the application.
For those looking to evaluate the USDM with a sample data set, please see the following files in the Data Model folder:
The below GET endpoint can be used to GET API Version -> USDM Version mapping.
/versions
For V3 endpoints, the "usdmVersion" header parameter is mandatory and the header value must be "2.0"
POST Endpoint The below endpoint can be used to create new study definitions.
/v3/studydefinitions
The below endpoint can be used to validate the USDM conformance rules for a study definition
/v3/studydefinitions/validate-usdm-conformance
PUT Endpoint The below endpoint can be used to update existing study definitions (create new version for a study definition).
/v3/studydefinitions/{studyId}
GET Endpoints
The below endpoint can be used to fetch all the elements for a given StudyId.
/v3/studydefinitions/{studyId}
The below endpoint can be used to fetch the sections of study design for a given StudyId.
/v3/studydesigns?studyId={studyId}
The below endpoint can be used to get the changes between two SDR Upload Versions of a specific study definition
/v3/studydefinitions/{studyId}/version-comparison?sdruploadversionone={sdruploadversionone}&sdruploadversiontwo={sdruploadversiontwo}
The below endpoint can be used to export study details mapped to a limited set of CPT Variables grouped by sections within the Common Protocol Template
/v3/studydefinitions/{studyId}/studydesigns/ecpt
The below endpoint can be used to fetch data from study definitions that help build the Schedule of Activities matrix for a given Schedule Timeline in a Study Design
/v3/studydefinitions/{studyId}/studydesigns/soa
For V4 endpoints, the "usdmVersion" header parameter is mandatory and the header value must be "3.0"
POST Endpoint The below endpoint can be used to create new study definitions.
/v4/studydefinitions
The below endpoint can be used to validate the USDM conformance rules for a study definition
/v4/studydefinitions/validate-usdm-conformance
PUT Endpoint The below endpoint can be used to update existing study definitions (create new version for a study definition).
/v4/studydefinitions/{studyId}
GET Endpoints
The below endpoint can be used to fetch all the elements for a given StudyId.
/v4/studydefinitions/{studyId}
The below endpoint can be used to fetch the sections of study design for a given StudyId.
/v4/studydesigns?studyId={studyId}
The below endpoint can be used to get the changes between two SDR Upload Versions of a specific study definition
/v4/studydefinitions/{studyId}/version-comparison?sdruploadversionone={sdruploadversionone}&sdruploadversiontwo={sdruploadversiontwo}
The below endpoint can be used to export study details mapped to a limited set of CPT Variables grouped by sections within the Common Protocol Template
/v4/studydefinitions/{studyId}/studydesigns/ecpt
The below endpoint can be used to fetch data from study definitions that help build the Schedule of Activities matrix for a given Schedule Timeline in a Study Design
/v4/studydefinitions/{studyId}/studydesigns/soa
For V5 endpoints, the "usdmVersion" header parameter is mandatory and the header value must be "4.0"
POST Endpoint The below endpoint can be used to create new study definitions.
/v5/studydefinitions
The below endpoint can be used to validate the USDM conformance rules for a study definition using the CDISC Rules Engine
/v5/studydefinitions/validate-usdm-conformance
PUT Endpoint The below endpoint can be used to update existing study definitions (create new version for a study definition).
/v5/studydefinitions/{studyId}
GET Endpoints
The below endpoint can be used to fetch all the elements for a given StudyId.
/v5/studydefinitions/{studyId}
The below endpoint can be used to fetch the sections of study design for a given StudyId.
/v5/studydesigns?studyId={studyId}
The below endpoint can be used to get the changes between two SDR Upload Versions of a specific study definition
/v5/studydefinitions/{studyId}/version-comparison?sdruploadversionone={sdruploadversionone}&sdruploadversiontwo={sdruploadversiontwo}
The below endpoint can be used to export study details mapped to a limited set of CPT Variables grouped by sections within the Common Protocol Template
/v5/studydefinitions/{studyId}/studydesigns/ecpt
The below endpoint can be used to fetch data from study definitions that help build the Schedule of Activities matrix for a given Schedule Timeline in a Study Design
/v5/studydefinitions/{studyId}/studydesigns/soa
The below endpoints can be used to fetch the revision history for a given StudyId.
/studydefinitions/{studyId}/revisionhistory
The below endpoint can be used to fetch basic details of all study definitions in SDR.
/studydefinitions/studyhistory
The below endpoint can be used to fetch study definitons in raw JSON string format
/studydefinitions/{studyId}/rawdata
The below endpoint can be used to fetch the change audit details of a study definiton
/studydefinitions/{studyId}/changeaudit
To view the API specifications and to run the endpoints locally, the below swagger url can be used.
https://localhost:44358/swagger/index.html
Note: Refer DDF SDR API User Guide for detailed information on all the endpoints.
SDR APIs are defined in such a way that an API version can handle more than one USDM Version. If there are no breaking changes between the USDM Versions, with same API version, more than one USDM Versions can be handled. But, when there is a breaking change in a new USDM Version, a new API version must be created to support the new USDM Version. Below are the list of changes that are required when creating a new API version.
- Configuration for ApiVersionUsdmVersionMapping and ConformanceRules must be updated to support new API version.
- Create new version for the below listed components
TransCelerate.SDR.Core.DTO
TransCelerate.SDR.Core.Entities
TransCelerate.SDR.Core.Utilities.Helpers
TransCelerate.SDR.RuleEngine
TransCelerate.SDR.DataAccess
TransCelerate.SDR.Services
TransCelerate.SDR.WebApi.Controllers
TransCelerate.SDR.WebApi.Mappers
Note: SDR V5 integrates with the CDISC Rules Engine for USDM conformance validation. This means the SDR no longer implements its own validation rules and utilizes the Core Engine for conformance validation. As a result, a new version for the RuleEngine no longer has to be created
- For version neutral endpoint search endpoint, data filters need to be added in below components to support new API version
TransCelerate.SDR.DataAccess
TransCelerate.SDR.Services
-
Automapper.Extensions.Microsoft.DependencyInjection - Used for mapping two different classes.
-
Newtonsoft.Json - Used for Serialization/De-Serialization of JSON Data.
-
MongoDB.Driver - Used for communicating with Mongo DB.
-
NUnit - Used for Unit Testing.
-
Moq - Used for mocking in unit testing.
-
Autofac.Extras.Moq - Used for mocking in unit testing.
-
FluentValidation.AspNetCore - Used for implementing the RuleEngine.
-
Swashbuckle.AspNetCore - Used for enabling Swagger for the API's.
-
Swashbuckle.AspNetCore.Annotations - Used for adding comments, sample request and response in Swagger.
-
Microsoft.Extensions.Logging - Used for logging.
-
Microsoft.Extensions.Configuration.Abstractions - Used for Key-Value abstractions.
-
Microsoft.AspNetCore.Mvc.Core - Contains common action result types, attribute routing, application model conventions, API explorer, application parts, filters, formatters, model binding, and more.
-
Vsxmd - Used for Converting xml comments into markdown file
-
ObjectsComparer - Used for comparing two objects of same type and return the differences
-
Microsoft.AspNetCore.Mvc.Versioning - Used for API Versioning Support
-
JsonSubTypes - Used to Serialize/Deserialize the inherited classes.
SDR Release V5.0 marks a fundamental shift from previous versions by eliminating Azure dependencies from its architecture, more easily enabling platform-agnostic deployment capabilities across various environments.
- For any technical queries on SDR API repository, please create an issue DDF SDR Support.