Measure — Healthcare quality indicator
eCQM, HEDIS, CMS Quality Reporting: Measure defines a performance measure with numerator, denominator and CQL evaluation logic.
Purpose
Measure encodes the definition of a quality or performance measure: target population, numerator, denominator, exclusions, stratifications, reference to the CQL Library that executes the evaluation logic.
Measures are evaluated by the $evaluate-measure operation, which
returns a MeasureReport with aggregated (cohort) or individual
(per-patient) results.
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
url | uri | 0..1 | Canonical URL. |
version | string | 0..1 | Version. |
name | string | 0..1 | Machine name. |
title | string | 0..1 | Human title. |
status | code | 1..1 | Mandatory. Publication status. |
subject[x] | CodeableConcept | Reference | 0..1 | Subject type (typically Patient). |
library | canonical(Library)[] | 0..* | CQL Library executing the logic. |
scoring | CodeableConcept | 0..1 | Scoring type (proportion, ratio, continuous-variable, cohort). |
type | CodeableConcept[] | 0..* | Type (process, outcome, structure, patient-reported-outcome). |
rationale | markdown | 0..1 | Clinical rationale. |
clinicalRecommendationStatement | markdown | 0..1 | Clinical recommendation. |
improvementNotation | CodeableConcept | 0..1 | Improvement direction (increase / decrease). |
group | BackboneElement[] | 0..* | Groups (multiple scorings or stratifications). |
group.population | BackboneElement[] | 0..* | Populations (initial, denominator, numerator, exclusion...). |
group.population.criteria | Expression | 1..1 | CQL or FHIRPath expression. |
group.stratifier | BackboneElement[] | 0..* | Stratifications (sex, age, ethnicity). |
supplementalData | BackboneElement[] | 0..* | Supplemental data captured in the MeasureReport. |
JSON example
HEDIS-like Measure: percentage of diabetic patients 18-75 with controlled HbA1c (<9%) over the past year. Reference to a CQL Library:
{
"resourceType": "Measure",
"id": "diabetes-hba1c-control",
"url": "http://example.org/Measure/diabetes-hba1c-control",
"version": "1.0.0",
"name": "DiabetesHbA1cControl",
"title": "Diabetes — HbA1c Control (less than 9%)",
"status": "active",
"experimental": false,
"date": "2026-05-14",
"publisher": "Example Org",
"description": "Percentage of diabetic patients 18-75 years old with HbA1c < 9% over the past year.",
"library": ["http://example.org/Library/diabetes-management"],
"scoring": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/measure-scoring",
"code": "proportion",
"display": "Proportion"
}]
},
"type": [{
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/measure-type",
"code": "process"
}]
}],
"improvementNotation": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/measure-improvement-notation",
"code": "decrease",
"display": "Decreased score indicates improvement"
}]
},
"group": [{
"linkId": "hba1c-group",
"population": [
{
"linkId": "initial-population",
"code": {
"coding": [{ "system": "http://terminology.hl7.org/CodeSystem/measure-population", "code": "initial-population" }]
},
"criteria": {
"language": "text/cql-identifier",
"expression": "Initial Population"
}
},
{
"linkId": "denominator",
"code": {
"coding": [{ "system": "http://terminology.hl7.org/CodeSystem/measure-population", "code": "denominator" }]
},
"criteria": {
"language": "text/cql-identifier",
"expression": "Denominator"
}
},
{
"linkId": "numerator",
"code": {
"coding": [{ "system": "http://terminology.hl7.org/CodeSystem/measure-population", "code": "numerator" }]
},
"criteria": {
"language": "text/cql-identifier",
"expression": "Numerator"
}
}
]
}]
}Common pitfalls
- No
library— without a CQL Library,$evaluate-measurefails. - Missing
initial-population— although technically optional, it's the root of the chain: without it, the denominator can't be computed. - Confusing
scoring=proportionandratio— proportion = numerator ⊆ denominator (result 0–1); ratio = numerator and denominator independent. - Incorrect improvement direction — for HbA1c <9%, we want to increase the proportion:
improvementNotation=increase. For readmission rate,decrease. - Combinatorial stratifications — multiplying age × sex × ethnicity generates near-empty cells at low N.