v0.7.4 - IG Loading APIs and Better Error Handling

This release adds several improvements to the FhirPackage class in both Python and C++. Initialization of the class is much faster, as it now lazy-loads all resources in its given package. To access its resources, the class supplies methods for looking up specific resources by their URLs. To maintain backwards compatibility, iterators which lazily load and parse all resources in the package one-by-one are provided.

A new FhirPackageManger class has also been added, which provides the same semantics for looking up a resource by URL over a given set of FhirPackages. This makes it easier to work with multiple FHIR IGs and sets of resources defined over different packages.

Additionally, this release simplifies C++ error handling by splitting the previous ErrorReporter into two different classes with more clearly defined roles. ScopedErrorReporter is used internally by implementers to manage the context in which errors are reported. ErrorHandler provides a listener-like interface that callers can pass into functions and use to introspect issues encountered by the function. An increasing number of APIs support ErrorHandler arguments, such as JsonFormat for converting between FhirProto and JSON. This allows processes to continue to run even when they encounter serious data issues by aggregating errors in OperationOutcomes rather than immediately returning or raising an exception. Legacy behavior of failing on any data issue can be maintained by passing the FailFastErrorReporter::FailOnErrorOrFatal() error handler.

Finally, this release modifies the Proto file generator to generate message definitions in alphabetical order to ensure order stability. If you’re currently using your own generated protos, you will need to regenerate them to pick up the new ordering.

v0.7.3 - Go Error Handling & Stable Proto Tag Numbers

C++

• Minor multithreading bug fixes around shared mutable data objects
• Fixed error during parsing where a string with a colon followed by a number could be incorrectly interpreted as a decimal

Go

• Introduced error reporter API
• Add support for error reporter to Unmarshaller
• Introduced a “severity” field to UnmarshalError

Java

• Added logic for stabilizing tag numbers between generated versions of FhirProtos

Python

• Further loosened version constraints for protobuf and python-date-util package dependencies, allowing fluctuations in minor/patch version
• Added resource_utils module with functions for working with Bundles and ContainedResources
• Ported FhirPackage from Java for abstracting over FHIR JSON Implementation Guides
• Corrected bug where nested choice types that were primitive extensions were being incorrectly mapped during parsing

v0.7.2 - Patch fix to v0.7.1

C++

Bug Fixes

• Fix bug in analytic printer when printing Id fields on a Choice type

Java

• Add support in the Proto Generator for FHIRPath warnings
• Minor Proto Generator improvements

Python

• Parameterize primitive json_format tests on FHIR version
• Pin pyenv version in distribution utilities
• Add ErrorReporter base class for future delegating of error handling encountered during FHIRPath validation and FHIRProto/JSON conversion

Bug Fixes

• Add environment marker for backports.zoneinfo to ensure pypi dependencies don’t pull in backports.zoneinfo for interpreters >=3.9

v0.7.1 - General performance improvements and bug fixes

C++

• Adds an ErrorReporter to expose encountered profile conversion and validation issues
• Improves FHIRPath handling of Decimal primitives, adds support for FHIRPath substring functions, and includes general FHIRPath performance improvements
• Minor performance improvements and bug fixes to parsing/printing

Bug Fixes

• Ensure FHIR Date/Datetime year is always printed with four digits according to the specification
• Properly resolve X.reference to a string during FHIRPath evaluation
• Fix FHIRPath handling of the union operator
• Fix handling of parsing complex Extensions with singular repeated fields
• Fix FHIR parser race condition present in memoization

Go

• Deprecated proto.MessageV1 APIs are migrated to proto.MessageV2
• Marshalling extension fields to the analytic schema will now fail as conflicting if the field name differs only by case
• Return an error when unmarshalling JSON that contains multiple values for a value[x] field (previously one was silently chosen)

Java

• Eliminate legacy JsonToProto example. For usage, see github.com/google/fhir-examples
• Break //java/com/google/fhir/common into individual targets
• Update ProtoGenerator to dump split resources to a single .zip file
• Add ability to mark code values as deprecated during proto generation
• Remove order-dependence during profile generation

Bug Fixes

• Remove upper-bound check for Decimal to conform to the FHIR specification

Python

