14.3.1Validation Support Modules

The Instance Validator relies on an implementation of an interface called IValidationSupport to load StructureDefinitions, validate codes, etc.

By default, an implementation of this interface called DefaultProfileValidationSupport is used. This implementation simply uses the built-in official FHIR definitions to validate against (and in many cases, this is good enough).

However, if you have needs beyond simply validating against the core FHIR specification, you may wish to use something more.

14.3.2Built-In Validation Support Classes

There are a several implementations of the IValidationSupport interface built into HAPI FHIR that can be used, typically in a chain.

14.3.3ValidationSupportChain

JavaDoc / Source

This module can be used to combine multiple implementations together so that for every request, each support class instance in the chain is tried in sequence. Note that nearly all methods in the IValidationSupport interface are permitted to return null if they are not able to service a particular method call. So for example, if a call to the validateCode method is made, the validator will try each module in the chain until one of them returns a non-null response.

14.3.4DefaultProfileValidationSupport

JavaDoc / Source

This module supplies the built-in FHIR core structure definitions, including both FHIR resource definitions (StructureDefinition resources) and FHIR built-in vocabulary (ValueSet and CodeSystem resources).

14.3.5InMemoryTerminologyServerValidationSupport

JavaDoc / Source

This module acts as a simple terminology service that can validate codes against ValueSet and CodeSystem resources purely in-memory (i.e. with no database). This is sufficient in many basic cases, although it is not able to validate CodeSystems with external content (i.e CodeSystems where the CodeSystem.content field is external, such as the LOINC and SNOMED CT CodeSystems).

14.3.6PrePopulatedValidationSupport

JavaDoc / Source

This module contains a series of HashMaps that store loaded conformance resources in memory. Typically this is initialized at startup in order to add custom conformance resources into the chain.

14.3.7NpmPackageValidationSupport

JavaDoc / Source

This module can be used to load FHIR NPM Packages and supply the conformance resources within them to the validator. See Validating Using Packages for am example of how to use this module.

14.3.8CachingValidationSupport

JavaDoc / Source

This module caches results of calls to a wrapped service implementation for a period of time. This class can be a significant help in terms of performance if you are loading conformance resources or performing terminology operations from a database or disk, but it also has value even for purely in-memory validation since validating codes against a ValueSet can require the expansion of that ValueSet.

14.3.9SnapshotGeneratingValidationSupport

JavaDoc / Source

This module generates StructureDefinition snapshots as needed. This should be added to your chain if you are working wiith differential StructureDefinitions that do not include the snapshot view.

14.3.10CommonCodeSystemsTerminologyService

JavaDoc / Source

This module validates codes in CodeSystems that are not distributed with the FHIR specification because they are difficult to distribute but are commonly used in FHIR resources.

The following table lists vocabulary that is validated by this module:

14.3.11RemoteTerminologyServiceValidationSupport

JavaDoc / Source

This module validates codes using a remote FHIR-based terminology server.

This module will invoke the following operations on the remote terminology server:

• GET [base]/CodeSystem?url=[url] – Tests whether a given CodeSystem is supported on the server
• GET [base]/ValueSet?url=[url] – Tests whether a given ValueSet is supported on the server
• POST [base]/CodeSystem/$validate-code – Validate codes in fields where no specific ValueSet is bound
• POST [base]/ValueSet/$validate-code – Validate codes in fields where a specific ValueSet is bound

14.3.12UnknownCodeSystemWarningValidationSupport

JavaDoc / Source

This validation support module may be placed at the end of a ValidationSupportChain in order to configure the validator to generate a warning if a resource being validated contains an unknown code system.

Note that this module must also be activated by calling setAllowNonExistentCodeSystem(true) in order to specify that unknown code systems should be allowed.

14.3.13Recipes

The IValidationSupport instance passed to the FhirInstanceValidator will often resemble the chain shown in the diagram below. In this diagram:

• DefaultProfileValidationSupport is used to supply basic built-in FHIR definitions
• PrePopulatedValidationSupport is used to supply other custom definitions
• InMemoryTerminologyServerValidationSupport is used to validate terminology
• The modules above are all added to a chain via ValidationSupportChain
• Finally, a cache is placed in front of the entire chain in order to improve performance

(expand)

14.3.14Recipe: Supplying Custom Definitions

The following snippet shows how to supply custom definitions to the validator.

FhirContext ctx = FhirContext.forR4();

// Create a chain that will hold our modules
ValidationSupportChain supportChain = new ValidationSupportChain();

// DefaultProfileValidationSupport supplies base FHIR definitions. This is generally required
// even if you are using custom profiles, since those profiles will derive from the base
// definitions.
DefaultProfileValidationSupport defaultSupport = new DefaultProfileValidationSupport(ctx);
supportChain.addValidationSupport(defaultSupport);

// This module supplies several code systems that are commonly used in validation
supportChain.addValidationSupport(new CommonCodeSystemsTerminologyService(ctx));

// This module implements terminology services for in-memory code validation
supportChain.addValidationSupport(new InMemoryTerminologyServerValidationSupport(ctx));

// Create a PrePopulatedValidationSupport which can be used to load custom definitions.
// In this example we're loading two things, but in a real scenario we might
// load many StructureDefinitions, ValueSets, CodeSystems, etc.
PrePopulatedValidationSupport prePopulatedSupport = new PrePopulatedValidationSupport(ctx);
prePopulatedSupport.addStructureDefinition(someStructureDefnition);
prePopulatedSupport.addValueSet(someValueSet);

// Add the custom definitions to the chain
supportChain.addValidationSupport(prePopulatedSupport);

// Wrap the chain in a cache to improve performance
CachingValidationSupport cache = new CachingValidationSupport(supportChain);

// Create a validator using the FhirInstanceValidator module. We can use this
// validator to perform validation
FhirInstanceValidator validatorModule = new FhirInstanceValidator(cache);
FhirValidator validator = ctx.newValidator().registerValidatorModule(validatorModule);
ValidationResult result = validator.validateWithResult(input);

14.3.15Recipe: Using a Remote Terminology Server

The following snippet shows how to leverage a remote (FHIR-based) terminology server, by making REST calls to the external service when codes need to be validated.

FhirContext ctx = FhirContext.forR4();

// Create a chain that will hold our modules
ValidationSupportChain supportChain = new ValidationSupportChain();

// DefaultProfileValidationSupport supplies base FHIR definitions. This is generally required
// even if you are using custom profiles, since those profiles will derive from the base
// definitions.
DefaultProfileValidationSupport defaultSupport = new DefaultProfileValidationSupport(ctx);
supportChain.addValidationSupport(defaultSupport);

// Create a module that uses a remote terminology service
RemoteTerminologyServiceValidationSupport remoteTermSvc = new RemoteTerminologyServiceValidationSupport(ctx);
remoteTermSvc.setBaseUrl("http://hapi.fhir.org/baseR4");
supportChain.addValidationSupport(remoteTermSvc);

// Wrap the chain in a cache to improve performance
CachingValidationSupport cache = new CachingValidationSupport(supportChain);

// Create a validator using the FhirInstanceValidator module. We can use this
// validator to perform validation
FhirInstanceValidator validatorModule = new FhirInstanceValidator(cache);
FhirValidator validator = ctx.newValidator().registerValidatorModule(validatorModule);
ValidationResult result = validator.validateWithResult(input);