New CQL value type for structured types in engine runtime by antvaset · Pull Request #1713 · cqframework/clinical_quality_language

antvaset · 2026-03-25T21:40:42Z

Non-system structured types (e.g. instances of FHIR.Patient, FHIR.string, etc.) are now represented in the engine as CqlClassInstances. A CqlClassInstance can be thought of as a named tuple type (a tuple with a QName type tag like {http://hl7.org/fhir}Patient). As a result:
- the engine only operates on a fixed set of Kotlin types, and HAPI FHIR structures and other custom types do not bleed into the runtime,
- resolvePath(), as(), setValue(), objectEqual(), objectEquivalent(), resolveType() are no longer needed in the ModelResolver interface.
Java Class<T> references are replaced with type specifiers and type QNames (both multiplatform) in the engine. As a result:
- packageName(s) is no longer needed in ModelResolver and is(value: Any?, type: Class<*>?): Boolean? changed to is(valueType: String, type: QName): Boolean?,
- type testing is improved so e.g. Interval[1,2] is Interval<Integer> returns true and Interval[1,2] is Interval<Time> returns false,
- function resolution is more robust when function refs are compiled without signatures.
In FhirModelResolver : ModelResolver, the is(valueType: String, type: QName): Boolean? method now returns true only if {http://hl7.org/fhir}_valueType_ extends type or is the same as type. As a result, expressions like FHIR.integer { ... } is FHIR.positiveInt and FHIR.Quantity { ... } is FHIR.Age return false because FHIR.integer is a supertype of FHIR.positiveInt and FHIR.Quantity is a supertype of FHIR.Age.
Fix DescendentsEvaluator.

github-actions · 2026-03-25T21:41:11Z

Related Issues

The following open issues may be related to this PR:

Issue	Title	Score	Matched Terms
#867	Runtime type behavior of FHIR types is not polymorphic	23	"returns false", "false because", "fhir string", "because fhir", true, returns, string, return, types, false, because, expressions, runtime (path), type (path), provider (path), fhir (path), state (path), value (path)
#1273	Contexts should have type specifiers	22	"type specifiers", "org fhir", "hl7 org", "http hl7", "fhir patient", specifiers, string, patient, http, type (path), context (path), fhir (path), org (path), cql (path), hl7 (path)
#895	Integrate code generation into the cql-engine build	21.5	"hapi fhir", structures, string, modelresolver, fhirmodelresolver, return, types, resolvetype, instances, hapi, runtime (path), resources (path), java (path), src (path), caching (path), opencds (path), engine (path), function (path), context (path), fhir (path), main (path), org (path), cql (path), cqf (path), model (path), reflection (path), hl7 (path), data (path), class (path)
#1718	Includes operation returns false instead of null if either operand is null	20.5	"returns false", "hl7 org", "http hl7", "interval interval", result, returns, false, http, fhirpath (path), operators (path), interval (path), org (path), cql (path), instance (path), hl7 (path), list (path), test (path)
#1133	ToList is not implemented according to the spec	20	"org fhir", "hl7 org", returns, types, because, expressions, set, type (path), java (path), src (path), opencds (path), engine (path), property (path), retrieve (path), fhir (path), main (path), org (path), cql (path), cqf (path), elm (path), execution (path), hl7 (path), value (path), list (path), test (path)

Tip: If this PR addresses any of these issues, please link them using Closes #NNN or Refs #NNN in the PR description.

github-actions · 2026-03-25T21:42:06Z

Formatting check succeeded!

codecov · 2026-03-25T21:58:42Z

Codecov Report

❌ Patch coverage is 80.76923% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.74%. Comparing base (5bb1ece) to head (55cfb3f).

Files with missing lines	Patch %	Lines
...cds/cqf/cql/engine/fhir/model/FhirModelResolver.kt	80.00%	3 Missing and 9 partials ⚠️
...cql/engine/fhir/converter/BaseFhirTypeConverter.kt	75.00%	0 Missing and 1 partial ⚠️
...f/cql/engine/fhir/converter/R4FhirTypeConverter.kt	66.66%	0 Missing and 1 partial ⚠️
...e/fhir/retrieve/SearchParamFhirRetrieveProvider.kt	50.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #1713      +/-   ##
============================================
+ Coverage     62.00%   62.74%   +0.74%     
+ Complexity     3944     3889      -55     
============================================
  Files           210      210              
  Lines         20374    19946     -428     
  Branches       3882     3767     -115     
============================================
- Hits          12632    12516     -116     
+ Misses         6131     5870     -261     
+ Partials       1611     1560      -51

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

JPercival · 2026-03-27T13:40:49Z

Src/java/engine/src/commonMain/kotlin/org/opencds/cqf/cql/engine/execution/Environment.kt

-        ) {
-            return operand
+        return when (target) {
+            is Quantity -> {


thought: This is most of the ModelProvider functionality, but now written against the internal CQL types. Might make sense to factor that out as a class and test it independently rather than rolling it into the Environment, which manages cache, library loading, etc.

Another possibility would be a specialized kind of "Evaluator" class in the engine.

I agree. I moved is(), as(), etc. into repsective evaluators, so now it looks better.

Zylox · 2026-04-01T20:42:53Z

We are currently using a custom modelinfo and a custom modelresolver to implement cql over internal data types that are not fhir related. This is well supported currently. These changes to modelresolver seem to make that impossible now. Is this engine only going to support FHIR, specifically hapi fhir, or is there some other avenue to get existing behavior that i am missing.

Fully extracting every record into a CqlClassInstance would be prohibitively poorly performing for us. Right now, the fact that we can retrieve objects at request time with resolvePath is very useful.

If CqlClassInstance were an interface that allowed similar behavior we could make this work, maybe. You could even then implement the interface by something identical to the current implementation if for some reason that is performant for you, where cqlClassInstanceImpl.resolvePath("value") performs a get on elements, and others like my team can back it with our existing data structures. This approach still wouldnt be ideal as we would have to wrap every object in an adapter, but its preferable to having to fork off the engine.

sonarqubecloud · 2026-04-03T01:56:35Z

Quality Gate failed

Failed conditions
70.3% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

WIP

db631e6

Merge branch 'main' into engine-structured-types

cac566d

antvaset added 12 commits March 26, 2026 13:34

Merge branch 'main' into engine-structured-types

d70dd7d

Type compatibility checking

cf5de72

Small changes

817453e

Clean up tests

b6c5e16

detekt fix

7adc520

Cleanup

f54c46f

Argument type check

fa15db8

KDocs

cf1a572

KDocs

5686c6e

Formatting

e5eda12

Tests for FhirModelResolver.toCqlValue()

da737a2

Add tests for is

7b4a425

antvaset marked this pull request as ready for review March 27, 2026 06:35

Replace Java Class<T> with type QNames

e658833

JPercival reviewed Mar 27, 2026

View reviewed changes

JPercival approved these changes Mar 27, 2026

View reviewed changes

antvaset added 4 commits March 31, 2026 15:06

Docs

51959b0

Docs

a44b03b

Simplify engine environment class

600be2f

Docs

cb7a3f5

antvaset added 2 commits April 3, 2026 14:28

Use safe cast to Iterable<T>

4303518

Helper methods for CqlClassInstance

55cfb3f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New CQL value type for structured types in engine runtime#1713

New CQL value type for structured types in engine runtime#1713
antvaset wants to merge 21 commits intomainfrom
engine-structured-types

antvaset commented Mar 25, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 25, 2026

Uh oh!

codecov bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

JPercival Mar 27, 2026

Uh oh!

JPercival Mar 27, 2026

Uh oh!

antvaset Mar 31, 2026

Uh oh!

Zylox commented Apr 1, 2026 •

edited

Loading

Uh oh!

sonarqubecloud bot commented Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

antvaset commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issues

Uh oh!

github-actions bot commented Mar 25, 2026

Uh oh!

codecov bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

JPercival Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

JPercival Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

antvaset Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Zylox commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sonarqubecloud bot commented Apr 3, 2026

Quality Gate failed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

antvaset commented Mar 25, 2026 •

edited

Loading

github-actions bot commented Mar 25, 2026 •

edited

Loading

codecov bot commented Mar 25, 2026 •

edited

Loading

Zylox commented Apr 1, 2026 •

edited

Loading