CQL primer

CQL and FHIR glossary

Terms you meet when reading CQL rules, FHIR data and Taiwan’s NHI implementation guides, each explained in two or three sentences with a link to the official source.

The CQL language

CQLClinical Quality Language

The HL7 standard for writing clinical rules as logic that computers can run and people can read: quality measure criteria, triggers for clinical alerts, reimbursement criteria. CQL isn’t tied to one data format; a using declaration names the data model, which in Taiwan is usually FHIR R4. The normative release is 1.5.3; HL7 also published 2.0.0 as a trial-use release in July 2026.

ELMExpression Logical Model

The machine-readable form of CQL: a tree of expressions in XML or JSON. CQL is written for people; engines usually run the ELM. The CQL-to-ELM translator that produces it also checks syntax and types. When rules are published, a FHIR Library resource often carries both the CQL source and the ELM.

Source: cql.hl7.org/elm.html

LibraryCQL library

The unit a CQL file is organized in. A library opens with its name and version and holds declarations, defines and functions; it can include other libraries, such as FHIRHelpers, to reuse their logic. It is published inside a FHIR Library resource; in the NHI pre-check rule guide, each reimbursement rule is one Library.

definenamed expression

define, a name and a colon, then an expression; other expressions refer to it by the name in double quotes. Under context Patient, each define is evaluated once per patient. A measure’s denominator and numerator, and each condition and group in the workbench, are all defines.

parameter

A value supplied from outside by the system running the CQL, such as the measurement period. It is declared with a type and may have a default; if nothing is supplied and there is no default, it is null. The workbench uses Boolean parameters to receive condition results that an evidence adapter has already looked up in the record.

context

Sets what each define is evaluated for. The usual context Patient means every following define is evaluated for one patient, and retrieves only return that patient’s data. context Unfiltered covers the whole data set, for calculations across patients.

retrieve

How CQL fetches data: a resource type in square brackets, optionally followed by a colon and a code or value set, as in [Observation: "HbA1c"]. It returns a list holding only data for the current context, and it doesn’t filter by status, so a where clause usually follows. Whether the data comes from a FHIR server or a database is up to the environment running the CQL.

Three-valued logic and null

CQL uses null for “unknown”, such as a lab test that isn’t in the record. Boolean operations therefore have three results, true, false and null: false and null is false, while true and null is null. To separate met, not met and missing data, test with is true and is false.

FHIR and implementation guides

FHIRFast Healthcare Interoperability Resources

The HL7 standard for exchanging health data. It defines patients, lab results, diagnoses, medications and so on as resources, represented in JSON or XML and accessed through a REST API. Taiwan’s core implementation guide and TWPAS are both based on FHIR R4 (version 4.0.1).

Source: hl7.org/fhir/R4

FHIR resource

The unit of data in FHIR, each type with a fixed set of elements. Patient holds demographics, Observation holds lab results and measurements, Condition holds diagnoses and MedicationRequest holds prescriptions. A CQL retrieve fetches by resource type: [Observation: "HbA1c"] returns Observations.

Source: hl7.org/fhir/R4/resourcelist.html

ProfileStructureDefinition

A set of constraints on a resource, such as which elements are required and which value set a code must come from. A profile is itself a FHIR resource (StructureDefinition), usually published in an implementation guide, and validators can check data against it. Taiwan’s core implementation guide defines Taiwan profiles for patients, lab results and other resources.

Source: hl7.org/fhir/R4/profiling.html

Implementation guideIG

A complete specification for using FHIR in a particular setting, with profiles, value sets, code systems, examples and documentation, usually published as a website. Guides have versions and a status, such as STU (Standard for Trial Use) or a continuous integration build, which can change at any time. Taiwan’s core implementation guide and TWPAS are both implementation guides.

Source: hl7.org/fhir/R4/implementationguide.html

Codes and terminologies

Code systemFHIR CodeSystem

A set of codes and their definitions, each code standing for one concept; in LOINC, 4548-4 stands for an HbA1c test. Every code system has a canonical URI, such as http://loinc.org, declared in CQL with codesystem. The same string can mean different things in different systems, so codes are always compared together with their code system.

Value setFHIR ValueSet

A set of codes chosen for a purpose, drawn from one or more code systems; a diabetes value set might hold the codes for diabetes from both ICD-10-CM and SNOMED CT. A value set is identified by a canonical URL and declared in CQL with valueset; a retrieve or the in operator then checks whether data is coded with one of its codes. Rules that refer to value sets don’t have to list codes in the logic.

LOINCLogical Observation Identifiers Names and Codes

Maintained by the Regenstrief Institute in the US to identify lab tests and clinical observations: 4548-4 is HbA1c and 62238-1 is eGFR estimated with the CKD-EPI formula. A FHIR Observation usually uses a LOINC code to say which test it is. The code system URI is http://loinc.org.

