FHIRPath v0.2.0.pre3

FHIRPath 0.2.0.pre3

Release status

• Release channel: pre-release
• Normative FHIRPath target: 2.0.0
• Capability set: parser, immutable-ast, collection-evaluation, plain-model-navigation, primitive-values, arithmetic, comparison-and-equivalence, boolean-logic, union-membership-and-type-operators, collection-functions, focus-variables, external-constants, custom-functions, compiled-expression-reuse, fhir-r4-model, structured-errors
• Trial-use (STU3-subset) features: stu3-aggregate-functions
• Supported Ruby CI matrix: Ruby 3.2 and Ruby 3.3
• License: MIT

Supported behavior

• require "fhirpath", version — test/fhirpath_test.rb
• Parse, immutable AST, source spans — foundation/parser tests
• Complete-input validation — parser regression tests
• String, Boolean, integer, decimal literals — foundation/core compatibility tests
• Scientific notation — core compatibility tests
• Empty and comma-separated collections — parser/evaluator tests
• Hash/Array/plain object navigation — foundation tests; PlainModel
• Unary/numeric arithmetic and string + — parity/core compatibility tests; + propagates empty operands; a zero divisor for /, div, mod yields an empty collection, while +, -, * operate on zero normally
• Relational comparison — parity/core compatibility tests
• Collection equality/equivalence — core compatibility tests and vectors
• Finite JSON Float treated as Decimal — evaluator correctness tests; a finite Float (e.g. from JSON.parse) compares, equals, arithmetically combines, and satisfies is Decimal; NaN/Infinity are rejected as non-numeric
• String & concatenation — core compatibility tests; empty operands are treated as ''
• Empty-aware Boolean operators — foundation/core compatibility tests
• Union, in, contains, is, as — core compatibility tests and vectors; union eliminates duplicates from both operands using = equality in first-seen order; in/contains require a singleton operand and follow the empty-collection rules; is/as test built-in primitive types by runtime value and, when a model provider resolves the value, also test the FHIR logical type recorded by navigation (e.g. Observation.value is Quantity), with as passing the value through unchanged on a match and yielding the empty collection on a mismatch
• Indexers — foundation/parity tests
• where, select, first, last, tail, take, skip, exists — test/subsetting_functions_test.rb
• Aggregate functions count(), sum(), avg(), max(), min() — test/aggregate_functions_test.rb and aggregate vectors. count() follows FHIRPath 2.0.0 (integer count; empty -> [0]). sum/avg/max/min are FHIRPath 3.0.0 STU3 aggregate additions (published 2026-07-28; absent from 2.0.0 and the 3.0.0 ballot) shipped in the standard registry: empty input -> empty; sum()/avg() accept numeric items only (TypeError code expected_number otherwise), sum mixed Integer/Decimal input through Decimal, and avg() converts Integer items to Decimal before dividing; max()/min() use comparison-operator semantics for numeric and string items (incompatible item types raise TypeError code incompatible_comparison); no input mutation. The STU3 subset is surfaced on the capability object: Capability.current keeps fhirpath 2.0.0 and declares marker stu3-aggregate-functions in trial_use (capability surface tests in the same file)
• empty, not, all, Boolean aggregates — core compatibility tests
• $this, $index, $total — parity tests
• Explicit external constants — foundation/core compatibility tests; values may come from variables: or an explicitly injected HostServices constant provider
• Missing external constant provider — test/host_services_test.rb; raises UnknownConstantError with code :unknown_constant and performs no fallback I/O
• Constant-provider failures and redaction — test/host_services_test.rb; raises generic HostError without retaining constant-provider exceptions as public causes or exposing their detail in diagnostics
• Host callback configuration/reentrancy — test/host_services_test.rb; HostServices is immutable and each evaluation receives a fresh context
• Custom registered functions — API/foundation tests
• Compiled-expression reuse — API/foundation tests
• Stable structured engine errors — API/foundation/parser tests
• ofType() type filter — test/oftype_test.rb; filters collections by built-in (Integer, String, Decimal, Boolean, Date, DateTime, Time) and FHIR resource types recorded during navigation; logical-type is/as previously deferred this slice
• Date/Time/DateTime literals (@...) — test/temporal_literals_test.rb; ISO 8601 with optional timezone (Z/±HH:MM)
• today(), now(), time() — test/temporal_now_test.rb
• Temporal component extractors (year, month, day, hour, minute, second, millisecond) — test/temporal_components_test.rb; millisecond() on DateTime reads sec_fraction * 1000
• Temporal timezone (timezone(), timezoneOffset()) — test/temporal_components_test.rb
• Temporal same-type comparison — test/temporal_comparison_test.rb; cross-type raises incompatible_comparison
• FHIR primitive extension accessor (._<name>) — test/primitive_extensions_test.rb; returns the underlying {value, extension} container or empty per FHIRPath 2.0.0
• FHIR R4 model adapter (model: :r4) — test/r4_model_test.rb; dependency-free FHIRPath::FHIR::R4::ModelProvider
• FHIR R4 Observation.value[x] logical navigation — R4 choice vectors; valueQuantity and valueString resolve through value, absent choice is empty
• FHIR R4 logical-type is/as over resolved choice values — test/r4_type_operator_test.rb and R4 choice vectors; navigation records the resolved choice variant's FHIR logical type (Quantity, string, ...) and is/as test against it; empty-in/empty-out and PlainModel (no model metadata) behavior are covered; the type is recorded for collections produced directly by navigation (operators that rebuild collections, such as union, do not yet propagate it); resource-level type tests and ofType() remain deferred
• FHIRPath 3.0 STU3 aggregate functions (sum, avg, max, min) — shipped by default as the first STU3-subset additions to the standard registry — a deliberate, documented exception (declared stu3-aggregate-functions in Capability.current.trial_use with fhirpath staying 2.0.0; see docs/api.md and docs/support-matrix.md); semantics follow the aggregate row above

Explicitly unsupported or deferred behavior

• Temporal arithmetic with Quantity/Duration — no Quantity type yet
• Quantity/UCUM — no unit service or quantity implementation
• Advanced conversion/math/string/regex — not in standard registry
• FHIR R5 model adapter — no R5 provider
• Official HL7 shared test suite — importer is not yet bundled
• Other FHIRPath 3.0 STU3 features — not enabled by default
• Network I/O/global evaluator state — pure evaluation boundary

Host-dependent behavior

• Broader FHIR choice elements and primitive extensions — first R4 slice only covers Observation.value[x]
• resolve() and terminology — requires injected host services

Verification evidence

• Compatibility vectors: 39 total (pass: 39, defect: 0, unsupported: 0, host-dependent: 0, not-run: 0).
• Release gates: Ruby matrix, tests, RuboCop, package build, installed-gem smoke test, and coverage validation ran on the tagged source.
• Artifact provenance: see SHA256SUMS.txt attached to this release.

Limitations

This is a pre-release compatibility slice, not a claim of complete FHIRPath
conformance. Review the release support matrix
and conformance workflow
before using it in production.