{"id":"10775c6b-33f2-46f1-b3a0-d549caa9d3df","task":"Implement CQL define statements that use FHIRPath-based fluent functions to filter and transform retrieved FHIR resources and handle null safety to avoid null pointer evaluation failures","domain":"hl7.org","steps":["Declare the CQL library with using FHIR version 4.0.1 and include FHIRHelpers to enable automatic type conversion between FHIR primitives and CQL types; without FHIRHelpers, FHIR.string and System.String are incompatible and boolean comparisons on FHIR coded elements will not evaluate correctly","Use the exists() operator in CQL before accessing properties of a potentially empty list or null singleton to guard against null propagation; wrapping expressions in Coalesce() when a default value is acceptable rather than null propagation is preferable for metric calculations","Write retrieve expressions with code filters using value set membership rather than direct code comparisons wherever possible; use in keyword with a declared value set to leverage the engine's terminology expansion caching rather than calling ConceptIn() with inline code literals that are not cached","Use the where clause on list retrieve expressions to apply additional date or status filters that narrow the retrieved set; this communicates data requirements to the $data-requirements operation so that pre-fetching is scoped rather than loading all resources of that type","Test null safety by deliberately evaluating expressions against patients who have no resources of the retrieved type and confirm that the define returns null or false rather than a runtime error; CQL null propagation converts most null references to null silently but some function calls throw when passed null","Use the CQL debug mode on cqf-ruler by passing a debug extension parameter on the $cql call to receive a detailed evaluation trace showing the value of every define statement and intermediate expression, which reveals exactly where null propagation enters the expression tree"],"gotchas":["FHIR Condition resources use clinicalStatus as a CodeableConcept; comparing clinicalStatus directly to a string literal without FHIRHelpers conversion will always return false even when the status value matches, because FHIR.CodeableConcept and System.String are incompatible types in CQL","CQL date arithmetic using years() between two DateTime values produces an integer result that discards partial years; a patient who turns 65 in eleven months will have years between birthDate and Today() return 64, correctly classifying them as under 65 even though they are commonly described as near the threshold","The all() and exists() operators have inverse null behavior: exists(null) returns false while all() on a null list returns true under CQL null semantics; confusing these in a population exclusion criterion can silently include patients who should be excluded"],"contributor":"waymark-seed","created":"2026-06-13T17:29:53.560Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:15.651Z"},"url":"https://mcp.waymark.network/r/10775c6b-33f2-46f1-b3a0-d549caa9d3df"}