Library — Encapsulating shared logic
A quality measure, a risk score, a clinical decision-support rule: Library holds their CQL logic or model, ready to be referenced by Measure, PlanDefinition and ActivityDefinition.
Purpose
Library is the reusable unit of the FHIR Clinical Reasoning chain. It encapsulates:
- CQL code (Clinical Quality Language) — typically the evaluation logic of a Measure.
- Data model consumed by other resources (packaged StructureDefinitions).
- Rule sets for CDS Hooks.
- IG template for IG Publisher (rarer).
CQL source code is included as base64 in content[], alongside the
compiled ELM version (XML or JSON).
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
url | uri | 0..1 | Canonical URL. |
version | string | 0..1 | Version. |
name | string | 0..1 | Machine name. |
status | code | 1..1 | Publication status. |
type | CodeableConcept | 1..1 | Mandatory. logic-library | model-definition | asset-collection | module-definition. |
subject[x] | CodeableConcept | Reference | 0..1 | Subject type (typically Patient). |
relatedArtifact | RelatedArtifact[] | 0..* | Dependencies (depends-on, documentation, citation...). |
parameter | ParameterDefinition[] | 0..* | In/out parameters. |
dataRequirement | DataRequirement[] | 0..* | FHIR resources required for execution. |
content | Attachment[] | 0..* | Source & compiled code. |
content.contentType | code | 1..1 | text/cql, application/elm+xml, application/elm+json. |
content.data | base64Binary | 0..1 | Inline content. |
JSON example
CQL logic Library for type-2 diabetes follow-up, depending on FHIRHelpers and SNOMED:
{
"resourceType": "Library",
"id": "diabetes-management",
"url": "http://example.org/Library/diabetes-management",
"version": "1.0.0",
"name": "DiabetesManagementLogic",
"title": "Diabetes Management CQL Library",
"status": "active",
"experimental": false,
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/library-type",
"code": "logic-library"
}]
},
"date": "2026-05-14",
"publisher": "Example Org",
"description": "CQL logic for type-2 diabetes follow-up (HbA1c, Framingham score, alerts).",
"subjectCodeableConcept": {
"coding": [{
"system": "http://hl7.org/fhir/resource-types",
"code": "Patient"
}]
},
"relatedArtifact": [{
"type": "depends-on",
"resource": "http://hl7.org/fhir/uv/cql/Library/FHIRHelpers|4.0.013"
}, {
"type": "depends-on",
"resource": "http://hl7.org/fhir/uv/cql/CodeSystem/snomed-ct"
}],
"parameter": [{
"name": "Patient",
"use": "in",
"min": 1,
"max": "1",
"type": "Patient"
}, {
"name": "HbA1cAlert",
"use": "out",
"min": 0,
"max": "1",
"type": "boolean"
}],
"dataRequirement": [{
"type": "Observation",
"profile": ["http://hl7.org/fhir/StructureDefinition/Observation"],
"codeFilter": [{
"path": "code",
"valueSet": "http://hl7.org/fhir/ValueSet/observation-laboratory"
}]
}],
"content": [{
"contentType": "text/cql",
"data": "bGlicmFyeSBEaWFiZXRlc01hbmFnZW1lbnQgdmVyc2lvbiAnMS4wLjAnCnVzaW5nIEZISVIgdmVyc2lvbiAnNS4wLjAnCi8vIFNpbXBsaWZpZWQuLi4="
}]
}Common pitfalls
- CQL alone without compiled ELM — most execution engines expect ELM. Always supply both.
- Missing
dataRequirement— without pre-fetch, CQL evaluation must run N ad-hoc queries, hurting performance. - Unspecified CQL version — CQL 1.5 vs 1.4 vs 2.0: different evaluation compatibility.
- Cyclic dependencies — two Libraries depending on each other via
relatedArtifact[type=depends-on]block the resolver. - Library larger than 100 KB inline — prefer an external URL and cache rather than bloating the FHIR payload.
Related resources
- Measure — references Library for quality measure evaluation.
- PlanDefinition, ActivityDefinition — other Library consumers.
- MeasureReport — output of a Measure evaluation.
- ImplementationGuide — packaging Libraries.