4.1 HL7 FHIR Tooling
There is a great deal of tooling available to support FHIR implementation, including open source implementations, reference implementations, test servers, schemas, automated test tools, etc. For a relatively complete list of what's available, consult the following:
NOTE: Because the specifications are currently based on an interim and un-supported release of the FHIR specification, be aware that not all tools will function with the specific version of FHIR used in this specification.
4.2 Schemas
The HL7 May 2016 FHIR specification includes two separate zip files containing a mixture of schemas and schematrons for use in validating FHIR instances for that version of the specification. All FHIR XML instances must be valid against those schemas and schematron validation processes, though there's no need to make use of those specific validation files in any production system. The first is a set of fully documented schemas with embedded schema annotations with human-readable documentation. The second is intended for Code generation, though that's not necessarily the best way to approach FHIR implementation.
FHIR has a principle of "one schema for all FHIR instances". Because of this, and because of how the FHIR XML syntax is designed (XML Representation of Resources can be found here), there are no PrescribeIT®-specific schemas. However, for convenience, a minimalist set of schemas that can be used to validate instances as part of testing is provided here as part of this implementation guide. As well, the FHIR validator has the capability of performing schema validation as part of its validation process.
4.3 FHIR Validator
Schemas are limited in their ability to completely validate FHIR instances. Schemas cannot perform full vocabulary validation and have no ability to validate FHIR content against profiles. The FHIR validator addresses this limitation by providing complete validation of FHIR instances, including terminology, invariants and profiles. The following table provides links to the validator and the files needed to run it:
NOTE: The links below will only work if the respective implementation guides are unzipped in parallel directories. Links for artifacts associated with implementation guides not used/available will not resolve. I.e. your directory structure should look like this:
[some shared folder]/common [some shared folder]/erx [some shared folder]/tools
with the content from each implementation guide unzipped from its respective source and placed in the appropriate folder.
| Artifact | Description |
|---|---|
| Validator jar | The most recent version of the HL7 validator tool tested for use with Shared Health artifacts. This is used to run the validation process from the commandline or from within other code |
| Validator source files | The java files used to produce the most recent version of the HL7 validator tool. These are relevant only if an implementer wishes to customize the HL7 validator for use in their own environment (for example, to enhance or tune it for performance reasons). |
| IG Pack | This file contains information to validate any artifacts built against the May 2016 version of the FHIR specification. It is needed to validate Shared Health artifacts from any implementation guide. |
| Validator Packages: | These files contain profiles, value sets and other artifacts specific to Shared Health implementation guides. The Shared Health pack (package-common.pack file) is required for all implementation guides. To validate artifacts against more specific implementation guides, the IG-specific pack will also be required. |
| This must be downloaded. It defines all of the value sets used for Shared Health and PrescribeIT®. The complete file name with version suffix must be used (e.g. infowayvocab-5.0.13.pack) | |
| This must be downloaded. It supports Shared Health such as polling as well as common profiles and value sets that are shared across all domains. | |
| This supports validating artifacts against the PrescribeIT® implementation guide. NOTE: You must also use the Shared Health pack. |
NOTE: The validator provided with PrescribeIT® v5.0 will not work with prior PrescribeIT® versions or other applications. A future version of the validator will likely again support validating all applications communicating with the Shared Health Hub.
The instructions for invoking the validator are as follows:
Usage: java -jar [validator].jar (parameters)
The following parameters are supported:
[source]: a file, url, directory or pattern for resources to validate. At
least one source must be declared. If there is more than one source or if
the source is other than a single file or url and the output parameter is
used, results will be provided as a Bundle.
Patterns are limited to a directory followed by a filename with an embedded
asterisk. E.g. foo*-examples.xml or someresource.*, etc.
-version [ver]: The FHIR version to use. This can only appear once.
valid values 1.0 | 1.4 | 3.0 | 4.5 or 1.0.2 | 1.4.0 | 3.0.2 | 4.0.1 | 4.5.0
Default value is 4.5
-ig [package|file|folder|url]: an IG or profile definition to load. Can be
the URL of an implementation guide or a package ([id]-[ver]) for
a built implementation guide or a local folder that contains a
set of conformance resources.
No default value. This parameter can appear any number of times
-tx [url]: the [base] url of a FHIR terminology service
Default value is http://tx.fhir.org. This parameter can appear once
To run without terminology value, specific n/a as the URL
NOTE: The PrescribeIT version of FHIR validator does NOT support external terminology services.
As such, the -tx option is only allowed with n/a as argument: -tx n/a
-txLog [file]: Produce a log of the terminology server operations in [file]
Default value is not to produce a log
-profile [url]: the canonical URL to validate against (same as if it was
specified in Resource.meta.profile). If no profile is specified, the
resource is validated against the base specification. This parameter
can appear any number of times.
NOTE: the profile (and it's dependencies) have to be made available
through one of the -ig parameters. Note that package dependencies will
automatically be resolved
-questionnaire mode: what to do with when validating QuestionnaireResponse resources
none (default): just ignore the questionnaire reference
required: check that the QuestionnaireResponse has a questionnaire and validate against it
check: if the QuestionnaireResponse has a questionnaire, validate against it
The questionnaire must be loaded using the -ig parameter
the location of a questionnaire. If provided, then the validator will validate
any QuestionnaireResponse that claims to match the Questionnaire against it
no default value. This parameter can appear any number of times
-output [file]: a filename for the results (OperationOutcome)
Default: results are sent to the std out.
-debug
Produce additional information about the loading/validation process
-recurse
Look in subfolders when -ig refers to a folder
-locale
Specifies the locale/language of the validation result messages (eg.: de-DE
-sct
Specify the edition of SNOMED CT to use. Valid Choices:
intl | us | uk | au | nl | ca | se | dk | es
tx.fhir.org only supports a subset. To add to this list or tx.fhir.org
ask on https://chat.fhir.org/#narrow/stream/179202-terminology
-native: use schema for validation as well
* XML: w3c schema+schematron
* JSON: json.schema
* RDF: SHEX
Default: false
-language: [lang]
The language to use when validating coding displays - same value as for xml:lang
Not used if the resource specifies language
Default: no specified language
-strictExtensions: If present, treat extensions not defined within the specified FHIR version and any
referenced implementation guides or profiles as errors. (Default is to only raise information messages.)
-hintAboutNonMustSupport: If present, raise hints if the instance contains data elements that are not
marked as mustSupport=true. Useful to identify elements included that may be ignored by recipients
-assumeValidRestReferences: If present, assume that URLs that reference resources follow the RESTful URI pattern
and it is safe to infer the type from the URL
-security-checks: If present, check that string content doesn't include any html-like tags that might create
problems downstream (though all external input must always be santized by escaping for either html or sql)
The validator also supports the param -proxy=[address]:[port] for if you use a proxy
Parameters can appear in any order
Alternatively, you can use the validator to execute a transformation as described by a structure map.
To do this, you must provide some additional parameters:
-transform [map]
* [map] the URI of the map that the transform starts with
Any other dependency maps have to be loaded through an -ig reference
-transform uses the parameters -defn, -txserver, -ig (at least one with the map files), and -output
Alternatively, you can use the validator to generate narrative for a resource.
To do this, you must provide a specific parameter:
-narrative
-narrative requires the parameters -defn, -txserver, -source, and -output. ig and profile may be used
Alternatively, you can use the validator to convert a resource or logical model.
To do this, you must provide a specific parameter:
-convert
-convert requires the parameters -source and -output. ig may be used to provide a logical model
Alternatively, you can use the validator to evaluate a FHIRPath expression on a resource or logical model.
To do this, you must provide a specific parameter:
-fhirpath [FHIRPath]
* [FHIRPath] the FHIRPath expression to evaluate
-fhirpath requires the parameters -source. ig may be used to provide a logical model
Finally, you can use the validator to generate a snapshot for a profile.
To do this, you must provide a specific parameter:
-snapshot
-snapshot requires the parameters -defn, -txserver, -source, and -output. ig may be used to provide necessary base profiles
Examples – (NOTE: These example presume that all validator files and example messages are in a single directory)
java -jar org.hl7.fhir.validator.jar -version 1.4.0 -ig infowayvocab.pack -ig package-common.pack -ig package-erx.pack -tx n/a Bundle-example-a1-101-e110.xml -output Bundle-example-a1-101-e110.txt
java -jar org.hl7.fhir.validator.jar -version 1.4.0 -ig infowayvocab.pack -ig package-common.pack -ig package-erx.pack -tx n/a Bundle-example-*.xml -output Bundle-examples.txt