v9.1.0

.github/workflows/pre-release.yml

@@ -34,6 +34,9 @@ jobs:
         with:
           java-version: 21
           distribution: "zulu"
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
 
       - name: Install uv
         uses: astral-sh/setup-uv@v6

.github/workflows/release.yml

@@ -34,6 +34,9 @@ jobs:
           java-version: 21
           distribution: "zulu"
 
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+
       - name: Install uv
         uses: astral-sh/setup-uv@v6
 

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "sql-on-fhir"]
 	path = sql-on-fhir
-	url = https://github.com/aehrc/sql-on-fhir-v2.git
+	url = https://github.com/FHIR/sql-on-fhir-v2.git

CONTRIBUTING.md

@@ -304,9 +304,54 @@ verified to be green within CI before merging to main. Merging to main
 automatically triggers publishing of artifacts and deployment of the software to
 production environments such as the Pathling website and sandbox instance.
 
-### Coding conventions
 
-#### Comments
+## Commit Message Format
+
+Write commit messages that capture the **objective** of the change, not the specific implementation details that can be obtained from the diff.
+
+**Structure**:
+```
+<type>: <succinct description of the objective>
+
+<optional body explaining the why and context>
+```
+
+**Types**:
+- `fix:` - Bug fixes or resolving warnings/errors
+- `feat:` - New features or enhancements
+- `refactor:` - Code restructuring without changing behavior
+- `docs:` - Documentation updates
+- `test:` - Test-related changes
+- `chore:` - Build, tooling, or dependency updates
+
+**Guidelines**:
+- Focus on **why** the change was needed and **what problem** it solves
+- Avoid mentioning specific files, line numbers, or implementation details
+- Keep the first line concise (under 72 characters when possible)
+- Use the body to provide context if the objective isn't obvious
+
+**Examples**:
+
+Good:
+```
+fix: Suppress Mockito dynamic agent loading warnings in Java 21
+
+Added JVM flag to suppress warnings about Mockito's inline mock maker
+self-attaching. Updated documentation to record Maven test configuration.
+```
+
+Poor:
+```
+fix: Added -XX:+EnableDynamicAgentLoading to pom.xml line 637
+
+Changed the argLine in maven-surefire-plugin configuration.
+Updated CLAUDE.md with new section at lines 102-120.
+```
+
+
+## Coding conventions
+
+### Comments
 
 - All comments must use correct grammar and be written as complete sentences.
 - Every comment, including single-line comments, must be terminated with a
@@ -320,7 +365,7 @@ production environments such as the Pathling website and sandbox instance.
   If you have a task that you want to complete in the future, please create an
   issue for it.
 
-#### Java
+### Java
 
 - Use meaningful and descriptive names for classes, methods, and variables
   (avoid abbreviations).
@@ -359,7 +404,7 @@ production environments such as the Pathling website and sandbox instance.
 - Ensure code is free of major bugs, vulnerabilities, and code smells as
   reported by SonarQube.
 
