This wiki has undergone a migration to Confluence found Here

Difference between revisions of "Using the FHIR Validator to transform content"

From HL7Wiki
Jump to navigation Jump to search
Line 93: Line 93:
The general pattern is:
The general pattern is:
   java -jar org.hl7.fhir.validator.jar [cda-file-name] -transform -ig [path-to-CDA-logical-model] -ig [path-to-ccda-maps] -output [dest-name] -ig [current-fhir-version]
   java -jar org.hl7.fhir.validator.jar [cda-file-name] -transform -ig [path-to-CDA-logical-model] -ig [path-to-ccda-maps] -output [dest-name] -ig [current-fhir-version]
== R3 / R4 conversions ==
== R3 / R4 conversions ==

Revision as of 02:08, 23 October 2018

This page describes how to use the validator to transform content from one format to another using the [FHIR Mapping Language]. To use the validator for validation, see Using the FHIR Validator

Running the validator

To use the validator, download the jar from Specifically, download the official FHIR validator at Note that you always use the current validator from the build, irrespective of what transforms you are running.. You need a current version of java to run the validator:

 java -jar org.hl7.fhir.validator.jar -transform  [params]

The params control how the transfomration occurs, and are documented here.

In general, in order to perform the transform, you need to specify:

  • what to transform
  • the map to use to transform it
  • where to put the tranform

+ you need to tell the engine where to find all the relevant logical models, mapping libraries, etc.

Choosing what to transform

There must be at just one source param, which is not a named parameter. All other parameters are 'named parameters' - e.g. -name value. Any parameter preceded by a recognised name is interpreted as a source parameter

The source parameter can contain either:

  • a URL that returns the content to transform (authentication is not supported)
  • a filename (relative to the current directory, or absolute)
  • a directory that contains a file to transform
  • a pattern: a directory followed by a filename with an embedded asterisk. E.g. foo*-examples.xml or someresource.*, etc

In the case of a directory or a pattern, it is an error if there is more than one matching file.


 java -jar org.hl7.fhir.validator.jar -transform /tmp/resource.json  (.. other parameters needed...)


 java -jar org.hl7.fhir.validator.jar -transform c:\temp\patient.xml  (.. other parameters needed...)

Note: the source does not need to be a FHIR resource - it needs to be whatever the transform reads from

Choosing what to produce

The parameter -output must be provided, and is a file will be created to contain the output.

 java -jar org.hl7.fhir.validator.jar -transform c:\temp\patient.xml -output c:\temp\output.xml  (.. other parameters needed...)

Specifying the map to start with

A parameter -map must be specified that is canonical URI of the map to use.

 java -jar org.hl7.fhir.validator.jar -transform c:\temp\patient.xml -output c:\temp\output.xml -map  (.. other parameters needed...)

The map must already be loaded using the -ig parameter (see below)

choosing where to save the log

The transform engine can produce a comprehensive log of the output from running the transform that is necessary when troubleshooting the transform process. By default, the transform engine writes the output to the console screen, but that can be redirected to a file using the -log parameter:

 java -jar org.hl7.fhir.validator.jar -transform c:\temp\patient.xml -log c:\temp\log.txt  (.. other parameters needed...)

Specifying libraries

Before it can actually run the transform, and handle non-FHIR input and output, the transform engine will need to load the relevant mapping libraries, logical models, and the relevant FHIR version. All loading the of the input is done using the -ig parameter:

 java -jar org.hl7.fhir.validator.jar -transform c:\temp\patient.xml -output c:\temp\output.xml 
   -log c:\temp\log.txt -map  
   -ig acme.fhir.formats -ig c:\temp\acme\maps

The -ig parameter can be one of the following:

  • a package (e.g. acme.fhir.formats)
  • the canonical URL for an implementation guide containing content
  • a file name
  • a directory containing resources (*.xml. *.json, or *.map)

Note that there's no requirement for any order etc - all resources found from the specified -ig parameters are loaded into the transform engine cache. The transform engine uses StructureDefinitions, ValueSets, CodeSystems, ConceptMaps, and StructureMap resources, and ignores the rest.



CCDA to FHIR is an exampe of converting a logical model to a FHIR resource (a bundle). In order to get this to run, the following has to be provided as parameters:

  • the CDA Logical model as published in the CDA on FHIR Implementation guide (the easiest way is simply to use the package hl7.fhir.cda#2.0, though you can use a local directory with the same content if you're testing a fix to the package)
  • the standard CCDA to FHIR map files. These are not yet published as a package, so the command assumes you have sourced them and have them locally in c:\temp\cda\maps (NOTE: This can be found at
  • the actual map to run is called (this was the URL chosen by the author of the CCDA to FHIR Map files

This gives a command of:

 java -jar org.hl7.fhir.validator.jar c:\temp\cda.xml-transform -ig hl7.fhir.cda#2.0 -ig c:\temp\cda\maps -output c:\temp\bundle.xml -ig hl7.fhir.core

The general pattern is:

 java -jar org.hl7.fhir.validator.jar [cda-file-name] -transform -ig [path-to-CDA-logical-model] -ig [path-to-ccda-maps] -output [dest-name] -ig [current-fhir-version]

R3 / R4 conversions

To use the library to convert from R3 to R4, you need specify the R4/R3 conversion package, which contains everything that is needed:

 java -jar org.hl7.fhir.validator.jar [r3-resource] -transform -ig hl7.fhir.transforms.v4v3 -output [dest-name]

Where XX is the resource name

The reverse is not very different:

 java -jar org.hl7.fhir.validator.jar [r3-resource] -transform -ig hl7.fhir.transforms.v4v3 -output [dest-name]