Health tool (FHIR/HL7)

The health tool generates accelerators for developing healthcare integrations in Ballerina.

The Health tool can generate accelerators primarily focussed on the Fast Healthcare Interoperability Resources (FHIR) standard. The Health tool is supported from Ballerina Swan Lake version 2201.7.0 onwards.


Download a directory containing all FHIR specification definition files. You can download a preferred standard implementation guide from the FHIR Implementation Guide registry.

Note: It is recommended to use the STU version of the implementation guides. Make sure that the downloaded specification archive has the StructureDefinition, ValueSet, and CodeSystem files for the Implementation Guide (IG) resources when extracted.


This tool generates a Ballerina package for a given FHIR implementation guide. The FHIR resources in the implementation guide will be represented as Ballerina records including the correct cardinality constraints and metadata.

FHIR integration developers can leverage the generated package when transforming custom health data into FHIR format without referring to the specification.

Command options

The parameters that are available with the tool are listed below.

Command optionDescriptionMandatory/Optional
-m, --modeMode can be package. If mode is set to package, a Ballerina package will be generated including all the records and types. New modes will be added in future releases.Mandatory
-o, --outputLocation of the generated Ballerina artifacts. If this path is not specified, the output will be written to the same directory from which the command is run.Optional
--package-nameName of the Ballerina package to be generated. The package name can be explicitly set using this argument. Unless specified, the default name of the implementation guide will be taken to construct the name of the package. For more information, see the name field.Optional
--org-nameOrganization name of the Ballerina package to be generated. For more information, see the org field.Optional
-v, --versionPrint the version information of the Health tool.Optional
-h, --helpPrint the usage details of the Health tool.Optional

Install the tool

Pull the Health tool from Ballerina Central.

$ bal tool pull health
health:1.0.0 pulled successfully.
health:1.0.0 successfully set as the active version.

Create the package

Follow the steps below to create the package.

  1. Download the JSON Definitions ZIP archive from the Carin BB implementation guide and extract it to your current directory.

  2. Run the tool with the required arguments to generate the package.

    Note: Provide values for mandatory arguments. Make sure to give the directory path of the downloaded FHIR definitions as the last argument.

    $ bal health fhir -m package --org-name healthcare_samples --package-name carinbb_package -o gen ./definitions.json
    Ballerina FHIR package generation completed successfully.
  3. Build the generated package.

    $ cd gen/carinbb_package
    $ bal pack
    Compiling source
    Creating bala
  4. Push it to a repository.

    Tip: You can push either to the local repository or the remote repository in Ballerina Central.

    $ bal push --repository local
    Successfully pushed target/bala/healthcare_samples-carinbb_package-any-0.0.1.bala to 'local' repository.


Follow the steps below to try out an example use case of the Health tool.

  1. Clone the artifacts of the example and extract them to a preferred location.

    Note: Make sure to add the correct version and repository to the Ballerina.toml file. The generated package is imported and the business logic/mapping is implemented using the generated FHIR resource records in the main.bal file.

  2. Run the Ballerina project and validate the output.

    $ bal run
    Compiling source
    Running executable
  3. Invoke the API to try it out.

    $ curl --location --request GET 'http://localhost:9090/Patient/2121'

    You can view the response shown below.

        "resourceType": "Patient",
        "gender": "male",
        "id": "2121",
        "identifier": [
                "system": "",
                "value": "2121"
        "meta": {
            "profile": [
        "name": [
                "family": "Doe",
                "given": [