FHIR Protocol Buffers
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.
UnmarshalError
protobuf and python-date-util package dependencies, allowing fluctuations in minor/patch versionresource_utils module with functions for working with Bundles and ContainedResourcesFhirPackage from Java for abstracting over FHIR JSON Implementation Guidesjson_format tests on FHIR versionpyenv version in distribution utilitiesbackports.zoneinfo to ensure pypi dependencies don’t pull in backports.zoneinfo for interpreters >=3.9ErrorReporter to expose encountered profile conversion and validation issuesDecimal primitives, adds support for FHIRPath substring functions, and includes general FHIRPath performance improvementsDate/Datetime year is always printed with four digits according to the specificationX.reference to a string during FHIRPath evaluationunion operatorExtensions with singular repeated fieldsproto.MessageV1 APIs are migrated to proto.MessageV2
value[x] field (previously one was silently chosen)JsonToProto example. For usage, see github.com/google/fhir-examples//java/com/google/fhir/common into individual targetsProtoGenerator to dump split resources to a single .zip fileDecimal to conform to the FHIR specificationrules_python to 0.1.0
requirements.txt to allow for alternate patch versionsDescriptorProto from the annotation_utils APIjson_format.json_fhir_string_to_proto
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.
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.
jsonformat APIGolang 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.
Fixed a bug where references would fail validation in Python and C++ if they did not conform to a known schema.
With the newly-updated BUILD structure for Java in place, look forward to added multi-version support and profiling in Java.
//py/distribution with a README.md, Dockerfile, and shell script for building and testing sdist and bdist_wheels from source for google-fhir
This release adds several bug fixes for the Python release of FhirProto in addition to some quality-of-life and performance improvements.
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).
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:
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.
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).
.pyi annotation stubs for generated proto classes, and py.typed file for the google-fhir package per PEP0561.ANALYTIC, require mutation)This release adds two minor patch improvements: A Java Maven jar, and performance improvements for python json_format.
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>
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.
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
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.
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.
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.
We intend to have a fast-follow v0.6.1 that will contain a few patch improvements:
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.