Skip to main content

CDISC Dataset-JSON

Category: Clinical-trial dataset exchange

CDISC Dataset-JSON is a JSON transport for tabular research datasets. Convert-Pheno reads Dataset-JSON v1.1 SDTM domains and groups their rows by participant. The route is implemented and regression-tested; independent study coverage is still limited.

RoleInput
Accepted inputDataset-JSON v1.1 SDTM datasets
Main outputBFF, PXF, OMOP-CDM
ProcessingGrouped by USUBJID in memory
SDTM domain datasets grouped by USUBJID before conversion to BFF, PXF, or OMOP-CDM
Separate SDTM domain datasets are grouped into participant records before target conversion

What You Need​

Supply one JSON or gzip-compressed JSON document per SDTM domain. The files may be given in any order. The essential requirements are:

  • exactly one DM dataset
  • one unique DM.USUBJID for each participant
  • USUBJID in each participant-level domain
  • one consistent studyOID when it is present

The structural SDTM mapping is built in. A mapping file is optional and is used only when reviewed terminology enrichment is required.

convert-pheno \
  -idataset-json dm.json ae.json lb.json \
  -obff individuals.json

The same input can produce PXF or OMOP-CDM. See the Dataset-JSON recipes for those commands.

Mapped Content​

SDTM domainMain converted content
DMidentifier, sex, ethnicity, geographic origin, birth date, and vital status
MH, AEdiseases and phenotypic features
LB, VSmeasurements, units, ranges, and dates
CM, EX, PRtreatments and procedures
TSdataset and cohort metadata

Other participant-level domains remain available under info.datasetJson.domains. Use --no-source-info to omit that raw copy while retaining the mapped BFF fields.

For the field-level contract, see Dataset-JSON to BFF.

Terminology​

Without extra configuration, term-bearing SDTM values use source-derived CDISC: identifiers. These preserve the SDTM field and value; they do not claim an NCIT, SNOMED CT, or LOINC mapping.

To resolve selected values, provide a Mapping V2 file with source.profile: sdtm. It may contain reviewed direct terms, aliases, or database queries. Optional Define-XML metadata can also supply supported NCI identifiers.

For OMOP output, source-derived CDISC: identifiers are not assumed to be Athena concept codes. The BFF-to-OMOP stage can still resolve a unique active standard concept from a reviewed identifier, an official Maps to relationship, or a label in the expected OMOP domain. Otherwise it emits concept 0. Use a reviewed terminology mapping when the OMOP concepts carry analytical meaning for the study.

convert-pheno \
  -idataset-json dm.json ae.json \
  --mapping-file sdtm-terminology.yaml \
  --term-audit terminology.tsv \
  -obff individuals.json

The baseline fixture output shows source-derived fallbacks. The terminology-enriched output uses a small reviewed mapping and resolves selected fields to NCIT. Neither is intended as a complete SDTM terminology crosswalk. See Mapping Files and Terminology Search before adapting the example to study data.

Memory use

Dataset-JSON input is non-streaming. All domain documents and grouped participant records must fit in memory.