fhirpath 0.2.0.pre3 → 0.2.0.pre4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55816199de3a062086023e1a40abdf4bf5496eab085f56d09c40348f3ef12099
-  data.tar.gz: e1a22be7cd54908b7824217559b82211feed90eda7884fe898341734875e05d8
+  metadata.gz: eacb9dc2934ca76d58acb3c6aab97acc1f2d602f436d28d1518a0ee26a25c14d
+  data.tar.gz: 7460ad33f47fd12408aaa905318285cec5e05f4db3503dcfd3ea4612c2d3ab53
 SHA512:
-  metadata.gz: 40667a9301563b5e7b8112234fcaaa13e9838efb83f5350b3aa5cd0aeb7ff40417320c8d296152c42a401873c857c5492ef20b3950434a525b4e36f46888d280
-  data.tar.gz: 166e58f9d11b4abe1c6ce4f646b367b1ff6da7f7273983d10442c40bc8757bc70b859fc02097ac657185e1d01df27cd6efd7d996684c24f9ac1a06116d542730
+  metadata.gz: 3e5de5efdbd7037022c0e36587dbebec79ab0406da23b76067b858d49f47b9edfecff975ef9e048fb19fd3455c1e2e704ad4491f77bffb47517abc46e3d5fc64
+  data.tar.gz: 5e7b7ec8152d3534464c70b739e025d63b06490f3c3fe8dcb16dc26017af0597d888243057de6600ac5a922eddda05035a7a5254773085a6d738ef339b65d494

data/.rubocop.yml

@@ -53,6 +53,7 @@ Metrics/ClassLength:
     - "test/subsetting_functions_test.rb"
     - "lib/fhirpath/conformance/importer.rb"
     - "test/conformance_pipeline_test.rb"
+    - "lib/fhirpath/models_r4.rb"
 
 Metrics/CyclomaticComplexity:
   Exclude:

data/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to this project are documented here. The project is pre-1.0;
 
 ## [Unreleased]
 