-#### Scala
+### Scala
 
 - Use meaningful and descriptive names
   following [Scala conventions](https://docs.scala-lang.org/style/).
@@ -376,7 +421,7 @@ production environments such as the Pathling website and sandbox instance.
 - Use appropriate collection methods (`map`, `filter`, `fold`) instead of loops.
 - Keep methods short and focused on a single responsibility.
 
-#### Python
+### Python
 
 - Follow [PEP 8](https://peps.python.org/pep-0008/) style guidelines.
 - Use meaningful and descriptive names with snake_case convention.
@@ -388,7 +433,7 @@ production environments such as the Pathling website and sandbox instance.
 - Write unit tests using [pytest framework](https://pytest.org/).
 - Keep imports organized: standard library, third-party, local imports.
 
-#### R
+### R
 
 - Follow [tidyverse style guide](https://style.tidyverse.org/) conventions.
 - Use snake_case for variable and function names.
@@ -401,7 +446,7 @@ production environments such as the Pathling website and sandbox instance.
 - Handle missing values (`NA`) appropriately.
 - Use consistent indentation (2 spaces recommended).
 
-#### Formatting
+### Formatting
 
 This repository uses multiple code formatters:
 

LICENSE

@@ -184,9 +184,9 @@ accessing the Software. Other third party software may also be identified in
 separate files distributed with the Software.
 
 * (Apache License, Version 2.0) FHIR Bulk Client (au.csiro.fhir:bulk-export:1.0.3 - https://github.com/aehrc/fhir-bulk-java)
-* (Apache License, Version 2.0) HAPI FHIR - Core Library (ca.uhn.hapi.fhir:hapi-fhir-base:8.4.0 - http://jamesagnew.github.io/hapi-fhir/)
-* (Apache License, Version 2.0) HAPI FHIR - Client Framework (ca.uhn.hapi.fhir:hapi-fhir-client:8.4.0 - https://hapifhir.io/hapi-deployable-pom/hapi-fhir-client)
-* (Apache License, Version 2.0) HAPI FHIR Structures - FHIR R4 (ca.uhn.hapi.fhir:hapi-fhir-structures-r4:8.4.0 - https://hapifhir.io/hapi-deployable-pom/hapi-fhir-structures-r4)
+* (Apache License, Version 2.0) HAPI FHIR - Core Library (ca.uhn.hapi.fhir:hapi-fhir-base:8.6.0 - https://hapifhir.io/)
+* (Apache License, Version 2.0) HAPI FHIR - Client Framework (ca.uhn.hapi.fhir:hapi-fhir-client:8.6.0 - https://hapifhir.io/hapi-deployable-pom/hapi-fhir-client)
+* (Apache License, Version 2.0) HAPI FHIR Structures - FHIR R4 (ca.uhn.hapi.fhir:hapi-fhir-structures-r4:8.6.0 - https://hapifhir.io/hapi-deployable-pom/hapi-fhir-structures-r4)
 * (Eclipse Public License 1.0) (GNU Lesser General Public License) Logback Classic Module (ch.qos.logback:logback-classic:1.5.18 - http://logback.qos.ch/logback-classic)
 * (Apache License, Version 2.0) WireMock (com.github.tomakehurst:wiremock-jre8-standalone:2.35.2 - http://wiremock.org)
 * (Apache License, Version 2.0) FindBugs-jsr305 (com.google.code.findbugs:jsr305:3.0.2 - http://findbugs.sourceforge.net/)
@@ -214,14 +214,14 @@ separate files distributed with the Software.
 * (Apache License, Version 2.0) Infinispan Component Annotations (org.infinispan:infinispan-component-annotations:15.0.3.Final - http://www.infinispan.org)
 * (Apache License, Version 2.0) Infinispan Core (org.infinispan:infinispan-core:15.0.3.Final - http://www.infinispan.org)
 * (Public Domain) JSON in Java (org.json:json:20240303 - https://github.com/douglascrockford/JSON-java)
-* (Eclipse Public License v2.0) JUnit Jupiter API (org.junit.jupiter:junit-jupiter-api:5.10.1 - https://junit.org/junit5/)
-* (Eclipse Public License v2.0) JUnit Jupiter Engine (org.junit.jupiter:junit-jupiter-engine:5.10.1 - https://junit.org/junit5/)
-* (Eclipse Public License v2.0) JUnit Jupiter Params (org.junit.jupiter:junit-jupiter-params:5.10.1 - https://junit.org/junit5/)
-* (MIT License) mockito-core (org.mockito:mockito-core:5.17.0 - https://github.com/mockito/mockito)
+* (Eclipse Public License v2.0) JUnit Jupiter API (org.junit.jupiter:junit-jupiter-api:5.11.4 - https://junit.org/junit5/)
+* (Eclipse Public License v2.0) JUnit Jupiter Engine (org.junit.jupiter:junit-jupiter-engine:5.11.4 - https://junit.org/junit5/)
+* (Eclipse Public License v2.0) JUnit Jupiter Params (org.junit.jupiter:junit-jupiter-params:5.11.4 - https://junit.org/junit5/)
+* (MIT License) mockito-core (org.mockito:mockito-core:5.18.0 - https://github.com/mockito/mockito)
 * (GNU General Public License (GPL), version 2, with the Classpath exception) JMH Core (org.openjdk.jmh:jmh-core:1.37 - http://openjdk.java.net/projects/code-tools/jmh/jmh-core/)
 * (GNU General Public License (GPL), version 2, with the Classpath exception) JMH Generators: Annotation Processors (org.openjdk.jmh:jmh-generator-annprocess:1.37 - http://openjdk.java.net/projects/code-tools/jmh/jmh-generator-annprocess/)
 * (MIT License) Project Lombok (org.projectlombok:lombok:1.18.38 - https://projectlombok.org)
 * (Apache License, Version 2.0) Scala Library (org.scala-lang:scala-library:2.13.15 - https://www.scala-lang.org/)
 * (Apache License, Version 2.0) JSONassert (org.skyscreamer:jsonassert:1.5.1 - https://github.com/skyscreamer/JSONassert)
 * (MIT License) SLF4J API Module (org.slf4j:slf4j-api:2.0.17 - http://www.slf4j.org)
-* (Apache License, Version 2.0) spring-boot-starter-test (org.springframework.boot:spring-boot-starter-test:3.3.11 - https://spring.io/projects/spring-boot)
+* (Apache License, Version 2.0) spring-boot-starter-test (org.springframework.boot:spring-boot-starter-test:3.4.11 - https://spring.io/projects/spring-boot)

benchmark/pom.xml

@@ -22,7 +22,7 @@
   <parent>
     <groupId>au.csiro.pathling</groupId>
     <artifactId>pathling</artifactId>
-    <version>9.0.1-SNAPSHOT</version>
+    <version>9.1.0-SNAPSHOT</version>
   </parent>
   <artifactId>benchmark</artifactId>
   <packaging>jar</packaging>
@@ -31,7 +31,7 @@
 
   <properties>
     <pathling.jmhVersion>1.37</pathling.jmhVersion>
-    <pathling.testDataVersion>1.0.0</pathling.testDataVersion>
+    <pathling.testDataVersion>1.1.0</pathling.testDataVersion>
   </properties>
 
   <dependencies>

benchmark/src/main/java/au/csiro/pathling/benchmark/PathlingBenchmark.java

@@ -90,4 +90,13 @@ public List<Row> usCoreBloodPressures(@Nonnull final PathlingBenchmarkState stat
         .collectAsList();
   }
 
+  @Benchmark
+  public List<Row> questionnaireResponseFlat(@Nonnull final PathlingBenchmarkState state) {
+    return state.getNdjsonSource()
+        .view("QuestionnaireResponse")
+        .json(state.getViewDefinitions().get("QuestionnaireResponseFlat"))
+        .execute()
+        .collectAsList();
+  }
+
 }

benchmark/src/main/java/au/csiro/pathling/benchmark/PathlingBenchmarkState.java

@@ -61,12 +61,12 @@
 public class PathlingBenchmarkState {
 
   /**
-   * Pre-defined view definitions used in benchmarks to test complex query scenarios. These view
-   * definitions are taken from the SQL on FHIR implementation guide.
+   * Pre-defined view definitions used in benchmarks to test query scenarios. These view definitions
+   * are taken from the SQL on FHIR implementation guide.
    */
   private static final List<String> VIEW_DEFINITIONS = List.of(
       "ConditionFlat", "EncounterFlat", "PatientAddresses", "PatientAndContactAddressUnion",
-      "PatientDemographics", "UsCoreBloodPressures"
+      "PatientDemographics", "UsCoreBloodPressures", "QuestionnaireResponseFlat"
   );
 
   /**
@@ -163,7 +163,8 @@ public PathlingBenchmarkState() {
   public void setup() {
     // Define the FHIR resource types that will be loaded for benchmarking
     // These represent core clinical data types commonly used in healthcare analytics
-    final List<String> resourceTypes = List.of("Patient", "Observation", "Condition", "Encounter");
+    final List<String> resourceTypes = List.of("Patient", "Observation", "Condition", "Encounter",
+        "QuestionnaireResponse");
 
     // Initialize the appropriate data source based on the benchmark parameter
     if ("ndjson".equals(sourceType)) {

benchmark/src/main/resources/QuestionnaireResponseFlat.json

@@ -0,0 +1,84 @@
+{
+  "resourceType": "ViewDefinition",
+  "id": "QuestionnaireResponseFlat",
+  "name": "questionnaire_response_flat",
+  "description": "Flattened questionnaire response data with recursively unnested items. One row per item at any nesting level. Useful for analysing questionnaire answers across all item types and testing the repeat directive with multiple expressions.",
+  "status": "draft",
+  "resource": "QuestionnaireResponse",
+  "select": [
+    {
+      "column": [
+        {
+          "path": "getResourceKey()",
+          "name": "id",
+          "description": "Unique questionnaire response identifier"
+        },
+        {
+          "path": "questionnaire",
+          "name": "questionnaire",
+          "type": "canonical",
+          "description": "Canonical URL of the questionnaire being answered"
+        },
+        {
+          "path": "status",
+          "name": "status",
+          "type": "code",
+          "description": "Response status: in-progress, completed, amended, entered-in-error, stopped"
+        },
+        {
+          "path": "subject.getReferenceKey(Patient)",
+          "name": "patient_id",
+          "description": "Patient identifier for joining with patient views"
+        },
+        {
+          "path": "authored",
+          "name": "authored",
+          "type": "dateTime",
+          "description": "Date and time the response was authored in ISO 8601 format"
+        }
+      ]
+    },
+    {
+      "repeat": [
+        "item"
+      ],
+      "column": [
+        {
+          "path": "linkId",
+          "name": "item_link_id",
+          "description": "Unique identifier for this item within the questionnaire definition"
+        },
+        {
+          "path": "answer.value.ofType(integer)",
+          "name": "answer_value_integer",
+          "description": "Integer answer value; null if answer is not an integer or no answer provided"
+        },
+        {
+          "path": "answer.value.ofType(string)",
+          "name": "answer_value_string",
+          "description": "String answer value; null if answer is not a string or no answer provided"
+        },
+        {
+          "path": "answer.value.ofType(boolean)",
+          "name": "answer_value_boolean",
+          "description": "Boolean answer value; null if answer is not a boolean or no answer provided"
+        },
+        {
+          "path": "answer.value.ofType(decimal)",
+          "name": "answer_value_decimal",
+          "description": "Decimal answer value; null if answer is not a decimal or no answer provided"
+        },
+        {
+          "path": "answer.value.ofType(date)",
+          "name": "answer_value_date",
+          "description": "Date answer value in YYYY-MM-DD format; null if answer is not a date or no answer provided"
+        },
+        {
+          "path": "answer.value.ofType(time)",
+          "name": "answer_value_time",
+          "description": "Time answer value; null if answer is not a time or no answer provided"
+        }
+      ]
+    }
+  ]
+}

encoders/pom.xml

@@ -31,7 +31,7 @@
   <parent>
     <groupId>au.csiro.pathling</groupId>
     <artifactId>pathling</artifactId>
-    <version>9.0.1-SNAPSHOT</version>
+    <version>9.1.0-SNAPSHOT</version>
   </parent>
   <artifactId>encoders</artifactId>
   <packaging>jar</packaging>

encoders/src/main/java/au/csiro/pathling/encoders/FhirEncoders.java

@@ -24,6 +24,8 @@
 
 package au.csiro.pathling.encoders;
 
+import au.csiro.pathling.config.Configurable;
+import au.csiro.pathling.config.EncodingConfiguration;
 import au.csiro.pathling.encoders.datatypes.DataTypeMappings;
 import ca.uhn.fhir.context.FhirContext;
 import ca.uhn.fhir.context.FhirVersionEnum;
@@ -39,7 +41,7 @@
 /**
  * Spark Encoders for FHIR Resources. This object is thread safe.
  */
-public class FhirEncoders {
+public class FhirEncoders implements Configurable<EncodingConfiguration> {
 
   /**
    * The reasonable default set of open types to encode with extension values.
@@ -88,7 +90,7 @@ public class FhirEncoders {
   private static final Map<FhirVersionEnum, FhirContext> FHIR_CONTEXTS = new ConcurrentHashMap<>();
 
   /**
-   * @return the FHIR context used by encoders produced by this instance.
+   * The FHIR context used by encoders produced by this instance.
    */
   @Getter
   private final FhirContext context;
@@ -258,4 +260,21 @@ public FhirVersionEnum getFhirVersion() {
     return context.getVersion().getVersion();
   }
 
+  /**
+   * Returns the encoding configuration that corresponds to this FhirEncoders instance.
+   * <p>
+   * The configuration is constructed on-demand from the current state of this instance.
+   *
+   * @return the encoding configuration, never null
+   */
+  @Nonnull
+  @Override
+  public EncodingConfiguration getConfiguration() {
+    return EncodingConfiguration.builder()
+        .maxNestingLevel(maxNestingLevel)
+        .enableExtensions(enableExtensions)
+        .openTypes(openTypes)
+        .build();
+  }
+
 }