CRTDL

The Clinical Resource Transfer Definition Language (CRTDL) is a JSON-based format used to define cohorts and data extraction rules for TORCH. It allows users to specify who to extract data for, what data to extract, and how to handle consent and masking.

Key Features of CRTDL

• Cohort Definition: Specify the population of interest using FHIR resources and criteria.
• Data Extraction Rules: Define which FHIR resources and fields to extract.
• Consent Handling: Integrate consent rules to ensure compliance with privacy regulations.

---

CRTDL Structure

A CRTDL definition is structured as a JSON object with the following key components:

• cohort definition: Defines the population of interest.
• data extraction: Specifies the FHIR resources and fields to extract.

---

Cohort Selection

The cohort selection uses the CCDL (Clinical Cohort Definition Language) to define the population of interest.

TORCH supports CQL or FHIR Search for the cohort selection execution.

If your FHIR server does not support CQL, the FLARE component must be used to extract the cohort based on the cohort definition of the CRTDL. Alternatively you can specify a list of patient IDs which TORCH will use to extract the data.

The cohort evaluation strategy can be set using the TORCH_USE_CQL setting in the enviroment variables.

Torch uses the Consent Key to enforce consent rules during the cohort selection and data extraction process.

---

Data Extraction Selection

The data extraction object contains an array defining attributeGroups, which bundle attributes together.

Each group has an identifier for the group called groupReference, a list of attributes to be extracted, called attributes, and a filter object containing exactly one time filter and many code filter. The code filter contains an array of codes to be filtered (see filters).

Every data extraction must have exactly one attribute group that describes patient attributes.

An attribute to be extracted contains an attribute reference attributeRef and a flag indicating whether the attribute is required: mustHave.

{
  "attributeRef": "Medication.medicationCode",
  "mustHave": true
}

When mustHave: true is set on at least one attribute in a group, TORCH enforces that every patient has at least one resource of that group where all mustHave: true attributes are populated. Patients for whom no such resource exists are dropped from the extraction result entirely.

When no attribute in a group carries mustHave: true, the group is optional: patients are retained even if they have no resources for that group.

Standard attributes (id, meta.profile, and patient compartment references such as subject) are enforced at pipeline level and are never subject to mustHave filtering. Resources that lack id or meta.profile are filtered out before must-have checking runs. For patient resources specifically, TORCH enriches the resource with the target profile if meta.profile is missing, so patients are not dropped for a missing profile alone. See must-have checking for the full semantics.

Filter definitions have a list of FHIR search parameter operations containing the type, name (corresponds the code field in FHIR Search Parameters) and corresponding parameters. Currently token and date are supported types.

{
    "version": "http://json-schema.org/to-be-done/schema#",
    "display": "",
    "cohortDefinition": {
      "version": "http://to_be_decided.com/draft-1/schema#",
      "display": "",
      "inclusionCriteria": [
        [
            {
              "termCodes": [
                {
                  "code": "424144002",
                  "system": "http://snomed.info/sct",
                  "display": "Gegenwärtiges chronologisches Alter"
                }
              ],
              "context": {
                "code": "Patient",
                "system": "fdpg.mii.cds",
                "version": "1.0.0",
                "display": "Patient"
              },
              "valueFilter": {
                "type": "quantity-comparator",
                "unit": {
                  "code": "a",
                  "display": "a"
                },
                "value": 18,
                "comparator": "gt"
              }
            }
          ],
          [
            {
              "termCodes": [
                {
                  "code": "263495000",
                  "system": "http://snomed.info/sct",
                  "display": "Geschlecht"
                }
              ],
              "context": {
                "code": "Patient",
                "system": "fdpg.mii.cds",
                "version": "1.0.0",
                "display": "Patient"
              },
              "valueFilter": {
                "selectedConcepts": [
                  {
                    "code": "female",
                    "display": "Female",
                    "system": "http://hl7.org/fhir/administrative-gender"
                  }
                ],
                "type": "concept"
              }
            }
          ],
          [
            {
              "termCodes": [
                {
                  "code": "8-918",
                  "system": "http://fhir.de/CodeSystem/bfarm/ops",
                  "version": "2023",
                  "display": "Interdisziplinäre multimodale Schmerztherapie"
                }
              ],
              "context": {
                "code": "Procedure",
                "system": "fdpg.mii.cds",
                "version": "1.0.0",
                "display": "Prozedur"
              }
            }
          ]

      ],
        "dataExtraction": {
          "attributeGroups": [
            {
              "groupReference": "https://www.medizininformatik-initiative.de/fhir/core/modul-labor/StructureDefinition/ObservationLab",
              "attributes": [
                {
                  "attributeRef": "Observation.code",
                  "mustHave": false
                },
                {
                  "attributeRef": "Observation.value",
                  "mustHave": true
                }
              ],
              "filter": [
                {
                  "type": "token",
                  "name": "code",
                  "codes": [
                    {
                      "code": "718-7",
                      "system": "http://loinc.org",
                      "display": "Hemoglobin [Mass/volume] in Blood"
                    },
                    {
                      "code": "33509-1",
                      "system": "http://loinc.org",
                      "display": "Hemoglobin [Mass/volume] in Body fluid"
                    }
                  ]
                },
                {
                  "type": "date",
                  "name": "date",
                  "start": "2021-09-09",
                  "end": "2021-10-09"
                }
              ]
            }
          ]
        }
    }
}