+## [0.2.0.pre4] - 2026-09-07
+- Add the `aggregate()` function with `$this`, `$total`, and `$index` variables for general-purpose collection aggregation (issue #43). The function signature is `aggregate(expression, initial)` where the expression is evaluated per item with the accumulator as `$total`. Empty collections return the initial value (or empty if omitted). Closes issue #43.
+- Add keyword-named functions (`contains`, `in`) usable after member access (`Patient.name.contains('John')`) — the lexer previously classified these as binary operators only, preventing function-call syntax after `.` (issue #66). Also registers both as standard functions with arity 1.
+- Accept raw JSON strings in `FHIRPath.evaluate()` and `CompiledExpression#evaluate`: strings starting with `{` or `[` after optional whitespace are parsed via `JSON.parse` once per call; malformed JSON raises `JSONInputError` (code `:invalid_json`); `Hash`/`Array` inputs pass through unchanged; other strings remain singleton string values (issue #56).
+- Add bounded Quantity/UCUM support: immutable `BigDecimal`-backed `FHIRPath::Quantity` type with case-sensitive conversion for the explicit subset (`m`, `cm`, `mm`, `km`, `g`, `kg`, `mg`, `Mg`, `ug`, `ng`, `L`, `mL`, `ML`, `uL`, `mol`, `mmol`, `umol`, `s`, `min`, `h` and products/quotients such as `mmol/L`). Same-dimension comparison/addition/subtraction/multiplication by scalar/division; incompatible or unsupported-unit operations return empty. The UCUM parser is dependency-free and exponents are bounded to 12 to prevent CPU/memory amplification (issue #44).
+- Expand R4 model adapter choice elements: `Medication`, `Condition`, `Procedure`, and `DiagnosticReport` choice elements now resolve through the FHIRPath navigation layer (issue #46).
+- Import and check in the full official HL7 FHIRPath shared test suite (935 cases from `fhir-test-cases` release `1.7.69`) with a new `load_full_suite` importer mode that bypasses the pinned `case_ids` subset (issue #47).
+- Document JSON input behavior in `docs/api.md` and add FHIR-native JSON examples to the README Quick Start.
+
+- Add a dependency-free, explicitly bounded FHIRPath `Quantity` type. Quantity
+  values always store a finite `BigDecimal` and expose `value`, `unit`,
+  `system`, and `code`; integer quantity literals are promoted to Decimal.
+  Single- and double-quoted unit literals are supported, with case-sensitive
+  conversion for the tested subset of length, mass, volume, amount, and time
+  units plus simple products/quotients such as `mmol/L`. Same-dimension
+  quantities support comparison, addition, subtraction, scalar multiplication
+  and division, and Quantity/Quantity ratios. Unsupported units are rejected;
+  incompatible calculations return an empty collection. Quantity×Quantity and
+  derived-unit composition such as `km/h` remain deferred. This is not complete
+  UCUM conformance, and calendar-duration arithmetic remains deferred. The
+  parser also accepts double-quoted strings as a documented extension, while
+  normative FHIRPath string literals remain single-quoted. Wrong-case symbols
+  such as `MG` and `G` are rejected; exponent notation uses `^` (for example,
+  `m^2`). Mixed Quantity/scalar addition is empty in either operand order,
+  and derived-unit division such as `km/h` is deferred. Quantity `system` and
+  `code` metadata is preserved but does not change unit equality.
+
+
 ## [0.2.0.pre3] - 2026-09-06
 - Same library content as `0.2.0.pre2`. Version bumped because the earlier
   `0.2.0.pre2` tag was pushed to RubyGems by a partial release run before the

data/README.md

@@ -4,6 +4,9 @@
 [![Release](https://github.com/niccoreyes/fhirpath-ruby/actions/workflows/release.yml/badge.svg)](https://github.com/niccoreyes/fhirpath-ruby/actions/workflows/release.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/niccoreyes/fhirpath-ruby/blob/main/LICENSE)
 [![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3-blue.svg)](https://github.com/niccoreyes/fhirpath-ruby/blob/main/.github/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/fhirpath.svg)](https://rubygems.org/gems/fhirpath)
+[![Gem Downloads](https://img.shields.io/gem/dt/fhirpath)](https://rubygems.org/gems/fhirpath)
+[![RubyGems](https://img.shields.io/gem/v/fhirpath?logo=rubygems&logoColor=white)](https://rubygems.org/gems/fhirpath)
 
 A Ruby-native implementation of the [HL7 FHIRPath](https://hl7.org/fhirpath/) expression language.
 
@@ -11,10 +14,10 @@ This repository is an intentionally small, pre-release implementation. It provid
 
 ## Status at a glance
 
-- Version: `0.2.0.pre1`
+- Version: `0.2.0.pre3`
 - Normative language target: FHIRPath `2.0.0`
 - Ruby support policy: Ruby `3.2` and `3.3` are tested in CI; newer Ruby versions are supported only after CI coverage is added.
-- Release status: pre-release; not published to RubyGems.
+- Release status: pre-release; published to [RubyGems](https://rubygems.org/gems/fhirpath).
 - License: [MIT](LICENSE).
 
 The exact release-facing target, capability identifiers, Ruby support matrix,
@@ -22,19 +25,15 @@ and host/model limitations are maintained in the [release support matrix](docs/s
 
 ## Installation
 
-The gem is not yet published. To use a checkout:
+The gem is published on [RubyGems.org](https://rubygems.org/gems/fhirpath):
 
 ```sh
-git clone https://github.com/niccoreyes/fhirpath-ruby.git
-cd fhirpath-ruby
-bundle install
-bundle exec rake test
+gem install fhirpath
 ```
 
-Once a release is published, the intended consumer workflow will be:
+Or in a Gemfile:
 
 ```ruby
-# Gemfile
 gem "fhirpath"
 ```
 
@@ -43,22 +42,38 @@ documented limitations before using this implementation in production.
 
 ## Quick start
 
+## Quick start
+
 ```ruby
 require "fhirpath"
 
-patient = {
-  "resourceType" => "Patient",
-  "name" => [
-    { "use" => "official", "family" => "Lovelace", "given" => ["Ada", "Augusta"] },
-    { "use" => "nickname", "given" => ["Addie"] }
-  ]
-}
+# Plain Ruby Hash/Array navigation
+data = { items: [1, 2, 3, 4, 5] }
+FHIRPath.evaluate(data, "items.where($this > 3)")   # => [4, 5]
 
-FHIRPath.evaluate(patient, "Patient.name.where(use = 'official').given").to_a
-# => ["Ada", "Augusta"]
+# FHIR R4 model adapter
+observation = {
+  "resourceType" => "Observation",
+  "id" => "obs-1",
+  "status" => "final",
+  "code" => { "coding" => [{ "system" => "http://loinc.org", "code" => "8480-6" }] },
+  "valueQuantity" => { "value" => 5.5, "unit" => "mmol/L", "system" => "http://unitsofmeasure.org", "code" => "mmol/L" }
+}
 
-FHIRPath.evaluate_first(patient, "Patient.name.family")
-# => "Lovelace"
+# Navigate FHIR JSON with R4 model adapter
+FHIRPath.evaluate(observation, "valueQuantity.value > 5.0", model: :r4)  # => [true]
+FHIRPath.evaluate(observation, "valueQuantity.unit", model: :r4)         # => ["mmol/L"]
+FHIRPath.evaluate(observation, "code.coding.system", model: :r4)         # => ["http://loinc.org"]
+
+# Type filtering with ofType()
+bundle = {
+  "resourceType" => "Bundle",
+  "entry" => [
+    { "resource" => { "resourceType" => "Observation", "id" => "1" } },
+    { "resource" => { "resourceType" => "Patient", "id" => "2" } }
+  ]
+}
+FHIRPath.evaluate(bundle, "entry.resource.ofType(Observation)", model: :r4)  # => [Observation resource]
 ```
 
 FHIR R4 JSON can be selected explicitly through the versioned provider. The
@@ -145,6 +160,7 @@ The current tested slice includes:
 - plain Ruby Hash/Array and simple object navigation, including resource-type roots such as `Patient`;
 - dependency-free FHIR R4 model navigation selected with `model: :r4`, including the logical `Observation.value` choice property over `valueQuantity` and `valueString`;
 - unary and numeric arithmetic (`+`, `-`, `*`, `/`, `div`, and `mod`), plus string `+` when both operands are strings; a zero divisor for `/`, `div`, `mod` returns an empty collection, while `+`, `-`, `*` treat zero as a normal operand;
+- bounded FHIRPath `Quantity` values with finite Decimal storage, case-sensitive conversion for the documented dependency-free unit subset, same-dimension comparison/addition/subtraction, scalar multiplication/division, Quantity ratios, and `ofType(Quantity)`/`is Quantity`/`as Quantity`; unsupported units and complete UCUM semantics remain outside this release slice; the parser also accepts double-quoted strings as an extension, uses `^` for supported unit exponents, preserves Quantity `system`/`code` metadata without using it for unit equality, and defers derived-unit composition such as Quantity×Quantity or `km/h`;
 - numeric/string relational comparison, collection-aware equality, equivalence, and empty-aware Boolean operators; a finite JSON `Float` is treated as a `Decimal`;
 - union, string concatenation (`+` and `&`), membership (`in`/`contains`), and type operators (`is`/`as`); union removes duplicate values from both operands using `=` equality in first-seen order, and `in`/`contains` require a singleton operand; `is`/`as` test built-in primitive types directly and, with `model: :r4`, also resolve the FHIR logical type of a navigated choice value (for example `Observation.value is Quantity` over `valueQuantity`), returning the value unchanged on a successful `as` and the empty collection otherwise; and
 - indexers with non-negative integer indexes;
@@ -162,7 +178,7 @@ This is not yet a complete FHIRPath engine. The following remain deferred or hos
 
 - complete FHIRPath 2.0 conformance; the checked-in importer covers only the pinned official subset;
 - broader FHIR R4 metadata such as primitive extensions, resource-level type tests (`Observation is Resource`/`DomainResource`), `ofType()`, and FHIR R5 model adapters; FHIR R4 `is`/`as` over a resolved choice value's logical type (e.g. `Quantity`) is supported, but terminology and `resolve()` remain host-dependent; and
-- date/time and quantity/UCUM values;
+- temporal arithmetic with Date/Time/DateTime and Quantity/Duration, including calendar-duration arithmetic;
 - advanced conversion, math, string, regular-expression, and navigation functions, and the general-purpose `aggregate()` function;
 - complex literals and additional standard value types;
 - standard environment variables beyond explicitly supplied external constants;

data/conformance/official-r4-core.json

@@ -1,15 +1,10 @@
 {
   "schema": "fhirpath-conformance-v1",
   "suite": "FHIR/fhir-test-cases",
-  "suite_commit": "2d595a506a91eeb311ab787f5fe2c8806be3cfd1",
+  "suite_commit": "1.7.69",
   "target": "2.0.0",
   "model": "plain",
   "source": "r4/fhirpath/tests-fhir-r4.xml",
   "fixture_root": "r4",
-  "cases": [
-    "testPrecedence2",
-    "testUnion1",
-    "testPlus4",
-    "testLiteralTrue"
-  ]
-}
+  "load_full_suite": true
+}

data/docs/api.md

@@ -63,6 +63,8 @@ result = FHIRPath.evaluate(
 
 Returns a `FHIRPath::Collection`. Empty results are collections with `empty? == true`, not `nil`. `to_a` returns a copy of the ordered values.
 
+The `resource` argument may be an already-parsed Hash/Array (used directly, never re-serialized) or a raw JSON document String. Strings that open with `{` or `[` after leading whitespace are parsed with `JSON.parse` once per call; a malformed document raises `FHIRPath::JSONInputError` (code `:invalid_json`) with a generic public message that does not echo document contents, while `original_cause` retains the underlying `JSON::ParserError` for programmatic diagnostics. Any other String — plain text, JSON scalar text such as `"null"` or `"123"`, or a quoted JSON primitive like `"\"Ada\""` — keeps its pre-existing meaning as a singleton FHIRPath string value and is never parsed. Parsing builds a fresh structure per call; the caller's String and any Hash/Array resource are never mutated or frozen. `CompiledExpression#evaluate` and `#call` apply the same resource handling.
+
 `variables:` supplies external constants using either String or Symbol keys:
 
 ```ruby
@@ -101,6 +103,7 @@ All public engine errors derive from `FHIRPath::Error` and carry a stable symbol
 | Error | Meaning |
 |---|---|
 | `ParseError` | Invalid token, malformed syntax, unsupported escape, trailing input, or expression nesting exceeding the parser depth budget (code `nesting_depth_exceeded`) |
+| `JSONInputError` | The resource argument opened like a JSON object or array (after whitespace) but was not valid JSON (code `invalid_json`) |
 | `EvaluationError` | Valid syntax cannot be evaluated for the current input |
 | `SingletonError` | A singleton value was required but the collection had multiple items |
 | `FHIRPath::TypeError` | A value has an incompatible FHIRPath type |

data/docs/conformance.md

@@ -5,7 +5,8 @@ The project distinguishes specification conformance from compatibility evidence.
 - The HL7 FHIRPath specification and official shared test cases are normative.
 - Checked-in JSONL vectors are small, reviewable regression probes inspired by observed behavior in `fhirpath-py`.
 - No Python runtime is required to run the Ruby vector harness.
-- The repository ships a Ruby-only importer for pinned official XML subsets and the pinned `fhirpath-py` YAML case format; complete conformance remains deferred.
+- The repository ships a Ruby-only importer for official XML suites and the pinned `fhirpath-py` YAML case format.
+- The default manifest imports a pinned subset; `load_full_suite: true` imports the complete official suite.
 
 ## Run the checked-in vectors
 
@@ -52,6 +53,23 @@ Values that JSON cannot represent should use explicit tagged values when that fa
 4. Add the JSONL vector and run the complete test, lint, build, and vector commands.
 5. Update `docs/feature-matrix.md`, README limitations, and `CHANGELOG.md` if the public scope changes.
 
+## Import the complete official suite
+
+Set `load_full_suite: true` in the manifest to bypass `case_ids` filtering and import every XML case from the official suite. The importer still applies the same fixture normalization, provenance tracking, and `not-run` classification rules as the pinned-subset mode.
+
+```json
+{
+  "schema": "fhirpath-conformance-v1",
+  "suite": "FHIR/fhir-test-cases",
+  "suite_commit": "1.7.69",
+  "target": "2.0.0",
+  "model": "plain",
+  "source": "r4/fhirpath/tests-fhir-r4.xml",
+  "fixture_root": "r4",
+  "load_full_suite": true
+}
+```
+
 ## Import a pinned suite subset
 
 The importer accepts the checked-in manifest and a local checkout of its pinned source:

data/docs/feature-matrix.md

@@ -10,22 +10,25 @@ This matrix is deliberately conservative. `Supported` means the behavior is exer
 | Parse, immutable AST, source spans | Supported | foundation/parser tests |
 | Complete-input validation | Supported | parser regression tests |
 | String, Boolean, integer, decimal literals | Supported | foundation/core compatibility tests |
+| Double-quoted string literals | Extension | the lexer accepts double-quoted strings in addition to normative single-quoted FHIRPath strings; this extension supports double-quoted Quantity units and is covered by Quantity tests |
 | Scientific notation | Supported | core compatibility tests |
 | Empty and comma-separated collections | Supported | parser/evaluator tests |
-| Hash/Array/plain object navigation | Supported | foundation tests; `PlainModel` |
-| Unary/numeric arithmetic and string `+` | Supported | parity/core compatibility tests; `+` propagates empty operands; a zero divisor for `/`, `div`, `mod` yields an empty collection, while `+`, `-`, `*` operate on zero normally |
+|| Hash/Array/plain object navigation | Supported | foundation tests; `PlainModel` ||
+|| Raw JSON string resource input | Supported | `test/json_string_input_test.rb`; `FHIRPath.evaluate`, `FHIRPath.evaluate_first`, and `CompiledExpression#normalize_resource` normalize strings opening with `{` or `[` after whitespace via `JSON.parse` once per call, malformed documents raise `JSONInputError` code `invalid_json`, Hash/Array inputs are never parsed, and other strings (plain text, JSON scalar text, quoted primitives) pass through unchanged ||
+|| Unary/numeric arithmetic and string `+` | Supported | parity/core compatibility tests; `+` propagates empty operands; a zero divisor for `/`, `div`, `mod` yields an empty collection, while `+`, `-`, `*` operate on zero normally ||
 | Relational comparison | Supported | parity/core compatibility tests |
 | Collection equality/equivalence | Supported | core compatibility tests and vectors |
 | Finite JSON `Float` treated as `Decimal` | Supported | 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 | Supported | core compatibility tests; empty operands are treated as `''` |
 | Empty-aware Boolean operators | Supported | foundation/core compatibility tests |
 | Union, `in`, `contains`, `is`, `as` | Supported | 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 | Supported | foundation/parity tests |
-| `where`, `select`, `first`, `last`, `tail`, `take`, `skip`, `exists` | Supported | `test/subsetting_functions_test.rb` |
-| Aggregate functions `count()`, `sum()`, `avg()`, `max()`, `min()` | Supported | `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 | Supported | core compatibility tests |
-| `$this`, `$index`, `$total` | Supported | parity tests |
-| Explicit external constants | Supported | foundation/core compatibility tests; values may come from `variables:` or an explicitly injected `HostServices` constant provider |
+|| Indexers | Supported | foundation/parity tests |
+|| `where`, `select`, `first`, `last`, `tail`, `take`, `skip`, `exists` | Supported | `test/subsetting_functions_test.rb` |
+|| Aggregate functions `count()`, `sum()`, `avg()`, `max()`, `min()` | Supported | `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 | Supported | core compatibility tests |
+|| `$this`, `$index`, `$total` | Supported | parity tests |
+| General-purpose `aggregate()` function | Supported | `test/aggregate_functions_test.rb`; enables custom aggregations via `$this`, `$index`, `$total` |
+|| Explicit external constants | Supported | foundation/core compatibility tests; values may come from `variables:` or an explicitly injected `HostServices` constant provider |
 | Missing external constant provider | Supported | `test/host_services_test.rb`; raises `UnknownConstantError` with code `:unknown_constant` and performs no fallback I/O |
 | Constant-provider failures and redaction | Supported | `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 | Supported | `test/host_services_test.rb`; `HostServices` is immutable and each evaluation receives a fresh context |
@@ -38,9 +41,9 @@ This matrix is deliberately conservative. `Supported` means the behavior is exer
 | Temporal component extractors (`year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`) | Supported | `test/temporal_components_test.rb`; `millisecond()` on `DateTime` reads `sec_fraction * 1000` |
 | Temporal timezone (`timezone()`, `timezoneOffset()`) | Supported | `test/temporal_components_test.rb` |
 | Temporal same-type comparison | Supported | `test/temporal_comparison_test.rb`; cross-type raises `incompatible_comparison` |
-| Temporal arithmetic with Quantity/Duration | Deferred | no Quantity type yet |
+| Temporal arithmetic with Quantity/Duration | Deferred | calendar-duration and date/time arithmetic is not implemented; bounded numeric Quantity arithmetic is supported separately below |
 | FHIR primitive extension accessor (`._<name>`) | Supported | `test/primitive_extensions_test.rb`; returns the underlying `{value, extension}` container or empty per FHIRPath 2.0.0 |
-| Quantity/UCUM | Deferred | no unit service or quantity implementation |
+| Quantity/UCUM | Supported | `test/quantity_test.rb` and `test/quantity_edge_cases_test.rb`; immutable Decimal-backed quantities, case-sensitive dimensional conversion for the explicitly bounded dependency-free subset (`m`/`cm`/`mm`/`km`, `g`/`kg`/`mg`/`Mg`/`ug`/`ng`, `L`/`mL`/`ML`/`uL`, `mol`/`mmol`/`umol`, `s`/`min`/`h`, and products/quotients such as `mmol/L`); unsupported units are rejected rather than treated as dimensionless, incompatible calculations and mixed Quantity/scalar addition return empty, same-dimension Quantity division returns a Decimal ratio, derived-unit composition such as Quantity×Quantity or `km/h` remains deferred, and system/code metadata is preserved without changing unit equality |
 | Advanced conversion/math/string/regex | Deferred | not in standard registry |
 | FHIR R4 model adapter (`model: :r4`) | Supported | `test/r4_model_test.rb`; dependency-free `FHIRPath::FHIR::R4::ModelProvider` |
 | FHIR R4 `Observation.value[x]` logical navigation | Supported | R4 choice vectors; `valueQuantity` and `valueString` resolve through `value`, absent choice is empty |

data/docs/support-matrix.md

@@ -34,12 +34,15 @@ These stable identifiers describe the behavior included in the current package:
 - `collection-evaluation` — explicit empty, singleton, and multi-item results;
 - `plain-model-navigation` — Hash, Array, and safe simple-object navigation;
 - `primitive-values` — strings, Booleans, integers, decimals, and scientific notation;
-- `arithmetic` — unary/numeric arithmetic and string `+`;
+- `arithmetic` — unary/numeric arithmetic, string `+`, and the bounded Quantity scalar/Quantity arithmetic described below;
+- `quantity-ucum` — immutable Decimal-backed Quantity values with case-sensitive dimensional conversion for the explicitly supported unit subset (`m`/`cm`/`mm`/`km`, `g`/`kg`/`mg`/`Mg`/`ug`/`ng`, `L`/`mL`/`ML`/`uL`, `mol`/`mmol`/`umol`, `s`/`min`/`h`, and products/quotients such as `mmol/L`); unsupported units are rejected, incompatible calculations and mixed Quantity/scalar addition return empty, same-dimension Quantity division returns a Decimal ratio, derived-unit composition such as Quantity×Quantity or `km/h` remains deferred, and system/code metadata is preserved without changing unit equality;
 - `comparison-and-equivalence` — relational comparison, equality, and equivalence;
 - `boolean-logic` — empty-aware Boolean operators;
 - `union-membership-and-type-operators` — union, `in`, `contains`, `is`, and `as`;
 - `collection-functions` — `where`, `select`, `first`, `exists`, `count`, `empty`, `not`, `all`, Boolean aggregates, and `ofType`;
++ `collection-functions` — `where`, `select`, `first`, `exists`, `count`, `empty`, `not`, `all`, Boolean aggregates, `ofType`, and `aggregate`;
 - `subsetting-functions` — `tail`, `take`, `skip`, `last`;
++ `subsetting-functions` — `tail`, `take`, `skip`, `last`;
 - `temporal-types` — `Date`, `DateTime`, `Time` literals (`@YYYY-MM-DD`, `@THH:MM:SS`, `@YYYY-MM-DDTHH:MM:SS±HH:MM`), `today()`, `now()`, `time()`, component extractors (`year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`), `timezone()`, `timezoneOffset()`, and same-type comparison;
 - `fhir-primitive-extensions` — `._<name>` accessor returning the underlying `{value, extension}` container or empty per FHIRPath 2.0.0;
 - `focus-variables` — `$this`, `$index`, and `$total`;
@@ -75,14 +78,64 @@ behavioral evidence and [`docs/api.md`](api.md) for the runtime declaration.
 The release must continue to state these limitations:
 
 - complete official HL7 shared-suite conformance and its importer;
-- date/time literals and values;
-- quantity and UCUM semantics;
-- advanced conversion, math, string, regular-expression, and navigation functions, and the general-purpose `aggregate()` function;
+- complete UCUM conformance, units outside the explicitly supported subset, derived-unit composition such as `60 'km' / 1 'h'`, `Quantity × Quantity`, calendar-duration arithmetic, and temporal arithmetic with Quantity;
+- `subsetOf`, `startsWith`, `endsWith`, `matches`, `matchesFull`, `convertsToInteger`, `lowBoundary`, `highBoundary`, `comparable`, `precision`, and `hasValue` (including the broader temporal/UCUM behavior those official cases exercise);
+- advanced conversion, math, string, regular-expression, and navigation functions beyond the explicitly listed implementations;
 - complex literals and additional standard value types;
 - standard environment variables beyond explicitly supplied external constants;
 - FHIRPath `3.0` STU3 features beyond the declared `stu3-aggregate-functions` subset; and
 - network I/O and global evaluator state in the pure evaluation boundary.
 
+## Official shared-suite classification snapshot
+
+The full checked-in R4 suite was imported and executed on 2026-09-07 from
+FHIR/fhir-test-cases commit `1.7.69` with the command sequence:
+
+```sh
+ruby script/import_vectors.rb conformance conformance/official-r4-core.json > /tmp/fhirpath-official-full.jsonl
+ruby script/run_vectors.rb /tmp/fhirpath-official-full.jsonl
+```
+
+The run produced 935 records; the full machine-readable report is checked in at
+`conformance/official-suite-report.json`. The runner's mechanical counts were:
+
+| Raw runner classification | Count | Manual disposition |
+|---|---:|---|
+| `pass` | 4 | passing evidence |
+| `defect` | 83 | 0 genuine parser defects (#66 resolved); 81 known unsupported/deferred behaviors; 1 expected-execution-failure (#65) |
+| `unsupported` | 0 | the current runner reports missing standard functions as raw defects when no expected error is declared |
+| `host-dependent` | 0 | no host-service cases reached evaluation |
+| `not-run` | 848 | fixture/import limitation: no verified matching JSON fixture for the source XML |
+
+The 81 known unsupported/deferred cases are grouped as follows: `subsetOf`
+(1), `startsWith` (1), `endsWith` (1), regular-expression `matches` and
+`matchesFull` (16), `convertsToInteger` (1), `lowBoundary` (28), `highBoundary`
+(24), `comparable` and the broader UCUM units it exercises (3), `precision`
+(5), and `hasValue` (1). These remain outside the published capability set and
+are covered by the limitations below; they are not evidence of regressions in
+supported behavior.
+
+One case is a genuine Ruby implementation defect and has a separate bug report:
+failure to parse the valid keyword-named function call
+`Appointment.identifier.contains('rand')` ([#66](https://github.com/niccoreyes/fhirpath-ruby/issues/66)), which is a lexer/parser
+collision between the `contains` binary operator and the `contains()` function
+name, independent of whether the string-function family is enabled. This was
+resolved by teaching the parser to treat keyword operators (`contains`, `in`)
+as member-invoked function names after a `.`.
+
+The `1 > 2 is Boolean` case ([#65](https://github.com/niccoreyes/fhirpath-ruby/issues/65)) is not a defect: the
+official suite marks `testPrecedence3` `invalid="execution"`, so the expression
+is expected to fail at evaluation time. With `is`/`as` binding tighter than the
+relational comparison, `1 > 2 is Boolean` parses as `1 > (2 is Boolean)`, which
+correctly raises a `TypeError` — matching the intended suite behavior.
+
+The 848 `not-run` records are not silently treated as passes. They identify
+where the official XML suite currently lacks a verified same-resource JSON
+fixture in the checked-in fixture set; improving fixture coverage is separate
+from evaluator conformance. Until those records are resolved or explicitly
+accepted as fixture limitations, the official suite cannot be used as a green
+release gate.
+
 ## Host-dependent behavior
 
 The gem bundles the dependency-free R4 JSON adapter described above. Callers

data/lib/fhirpath/capability.rb

@@ -8,7 +8,7 @@ module FHIRPath
       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
+      structured-errors quantity-ucum aggregate
     ].freeze
 
     # Named FHIRPath 3.0.0 STU3 subset the standard registry ships by default.
@@ -37,7 +37,7 @@ module FHIRPath
 
     def supports?(feature)
       trial_use.include?(feature.to_s) || host_features.include?(feature.to_s) ||
-        supports_model?(feature)
+        capability_set.include?(feature.to_s) || supports_model?(feature)
     end
 
     def supports_model?(release)

data/lib/fhirpath/compiled_expression.rb

@@ -16,6 +16,7 @@ module FHIRPath
     end
 
     def evaluate(resource, variables: {}, host: nil, options: {})
+      resource = normalize_resource(resource)
       context = EvaluationContext.new(
         root: resource,
         variables: variables,
@@ -31,5 +32,43 @@ module FHIRPath
     def call(resource, **kwargs)
       evaluate(resource, **kwargs)
     end
+
+    private
+
+    # Raw JSON document strings (the common HTTP-body shape for FHIR) are
+    # parsed once per call so Hash/Array resources never pay a JSON cost and
+    # the caller's String is left untouched. Detection is deliberately limited
+    # to text that opens with `{` or `[` after whitespace; any other String --
+    # plain text, JSON scalar text such as "null" or "123", quoted primitives
+    # -- keeps its pre-existing meaning as a singleton FHIRPath string value.
+    def normalize_resource(resource)
+      return resource unless resource.is_a?(String)
+
+      document = resource.dup
+      document = document.force_encoding(Encoding::UTF_8) if document.encoding == Encoding::ASCII_8BIT
+      unless document.valid_encoding?
+        if ascii_json_document?(resource)
+          raise JSONInputError.new('resource string is not valid JSON', expression: source)
+        end
+
+        return resource
+      end
+      document = document.encode(Encoding::UTF_8)
+      document = document.lstrip
+      document = document.delete_prefix("\uFEFF").lstrip
+      return resource unless document.start_with?('{', '[')
+
+      JSON.parse(document)
+    rescue JSON::ParserError => e
+      raise JSONInputError.new(
+        'resource string is not valid JSON',
+        cause: e, expression: source
+      )
+    end
+
+    def ascii_json_document?(resource)
+      index = resource.bytes.index { |byte| ![9, 10, 13, 32].include?(byte) }
+      index && [91, 123].include?(resource.getbyte(index))
+    end
   end
 end

data/lib/fhirpath/conformance/importer.rb

@@ -7,9 +7,8 @@ require_relative '../capability'
 
 module FHIRPath
   module Conformance
-    # Imports a selected, pinned subset of the official XML shared suite.
-    # The importer is deliberately Ruby-only so it is safe to use in tests and
-    # release checks without installing a second language runtime.
+    # Imports test cases from the official HL7 FHIRPath test suite.
+    # Can load either a pinned subset or the complete suite.
     class Importer
       DEFAULT_SUITE = 'FHIR/fhir-test-cases'
 
@@ -25,12 +24,14 @@ module FHIRPath
           target: manifest.fetch('target'),
           model: manifest.fetch('model', 'plain'),
           host_features: manifest.fetch('host_features', Capability.current.host_features),
-          case_ids: manifest['cases']
+          case_ids: manifest['case_ids'],
+          load_full_suite: manifest.fetch('load_full_suite', false)
         )
       end
 
       def initialize(source_root:, suite_path:, suite_commit:, suite: DEFAULT_SUITE, target: '2.0.0',
-                     fixture_root: nil, model: 'plain', host_features: Capability.current.host_features, case_ids: nil)
+                     fixture_root: nil, model: 'plain', host_features: Capability.current.host_features,
+                     case_ids: nil, load_full_suite: false)
         @source_root = File.expand_path(source_root)
         @suite_path = relative_path(suite_path)
         @fixture_root = fixture_root && relative_path(fixture_root)
@@ -40,6 +41,7 @@ module FHIRPath
         @model = model.to_s.freeze
         @host_features = Array(host_features).map(&:to_s).freeze
         @case_ids = case_ids&.map(&:to_s)&.freeze
+        @load_full_suite = load_full_suite
         validate_options
       end
 
@@ -61,11 +63,12 @@ module FHIRPath
       def import_xml
         document = REXML::Document.new(File.read(absolute_path(@suite_path)))
         tests = document.root.elements.to_a('group/test')
-        select_tests(tests).map { |test| record_for(test) }
+        tests_to_process = @load_full_suite ? tests : select_tests(tests)
+        tests_to_process.map { |test| record_for(test) }
       end
 
       def import_yaml
-        document = YAML.safe_load_file(absolute_path(@suite_path), permitted_classes: [], aliases: false)
+        document = YAML.safe_load(File.read(absolute_path(@suite_path)), permitted_classes: [], aliases: false) # rubocop:disable Style/YAMLFileRead
         subject = deep_copy(document['subject']) if document.is_a?(Hash)
         ordinal = 0
         records = []
@@ -98,7 +101,7 @@ module FHIRPath
       end
 
       def select_tests(tests)
-        return tests unless @case_ids
+        return tests unless @case_ids && !@load_full_suite
 
         by_id = tests.to_h { |test| [test.attributes.fetch('name').to_s, test] }
         @case_ids.map do |case_id|

data/lib/fhirpath/errors.rb

@@ -26,6 +26,14 @@ module FHIRPath
     end
   end
 
+  # The resource argument to an evaluate boundary was a String that opens like
+  # a JSON object or array (after leading whitespace) but is not valid JSON.
+  class JSONInputError < Error
+    def initialize(message = 'resource string is not valid JSON', code: :invalid_json, **kwargs)
+      super(message, code: code, **kwargs)
+    end
+  end
+
   class EvaluationError < Error
     def initialize(message = 'expression could not be evaluated', code: :evaluation_error, **kwargs)
       super(message, code: code, **kwargs)

data/lib/fhirpath/evaluator.rb

@@ -54,7 +54,11 @@ module FHIRPath
               when 'index'
                 context.index.nil? ? Collection.empty : Collection.new([context.index])
               when 'total'
-                context.total.nil? ? Collection.empty : Collection.new([context.total])
+                if context.variables.key?('total')
+                  context.variables['total']
+                else
+                  context.total.nil? ? Collection.empty : Collection.new([context.total])
+                end
               else
                 unless context.variables.key?(node.name)
                   raise EvaluationError.new("unknown variable: $#{node.name}",
@@ -215,6 +219,12 @@ module FHIRPath
         boolean_aggregate(receiver, node.name, node)
       when 'ofType'
         of_type(receiver, node, context)
+      when 'in'
+        # `in` as a function: receiver.in(collection) -> receiver in collection
+        membership_value(receiver, node.arguments.first, context)
+      when 'contains'
+        # `contains` as a function: receiver.contains(value) -> receiver contains value
+        membership_collection(receiver, node.arguments.first, context)
       when 'today'
         temporal_now(receiver, node, context, :date)
       when 'now'
@@ -225,6 +235,10 @@ module FHIRPath
         temporal_component(receiver, node, context, node.name)
       when 'timezone', 'timezoneOffset'
         temporal_timezone(receiver, node, context, node.name)
+      when 'aggregate'
+        aggregate(receiver, node, context)
+      when 'iif'
+        iif(receiver, node, context)
       else
         invoke_registered(node, receiver, context, spec)
       end
@@ -303,6 +317,51 @@ module FHIRPath
       Collection.new([decimal(total) / receiver.count])
     end
 
+    def iif(_receiver, node, context)
+      condition_expr = node.arguments[0]
+      true_expr = node.arguments[1]
+      false_expr = node.arguments[2]
+
+      cond_result = evaluate(condition_expr, context)
+      is_true = boolean_value(cond_result, condition_expr.span) == true
+
+      if is_true
+        true_expr ? evaluate(true_expr, context) : Collection.empty
+      else
+        false_expr ? evaluate(false_expr, context) : Collection.empty
+      end
+    end
+
+    def aggregate(receiver, node, context)
+      aggregator_expr = node.arguments.first
+      init_expr = node.arguments[1]
+
+      total = if init_expr
+                evaluate(init_expr, context)
+              else
+                Collection.empty
+              end
+
+      return total if receiver.empty?
+
+      receiver.items.each_with_index do |item, index|
+        item_col = Collection.new([item])
+        iter_context = context.derive(
+          focus: item_col,
+          index: index,
+          total: receiver.count,
+          variables: context.variables.merge(
+            'this' => item_col,
+            'total' => total
+          )
+        )
+
+        total = evaluate(aggregator_expr, iter_context)
+      end
+
+      total
+    end
+
     def extremum(receiver, mode, node)
       return Collection.empty if receiver.empty?
 
@@ -387,6 +446,11 @@ module FHIRPath
       return Collection.empty if value.empty?
 
       number = require_singleton(value, node.operand.span)
+      if number.is_a?(Quantity)
+        result = node.operator == :minus ? -number.value : number.value
+        return Collection.new([Quantity.new(value: result, unit: number.unit,
+                                            system: number.system, code: number.code)])
+      end
       unless numeric?(number)
         raise TypeError.new('unary arithmetic requires a number', code: :expected_number,
                                                                   span: node.span)
@@ -493,6 +557,9 @@ module FHIRPath
 
       left_value = require_singleton(left, node.left.span)
       right_value = require_singleton(right, node.right.span)
+      if left_value.is_a?(Quantity) || right_value.is_a?(Quantity)
+        return quantity_arithmetic(left_value, right_value, node.operator, node.span)
+      end
       if left_value.is_a?(::String) && right_value.is_a?(::String) && node.operator == :plus
         return Collection.new([left_value + right_value])
       end
@@ -527,6 +594,51 @@ module FHIRPath
       Collection.empty
     end
 
+    def quantity_arithmetic(left, right, operator, span)
+      if left.is_a?(Quantity) && right.is_a?(Quantity)
+        return Collection.empty unless left.compatible?(right)
+
+        converted = right.convert_to(left.unit)
+        return Collection.empty if operator == :divide && converted.value.zero?
+
+        result = case operator
+                 when :plus then Quantity.new(value: left.value + converted.value, unit: left.unit,
+                                              system: left.system, code: left.code)
+                 when :minus then Quantity.new(value: left.value - converted.value, unit: left.unit,
+                                               system: left.system, code: left.code)
+                 when :divide then decimal(left.value) / decimal(converted.value)
+                 else return Collection.empty
+                 end
+        return Collection.new([result])
+      end
+
+      if left.is_a?(Quantity) && numeric?(right)
+        return Collection.empty if %i[divide div mod].include?(operator) && zero?(right)
+        if operator == :multiply
+          return Collection.new([Quantity.new(value: left.value * right, unit: left.unit, system: left.system,
+                                              code: left.code)])
+        end
+        if operator == :divide
+          return Collection.new([Quantity.new(value: left.value / right, unit: left.unit, system: left.system,
+                                              code: left.code)])
+        end
+
+        return Collection.empty
+      end
+
+      if numeric?(left) && right.is_a?(Quantity)
+        if operator == :multiply
+          return Collection.new([Quantity.new(value: right.value * left, unit: right.unit,
+                                              system: right.system, code: right.code)])
+        end
+
+        return Collection.empty
+      end
+
+      raise TypeError.new('Quantity arithmetic requires a compatible Quantity or scalar',
+                          code: :incompatible_quantity, span: span)
+    end
+
     def comparison(node, context)
       left = evaluate(node.left, context)
       right = evaluate(node.right, context)
@@ -534,7 +646,15 @@ module FHIRPath
 
       left_value = require_singleton(left, node.left.span)
       right_value = require_singleton(right, node.right.span)
-      comparison = compare_values(left_value, right_value, node.span)
+      if left_value.is_a?(Quantity) || right_value.is_a?(Quantity)
+        return Collection.empty unless left_value.is_a?(Quantity) && right_value.is_a?(Quantity)
+        return Collection.empty unless left_value.compatible?(right_value)
+
+        right_value = right_value.convert_to(left_value.unit)
+        comparison = left_value.value <=> right_value.value
+      else
+        comparison = compare_values(left_value, right_value, node.span)
+      end
       result = case node.operator
                when :less_than then comparison.negative?
                when :less_or_equal then comparison <= 0
@@ -595,6 +715,30 @@ module FHIRPath
       Collection.new([left.items.any? { |candidate| equal?(candidate, value) }])
     end
 
+    # `in` as a function: receiver.in(collection) checks if the singleton receiver
+    # is a member of the argument collection.
+    def membership_value(receiver, argument_node, context, receiver_span = nil)
+      argument = evaluate(argument_node, context)
+      return Collection.empty if receiver.empty?
+
+      value = require_singleton(receiver, receiver_span || argument_node.span)
+      return Collection.new([false]) if argument.empty?
+
+      Collection.new([argument.items.any? { |candidate| equal?(value, candidate) }])
+    end
+
+    # `contains` as a function: receiver.contains(value) checks if the argument
+    # singleton is a member of the receiver collection.
+    def membership_collection(receiver, argument_node, context)
+      argument = evaluate(argument_node, context)
+      return Collection.empty if argument.empty?
+
+      value = require_singleton(argument, argument_node.span)
+      return Collection.new([false]) if receiver.empty?
+
+      Collection.new([receiver.items.any? { |candidate| equal?(candidate, value) }])
+    end
+
     def of_type(receiver, node, _context)
       # FHIRPath ofType() filters the collection to items matching the specified type
       # The argument is a type identifier (e.g., Integer, String, Decimal, Boolean,
@@ -728,6 +872,7 @@ module FHIRPath
       when 'date' then value.is_a?(Date)
       when 'datetime' then value.is_a?(DateTime)
       when 'time' then value.is_a?(Time)
+      when 'quantity' then value.is_a?(Quantity)
       else false
       end
     end

data/lib/fhirpath/functions.rb

@@ -16,12 +16,13 @@ module FHIRPath
       where select first last tail take skip ofType
       exists count empty not all
       allTrue anyTrue allFalse anyFalse
-      sum avg max min
+      sum avg max min aggregate iif
       today now time
       year month day hour minute second millisecond
       timezone timezoneOffset
+      in contains
     ].freeze
-    DELAYED_NAMES = %w[where select exists all].freeze
+    DELAYED_NAMES = %w[where select exists all aggregate iif].freeze
 
     def self.standard
       @standard ||= new(STANDARD_NAMES.each_with_object({}) do |name, specs|
@@ -33,19 +34,30 @@ module FHIRPath
       FunctionSpec.new(
         name: name,
         arity: standard_arity(name),
-        parameters: DELAYED_NAMES.include?(name) ? [:expression] : [],
+        parameters: standard_parameters(name),
         receiver: :collection,
         delayed: DELAYED_NAMES.include?(name)
       )
     end
 
+    def self.standard_parameters(name)
+      return [:expression] if %w[where select exists all].include?(name)
+      return %i[expression expression expression] if name == 'iif'
+      return %i[expression any] if name == 'aggregate'
+
+      []
+    end
+
     def self.standard_arity(name)
       return 0..1 if name == 'exists'
-      return 1 if name == 'all' || %w[where select take skip ofType].include?(name)
+      return 1 if name == 'all' || %w[where select take skip ofType in contains].include?(name)
+      return 1..2 if name == 'aggregate'
+      return 2..3 if name == 'iif'
 
       0
     end
-    private_class_method :standard_arity, :standard_spec
+
+    private_class_method :standard_arity, :standard_spec, :standard_parameters
 
     def initialize(specs = {})
       @specs = specs.transform_keys(&:to_s).dup.freeze

data/lib/fhirpath/models_r4.rb

@@ -19,6 +19,35 @@ module FHIRPath
               valueInteger valueRange valueRatio valueSampledData valueTime
               valueDateTime valuePeriod
             ].freeze
+          },
+          'Medication' => {
+            'medication' => %w[
+              medicationCodeableConcept medicationReference
+            ].freeze
+          },
+          'Condition' => {
+            'clinicalStatus' => %w[
+              clinicalStatusCodeableConcept clinicalStatusCoding
+            ].freeze,
+            'verificationStatus' => %w[
+              verificationStatusCodeableConcept verificationStatusCoding
+            ].freeze
+          },
+          'Procedure' => {
+            'outcome' => %w[
+              outcomeCodeableConcept outcomeReference
+            ].freeze,
+            'indication' => %w[
+              indicationCodeableConcept indicationReference
+            ].freeze
+          },
+          'DiagnosticReport' => {
+            'category' => %w[
+              categoryCodeableConcept categoryCoding
+            ].freeze,
+            'code' => %w[
+              codeCodeableConcept codeCoding
+            ].freeze
           }
         }.freeze
         CHOICE_TYPES = {
@@ -26,6 +55,35 @@ module FHIRPath
             'value' => %w[
               Quantity CodeableConcept string boolean integer Range Ratio SampledData time dateTime Period
             ].freeze
+          },
+          'Medication' => {
+            'medication' => %w[
+              CodeableConcept Reference
+            ].freeze
+          },
+          'Condition' => {
+            'clinicalStatus' => %w[
+              CodeableConcept Coding
+            ].freeze,
+            'verificationStatus' => %w[
+              CodeableConcept Coding
+            ].freeze
+          },
+          'Procedure' => {
+            'outcome' => %w[
+              CodeableConcept Reference
+            ].freeze,
+            'indication' => %w[
+              CodeableConcept Reference
+            ].freeze
+          },
+          'DiagnosticReport' => {
+            'category' => %w[
+              CodeableConcept Coding
+            ].freeze,
+            'code' => %w[
+              CodeableConcept Coding
+            ].freeze
           }
         }.freeze
 

data/lib/fhirpath/parser.rb

@@ -93,7 +93,7 @@ module FHIRPath
         @index += 1
         return token(SINGLE.fetch(char), char, start)
       end
-      return string_token(start) if char == "'"
+      return string_token(start) if ["'", '"'].include?(char)
       return external_token(start) if char == '%'
       return variable_token(start) if char == '$'
       return number_token(start) if char =~ /[0-9]/
@@ -103,12 +103,13 @@ module FHIRPath
     end
 
     def string_token(start)
+      quote = @source[@index]
       @index += 1
       value = +''
       until eof?
         char = @source[@index]
         @index += 1
-        return token(:string, value, start) if char == "'"
+        return token(:string, value, start) if char == quote
 
         if char == '\\'
           raise_error('unterminated string escape', @index - 1) if eof?
@@ -118,14 +119,14 @@ module FHIRPath
           value << char
         end
       end
-      raise_error('unterminated string literal', start)
+      raise_error('unterminated string literal', start, code: :unterminated_string)
     end
 
     def escaped_character
       escaped = @source[@index]
       @index += 1
       simple = { 'b' => "\b", 'f' => "\f", 'n' => "\n", 'r' => "\r",
-                 't' => "\t", '\\' => '\\', "'" => "'", '/' => '/' }
+                 't' => "\t", '\\' => '\\', "'" => "'", '"' => '"', '/' => '/' }
       return simple.fetch(escaped) if simple.key?(escaped)
       return unicode_escape if escaped == 'u'
 
@@ -362,6 +363,8 @@ module FHIRPath
   end
 
   class Parser
+    OPERATOR_FUNCTIONS = %i[in contains].freeze
+
     PRECEDENCE = {
       implies: 1,
       or: 2, xor: 2,
@@ -438,7 +441,20 @@ module FHIRPath
     def parse_primary
       token = advance
       node = case token.type
-             when :string, :integer, :decimal, :date, :time, :datetime
+             when :integer, :decimal
+               if current.type == :string
+                 unit = advance
+                 begin
+                   value = Quantity.new(value: token.value, unit: unit.value)
+                 rescue ArgumentError => e
+                   fail_parse("invalid Quantity literal: #{e.message}", :invalid_quantity,
+                              span_between(token.span, unit.span))
+                 end
+                 AST::Literal.new(value: value, span: span_between(token.span, unit.span))
+               else
+                 AST::Literal.new(value: token.value, span: token.span)
+               end
+             when :string, :date, :time, :datetime
                AST::Literal.new(value: token.value, span: token.span)
              when :identifier
                if %w[true false].include?(token.value)
@@ -483,14 +499,7 @@ module FHIRPath
       loop do
         case current.type
         when :dot
-          advance
-          name = expect(:identifier)
-          node = if current.type == :left_paren
-                   parse_function(node, name)
-                 else
-                   AST::MemberInvocation.new(receiver: node, name: name.value,
-                                             span: span_between(node.span, name.span))
-                 end
+          node = parse_member_access(node)
         when :left_bracket
           advance
           index = parse_expression(0)
@@ -511,8 +520,34 @@ module FHIRPath
       node
     end
 
+    def parse_member_access(node)
+      advance
+      if current.type == :identifier
+        name = expect(:identifier)
+        # Regular identifier: can be either a member access or function call
+        if current.type == :left_paren
+          parse_function(node, name)
+        else
+          AST::MemberInvocation.new(receiver: node, name: name.value,
+                                    span: span_between(node.span, name.span))
+        end
+      elsif current.type == :operator && OPERATOR_FUNCTIONS.include?(current.value)
+        # Keyword operators (in, contains): ONLY allowed as function calls with ()
+        name = current
+        advance
+        if current.type == :left_paren
+          parse_function(node, name)
+        else
+          fail_parse('keyword operator requires function call syntax', :unexpected_token, current.span)
+        end
+      else
+        fail_parse('expected a function name', :unexpected_token, current.span)
+      end
+    end
+
     def parse_function(receiver, name_token)
       name = name_token.is_a?(AST::Identifier) ? name_token.name : name_token.value
+      name = name.to_s
       start = receiver ? receiver.span : name_token.span
       expect(:left_paren)
       arguments = []

data/lib/fhirpath/types.rb

@@ -70,4 +70,73 @@ module FHIRPath
       end
     end
   end
+
+  # A FHIRPath Quantity backed by an explicitly bounded UCUM subset.
+  class Quantity < Value::Base
+    DEFAULT_SYSTEM = 'http://unitsofmeasure.org'
+
+    attr_reader :unit, :system, :code
+
+    def initialize(value = nil, unit = nil, **kwargs)
+      value = kwargs.fetch(:value, value)
+      unit = kwargs.fetch(:unit, unit)
+      raise ArgumentError, 'Quantity value is required' if value.nil?
+
+      decimal = value.is_a?(BigDecimal) ? value : BigDecimal(value.to_s)
+      raise ArgumentError, 'Quantity value must be finite' unless decimal.finite?
+
+      @unit = UCUM.validate(unit)
+      @system = (kwargs[:system] || DEFAULT_SYSTEM).to_s.dup.freeze
+      @code = (kwargs[:code] || @unit).to_s.dup.freeze
+      super(decimal)
+    rescue ArgumentError
+      raise
+    rescue StandardError => e
+      raise ArgumentError, "invalid Quantity value: #{e.message}"
+    end
+
+    def to_ruby
+      to_h
+    end
+
+    def to_h
+      { value: value, unit: unit, system: system, code: code }.freeze
+    end
+
+    def compatible?(other)
+      other.is_a?(Quantity) && definition.dimensions == other.send(:definition).dimensions
+    end
+
+    def convert_to(target_unit)
+      target = UCUM.validate(target_unit)
+      return self if target == unit
+      raise ArgumentError, "incompatible Quantity units: #{unit} and #{target}" unless compatible_unit?(target)
+
+      converted = value * definition.factor / UCUM.definition(target).factor
+      Quantity.new(value: converted, unit: target, system: system, code: target)
+    end
+
+    def ==(other)
+      other.is_a?(Quantity) && compatible?(other) && value == other.convert_to(unit).value
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, definition.dimensions, base_value].hash
+    end
+
+    private
+
+    def base_value
+      value * definition.factor
+    end
+
+    def definition
+      UCUM.definition(unit)
+    end
+
+    def compatible_unit?(target)
+      definition.dimensions == UCUM.definition(target).dimensions
+    end
+  end
 end

data/lib/fhirpath/ucum.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module FHIRPath
+  # Dependency-free, deliberately bounded UCUM support used by Quantity.
+  # Unknown atoms are rejected; callers should not interpret this subset as
+  # complete UCUM conformance.
+  module UCUM
+    UnitDefinition = Struct.new(:dimensions, :factor, keyword_init: true) do
+      def initialize(**kwargs)
+        super
+        self.dimensions = dimensions.freeze
+        freeze
+      end
+    end
+
+    MAX_EXPONENT = 12
+
+    UNIT_ATOMS = {
+      '1' => [{}, '1'],
+      'm' => [{ length: 1 }, '1'],
+      'cm' => [{ length: 1 }, '0.01'],
+      'mm' => [{ length: 1 }, '0.001'],
+      'km' => [{ length: 1 }, '1000'],
+      'g' => [{ mass: 1 }, '1'],
+      'kg' => [{ mass: 1 }, '1000'],
+      'mg' => [{ mass: 1 }, '0.001'],
+      'Mg' => [{ mass: 1 }, '1000000'],
+      'ug' => [{ mass: 1 }, '0.000001'],
+      'ng' => [{ mass: 1 }, '0.000000001'],
+      'L' => [{ volume: 1 }, '1'],
+      'mL' => [{ volume: 1 }, '0.001'],
+      'ML' => [{ volume: 1 }, '1000000'],
+      'uL' => [{ volume: 1 }, '0.000001'],
+      'mol' => [{ amount: 1 }, '1'],
+      'mmol' => [{ amount: 1 }, '0.001'],
+      'umol' => [{ amount: 1 }, '0.000001'],
+      's' => [{ time: 1 }, '1'],
+      'min' => [{ time: 1 }, '60'],
+      'h' => [{ time: 1 }, '3600']
+    }.freeze
+
+    module_function
+
+    def validate(unit)
+      text = unit.to_s.dup
+      definition(text)
+      text.freeze
+    end
+
+    def definition(unit)
+      raise ArgumentError, 'Quantity unit must not be blank' if unit.empty?
+      return UnitDefinition.new(dimensions: {}, factor: BigDecimal('1')) if unit == '1'
+
+      parts = unit.split('/', -1)
+      unless parts.length.between?(1, 2) && parts.none?(&:empty?)
+        raise ArgumentError, "unsupported Quantity unit: #{unit}"
+      end
+
+      numerator = product_definition(parts.first, unit)
+      denominator = build_denominator(parts, unit)
+      dimensions = combine_dimensions(numerator.dimensions, denominator.dimensions)
+      validate_dimensions!(dimensions)
+      UnitDefinition.new(dimensions: dimensions,
+                         factor: numerator.factor * denominator.factor)
+    end
+
+    def build_denominator(parts, unit)
+      return unitless_definition unless parts.length == 2
+
+      product_definition(parts.last, unit, exponent_sign: -1)
+    end
+    private_class_method :build_denominator
+
+    def validate_dimensions!(dimensions)
+      dimensions.each_value do |power|
+        next unless power.abs > MAX_EXPONENT
+
+        raise ArgumentError, "Quantity unit exponent exceeds #{MAX_EXPONENT}"
+      end
+    end
+    private_class_method :validate_dimensions!
+
+    def product_definition(product, original, exponent_sign: 1)
+      dimensions = {}
+      factor = BigDecimal('1')
+      product.split('*', -1).each do |atom_with_exponent|
+        atom_dimensions, atom_factor, exponent = atom_definition(atom_with_exponent, original, exponent_sign)
+        atom_dimensions.each do |dimension, power|
+          dimensions[dimension] = dimensions.fetch(dimension, 0) + (power * exponent)
+        end
+        factor *= BigDecimal(atom_factor)**exponent
+      end
+      UnitDefinition.new(dimensions: dimensions.reject { |_dimension, power| power.zero? }, factor: factor)
+    end
+    private_class_method :product_definition
+
+    def atom_definition(atom_with_exponent, original, exponent_sign)
+      match = /\A([^\^]+)(?:\^(-?\d+))?\z/.match(atom_with_exponent)
+      raise ArgumentError, "unsupported Quantity unit: #{original}" unless match && UNIT_ATOMS.key?(match[1])
+
+      exponent = (match[2] || '1').to_i * exponent_sign
+      raise ArgumentError, "Quantity unit exponent exceeds #{MAX_EXPONENT}" if exponent.abs > MAX_EXPONENT
+
+      atom_dimensions, atom_factor = UNIT_ATOMS.fetch(match[1])
+      [atom_dimensions, atom_factor, exponent]
+    end
+    private_class_method :atom_definition
+
+    def unitless_definition
+      UnitDefinition.new(dimensions: {}, factor: BigDecimal('1'))
+    end
+    private_class_method :unitless_definition
+
+    def combine_dimensions(numerator, denominator)
+      numerator.merge(denominator) { |_dimension, left, right| left + right }
+               .reject { |_dimension, exponent| exponent.zero? }
+    end
+    private_class_method :combine_dimensions
+  end
+end

data/lib/fhirpath/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module FHIRPath
-  VERSION = '0.2.0.pre3'
+  VERSION = '0.2.0.pre4'
   # A stable release requires the complete release gate to be deliberately
   # promoted. Keep pre-release status explicit while the shared-suite and
   # model-adapter work remains incomplete.

data/lib/fhirpath.rb

@@ -5,6 +5,7 @@ require_relative 'fhirpath/source_span'
 require_relative 'fhirpath/errors'
 require_relative 'fhirpath/capability'
 require_relative 'fhirpath/collection'
+require_relative 'fhirpath/ucum'
 require_relative 'fhirpath/types'
 require_relative 'fhirpath/ast'
 require_relative 'fhirpath/model'
@@ -46,8 +47,13 @@ module FHIRPath
     def evaluate(resource, expression, variables: {}, model: nil,
                  capability: Capability.current, functions: FunctionRegistry.standard,
                  options: {}, host: nil)
-      compile(expression, model: model, capability: capability, functions: functions)
-        .evaluate(resource, variables: variables, host: host, options: options)
+      compiled = if expression.is_a?(CompiledExpression)
+                   expression
+                 else
+                   compile(expression, model: model, capability: capability,
+                                       functions: functions)
+                 end
+      compiled.evaluate(resource, variables: variables, host: host, options: options)
     end
 
     def evaluate_first(resource, expression, variables: {}, model: nil,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fhirpath
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre3
+  version: 0.2.0.pre4
 platform: ruby
 authors:
 - Nicco Reyes
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -81,6 +81,7 @@ files:
 - lib/fhirpath/parser.rb
 - lib/fhirpath/source_span.rb
 - lib/fhirpath/types.rb
+- lib/fhirpath/ucum.rb
 - lib/fhirpath/vector_runner.rb
 - lib/fhirpath/version.rb
 - script/import_vectors.rb
@@ -91,7 +92,7 @@ licenses:
 metadata:
   release_status: pre-release
   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
+  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,quantity-ucum,aggregate
   source_code_uri: https://github.com/niccoreyes/fhirpath-ruby
   bug_tracker_uri: https://github.com/niccoreyes/fhirpath-ruby/issues
   documentation_uri: https://github.com/niccoreyes/fhirpath-ruby/blob/main/docs/api.md