• Add support for Python 3.9 interpreters
• Bump rules_python to 0.1.0
• Loosen package dependencies in requirements.txt to allow for alternate patch versions
• Remove DescriptorProto from the annotation_utils API

Bug Fixes

• Return proper exception type from json_format.json_fhir_string_to_proto

Other

• Add search parameters to R4 protobuf definitions
• Introduce language-agnostic primitive test suite protos

v0.7.0 - Golang Modules, Java Build Cleanup

Go Modules

This release adds support for go get and go modules. This means that the Go libraries may now be built and used without Bazel. Note that proto imports must now be prefixed by github.com/google/fhir/go.

See the Go Examples in the Fhir-Examples repo for an example of using the FhirProto libraries with modules.

Java BUILD Cleanup

FhirProto Java has outgrown a single BUILD file. To bring this in line with other languages, there is now one BUILD rule per directory. To avoid long and redundant paths, some Java directories have been collapsed:

@com_google_fhirproto//java/src/main/java -> @com_google_fhirproto//java
@com_google_fhirproto//java/src/test/java -> @com_google_fhirproto//javatests

This means that imports will now better reflect the directory structure, like in other languages. For instance:

com.google.fhir.common.JsonFormat will be provided by @com_google_fhirproto//java/com/google/fhir/common:json_format, instead of @com_google_fhirproto//java:json_format

Note that no actual Java package names have been changed, but BUILD dependencies have to be updated.

For an example of how to update your dependencies, see the Java Fhir Examples commit.

Golang jsonformat API

Golang jsonformat unmarshalling now uses the same validation conventions as other languages. Both NewUnmarshaller and NewUnmarshallerWithoutValidation will enforce basic FHIR primitive validity - e.g., DateTimes must be valid FHIR DateTimes, bound codes must use a valid code string from the correct code system. The difference is that the default Parser will also enforce StructureDefinition/Profile constraints such as required fields and FHIRProto expressions. If you want to be able to parse incomplete/non-compliant protos, use NewUnmarshallerWithoutValidation. Finally, the default (i.e., validating) parser will no longer fail on the first error, and instead return all the errors it encountered in the case of a failure.

Other

Fixed a bug where references would fail validation in Python and C++ if they did not conform to a known schema.

Upcoming

With the newly-updated BUILD structure for Java in place, look forward to added multi-version support and profiling in Java.

v0.6.3 - Go FHIR validation library

Go

• Upgrade protobuf dependency from github.com/golang/protobuf/proto to google.golang.org/protobuf/proto internally
  • Overall marshaller/unmarshaller performance is improved
  • Upcoming change will migrate the public API
• Introduce fhirvalidate package. This splits out most of the validation that was being done in the unmarshaller so it can be performed independently on the FHIR protos. Consequently, NewUnmarshallerWithoutValidation is now more lenient.

Python

• Add //py/distribution with a README.md, Dockerfile, and shell script for building and testing sdist and bdist_wheels from source for google-fhir

Bug fixes

• Fixes #25, where a dangling comma was being added when an empty ContainedResource was written to JSON

v0.6.2 - Python FhirProto Bug Fixes and Performance Improvements

This release adds several bug fixes for the Python release of FhirProto in addition to some quality-of-life and performance improvements.

Python FhirProto Bug Fixes

Analytic FHIR primitive printing

We discovered that leveraging the json_format.py module for analytic printing would result in an AttributeError exception being thrown. The bug has been corrected and additional test coverage has been added to ensure that Analytic FHIR is tested in all offered versions of the FHIR standard (at time of writing, STU3 and R4).

"Distant future" timezone-aware arithmetic

Previously, the internal module _primitive_time_utils.py leveraged dateutil for datetime.datetime timezone arithmetic. However, dateutil is unable to properly account for DST offsets when performing datetime arithmetic for dates in the distant future. This is a known dateutil bug and more info can be found at:

• dateutil/dateutil#462
• dateutil/dateutil#590

This is addressed with PEP615 for Python interpreters >=3.9. backports.zoneinfo provides backwards compatibility for interpreters >=3.6, < 3.9, which we now leverage.

Python Performance Improvements

Minor performance improvements in PrimitiveWrapper construction were added via dict-lookup for primitive wrapper class. Additionally, a fix was made in annotation_utils.py to avoid linear attribute access when retrieving options from a Descriptor for C++-based protos (which we default to in both bazel and pypi).