Source: loinc.org

SNOMED CT

A clinical terminology maintained by SNOMED International, covering diagnoses, findings, procedures, specimens and more, with concepts arranged in a hierarchy: type 2 diabetes is a kind of diabetes. Use is subject to SNOMED International’s licensing terms. The code system URI is http://snomed.info/sct.

Source: www.snomed.org

ICD-10-CMInternational Classification of Diseases, 10th Revision, Clinical Modification

The US extension of the World Health Organization’s ICD-10 for coding diagnoses. Taiwan’s NHI has used ICD-10-CM/PCS for claims since 2016 (PCS covers procedures); codes starting with E11 are type 2 diabetes. CQL rules that check diagnoses usually use value sets of these codes.

Source: www.cdc.gov/nchs/icd/icd-10-cm/index.html

RxNorm

Standard drug names maintained by the US National Library of Medicine, giving drugs on the US market consistent codes for ingredient, strength and dose form. US eCQMs and many international examples use RxNorm for medications; prescription data in Taiwan mostly uses NHI drug codes, so applying foreign rules usually needs a mapping.

Source: www.nlm.nih.gov/research/umls/rxnorm/index.html

ATCAnatomical Therapeutic Chemical classification

Maintained by the WHO Collaborating Centre for Drug Statistics Methodology, it sorts drugs into five levels by the organ they act on, therapeutic use and chemical substance: A10 is drugs used in diabetes and A10BA02 is metformin. It suits rules about a class of drugs, such as “taking any diabetes drug”.

Source: atcddd.fhi.no

Decision support and measures

CDS Hooks

The HL7 standard for clinical decision support calls: at set moments (hooks), the EHR calls an outside service, for example when a patient’s chart is opened (patient-view) or orders are signed (order-sign). The service replies with cards that the EHR shows the clinician, such as a warning that a prescription doesn’t meet the reimbursement criteria. CQL makes the decision; CDS Hooks puts the result in front of the clinician.

CDS Service

An outside service that implements CDS Hooks. When a hook fires, the EHR sends it the patient context, optionally with FHIR data fetched in advance (prefetch), and the service replies with cards. A service lists the hooks it supports at its /cds-services endpoint, and often runs rules with a CQL engine.

Source: cds-hooks.hl7.org

eCQM and Measureelectronic Clinical Quality Measure

A quality measure calculated straight from EHR data, such as the share of patients with diabetes whose HbA1c is above 9%. The logic is written in CQL, with the initial population, denominator and numerator each a define; in FHIR, a Measure resource describes the measure and refers to the Library holding the CQL. Quality programs of the US Centers for Medicare & Medicaid Services (CMS) rely heavily on eCQMs.

Source: hl7.org/fhir/R4/measure.html

Taiwan’s platform and guides

Guides and a platform published by Taiwan’s Ministry of Health and Welfare and its National Health Insurance Administration. Publishers, versions and status are summarized in Taiwan’s official CQL guidance.

TW Core IG臺灣核心實作指引

The FHIR implementation guide led by the Ministry of Health and Welfare’s Department of Information Management. Based on FHIR R4 and drawing on the International Patient Summary (IPS) and US Core, it defines the profiles, value sets and code systems for exchanging health data in Taiwan, such as NHI drug codes and the Chinese edition of ICD-10-CM. TWPAS builds on it.

Source: twcore.mohw.gov.tw/ig/twcore

TWPAS臺灣健保事前審查實作指引

The NHI Administration’s FHIR implementation guide for the data hospitals send when requesting prior authorization, covering submissions, supplementary submissions, appeals and dispute reviews. It builds on TW Core; the CQL in the NHI pre-check rule guide reads the request data that TWPAS defines.

NHI pre-check rule IGTaiwan NHI Clinical Quality Language Implementation Guide (臺灣健保預檢規則實作指引)

The NHI Administration’s FHIR implementation guide that writes the reimbursement criteria for cancer drug prior authorization as CQL libraries. Each reimbursement rule is one Library that reads the request data TWPAS defines and decides whether it meets the criteria. As of 2026-10-28 it is still a draft continuous integration build and will change.

THRSTaiwan Health Rule Space (臺灣健康規則空間)

The ministry’s platform for sharing rules. Its core is a CQL library in which each rule maps to an NHI fee schedule code and is grouped by specialty. When the fee schedule changes, the platform posts a notice listing the rules affected. The site also has a CQL course area and a sandbox.

See also: Official guidance: THRSSource: thrs.mohw.gov.tw

Previous← CQL syntax cheat sheet NextTaiwan’s official CQL guidance →