Additional Python QoL Improvements

• Added .pyi annotation stubs for generated proto classes, and py.typed file for the google-fhir package per PEP0561.
• Added additional safety checks during testing to ensure integrity of protos during printing (specifically since some print styles, e.g. ANALYTIC, require mutation)

v0.6.1: Java Maven Jar and Python Performance Fixes

This release adds two minor patch improvements: A Java Maven jar, and performance improvements for python json_format.

Java Maven Jar

With this release, the R4 protos and several utilities are made available as a Java binary on Google's Maven repository. For examples on how to use this, see the FhirExamples repo.

The binary can be added as a dependency by adding the following to your build.gradle file if your project uses Gradle:

repositories {
    maven {
        google()
    }
}
dependencies {
    implementation 'com.google.fhir:r4:0.6.1'
}

If your project uses Maven instead of Gradle, ensure https://maven.google.com is in your repositories configuration and then add the following dependency to your pom.xml:

<dependencies>
  <dependency>
    <groupId>com.google.fhir</groupId>
    <artifactId>r4</artifactId>
    <version>0.6.1</version>
  </dependency>
</dependencies>

Python Performance Fix

We noticed that a lot of redundant work was being done to dynamically construct message definitions. These are now properly cached, resulting in a big performance improvement to parsing FHIR JSON to FhirProto.

v0.6.0: Parsing, Printing and Validating in Python

This release adds Python implementations of some of the core FhirProto libraries: Parsing raw JSON into FhirProto, Printing FhirProtos into JSON, and Validating FhirProtos for FHIR data requirements such as required fields and Value Set bindings. These APIs support FHIR versions STU3 and R4.

Examples of this usage (using both Bazel and Pip) can be found in the fhir-examples repo

Proto Package Change

This release contains a backwards compatibility-breaking change to the import paths and file locations of protos. In order to provide better namespacing and parallelism with other languages, proto files have been moved from

//proto/... to //proto/google/fhir/proto/

This means that BUILD deps must be updated:

@com_google_fhir//proto/... to @com_google_fhir//proto/google/fhir/proto/...

Similarly, some source files will have to update import statements. Examples of these changes can be found in the changes to fhir-examples.

PyPi Distribution

FhirProto for Python is available on pypi.org under the package google-fhir. The PyPi package is installable via the pip package manager. The google-fhir package includes the same support for parsing, printing, and validation, as what is present in the source repository and available via bazel for FHIR versions STU3 and R4.

We recommend installing into a Python3 virtual environment such as venv to install google-fhir along with your other project requirements. See the instructions at https://pypi.org/project/google-fhir/ for installation.

Note that *_test.py modules and accompanying data files are not included in the PyPi distribution as a means to help reduce the package size. If you need the test modules or the accompanying data files themselves, both are available in the raw source code and executable via the bazel project. See https://github.com/google/fhir for more details on how to execute via supported versions of bazel.

Machine Learning and FhirProto

The code for generating TensorFlow sequence examples, as well as the code for labeling and modeling with Fhir SeqEx has been removed from the core FhirProto library. Its new home will be https://github.com/google/fhir-ml. This provides better separation of core functionality vs uses of FhirProto, as well as helping to keep binary size and compile times down. Keep an eye out for the initial commit of code to that repo very soon.

Other changes

• google::fhir::Status and google::fhir::StatusOr have been removed in favor of absl::Status and absl::StatusOr

Upcoming Changes

We intend to have a fast-follow v0.6.1 that will contain a few patch improvements:

• Merge in some performance improvements to Python parsing
• Provide a Maven jar for including Java code in build systems like Gradle without Bazel

v0.5.4 - Update to Go import paths

This release migrates the Go library import paths to use the familiar Go-gettable github.com prefixed import paths (and moves the code location to /go/jsonformat). This is the first step in making the Go library Go mod compliant. Current users of the library will need to migrate their import paths from google/fhir/jsonformat/jsonformat to github.com/google/fhir/go/jsonformat when upgrading to this new version.

Additional changes include some refreshes to the machine-learning code, including making the C++ ML code version independent, and bumping the Python ML code from STU3 to R4. This is in anticipation of an upcoming major release that will separate TensorFlow/ML code into a standalone library that runs with FhirProto as a dep.