FHIR validation ensures that clinical data conforms to the rules defined by the FHIR specification and any applicable Implementation Guides. Smile CDR uses the official HAPI FHIR Instance Validator, which is considered the reference validator for the FHIR standard, and supports profile-driven validation against StructureDefinitions, ValueSet membership testing, and terminology code validation.

For background on what FHIR conformance resources are and how they are structured, see Conformance Data. For terminology-specific features (CodeSystem, ValueSet, ConceptMap), see Terminology.

Conformance Resources

Validation rules in Smile CDR are expressed through FHIR conformance resources. The FHIR specification defines a set of resource types that together describe the structure, terminology, and constraints that clinical data must satisfy. See Conformance Data for full details on each resource type.

StructureDefinition

StructureDefinition resources are the primary data models used for validation. They define the structure of a FHIR resource or data type, declaring which elements are mandatory, forbidden, or repeatable; what data types are allowed; which extensions may be used; and what ValueSet bindings apply to coded fields. A StructureDefinition that constrains a base FHIR resource type is called a Profile.

CodeSystem

CodeSystem resources define collections of codes and their meanings. Smile CDR supports three content modes:

In Complete mode (CodeSystem.content = complete), all codes are defined inline in the resource. Validation fails if a code is not present.
In Not-Present / External mode (CodeSystem.content = not-present), codes are loaded into dedicated database tables rather than stored inline. This is used for large or copyright-restricted vocabularies such as LOINC or SNOMED CT. See Uploading CodeSystems.
In Fragment mode (CodeSystem.content = fragment), the resource contains a known subset of codes. Unknown codes produce a warning rather than a validation failure.

ValueSet

ValueSet resources select a subset of codes from one or more CodeSystems for use in a specific context. StructureDefinitions declare ValueSet bindings on coded fields, meaning codes in those fields must be drawn from the bound ValueSet. Smile CDR pre-calculates ValueSet expansions in the background for efficient validation. See Terminology for more on ValueSet expansion and terminology operations.

Loading Conformance Resources

Conformance resources are loaded into Smile CDR from several sources:

Built-in FHIR specification resources such as StructureDefinitions, CodeSystems, ValueSets, and OperationDefinitions are bundled with Smile CDR and can be seeded into the repository at startup.
Implementation Guides (IGs) are distributed as NPM packages and extend the base specification with profiles, extensions, and terminology for specific clinical use cases. See NPM Packages and Implementation Guides.
Custom conformance resources such as organization-specific StructureDefinitions, CodeSystems, and ValueSets can be uploaded via the FHIR REST API.

Validation Support Repository

When multiple FHIR Storage modules share the same conformance resources, a dedicated Validation Support Repository module can centralize the conformance data so that it is loaded once and shared across modules. See Validation Support Repository for details.

Validation Modes

There are two validation modes that can be used to provide data validation in Smile CDR: Endpoint Validation, and Repository Validation. These two modes each have their advantages and tradeoffs.

Both validation modes use the official FHIR "Instance Validator", which is considered the reference validator for the FHIR standard.

Repository Validation

Repository Validation places a validator directly in the FHIR Storage module, where it can be applied to every write operation that passes through the system. This mode has several key advantages:

It applies to all sources of data equally. This means that regardless of whether data is being written due to a FHIR REST transaction, and ETL Import job, an HL7 v2.x Listener, etc. you can be sure that the data will be subjected to whatever validation rules you have configured.
Because the validator is deeply integrated with the storage engine in this mode, incremental operations such as the Patch Operation can be validated as well. In the case of a patch the target resource will be validated as though the patch had been applied, but before the storage operation actually occurs, giving the validator a chance to block the operation.

This validation mode applies only to Smile CDR FHIR Repositories, meaning systems where a FHIR Storage module is being used to actually store the FHIR data. It cannot be used with other types of FHIR servers, such as Hybrid Providers or the FHIR Gateway.

Validation rules can be configured declaratively or through custom code:

Declarative rules are configured in the FHIR Storage module settings. See Repository Validation.
Java-based rules use a custom interceptor for advanced validation logic. See Java Validation Rules.
JavaScript-based rules implement validation logic in a JavaScript script. See JavaScript Validation Rules.
Custom validation beans add custom IValidationSupport implementations to the validation chain for custom code validation logic. See Custom Validation Beans.

Endpoint Validation

Endpoint validation mode involves a validator that is placed inside the HTTP Server module, validating requests as they enter the system. This mode can be used on any FHIR HTTP server module, including FHIR Endpoints that have been paired with a FHIR Storage module, but also modules such as Hybrid Providers and the FHIR Gateway.

Unlike the repository mode, this mode is only able to perform a superficial validation of Patch Operations. It can validate that the patch itself is valid, but can not provide guarantees that the target resource will be valid after the patch is applied.

See Endpoint Validation for more information on this feature.

Remote Terminology Services

By default, terminology validation (code membership, ValueSet expansion) uses the terminology resources loaded into the local FHIR repository. Smile CDR can also delegate these operations to an external terminology server, which is useful when a central organizational terminology authority exists or when using a large vocabulary that is impractical to load locally (e.g. the HL7 Terminology Server). Note that POST CodeSystem/$lookup against a remote terminology server is not currently supported on FHIR R5 endpoints. See Remote Terminology Services for details.

Suppressing Validation Messages

Validation sometimes produces messages for known or acceptable issues, such as warnings about codes in a vocabulary that is not locally loaded. Smile CDR allows specific validation messages to be suppressed or downgraded in severity without disabling validation entirely. See Suppressing Validation Messages for details.

Validation Performance

Validation can be a CPU-intensive operation on high-throughput systems. Smile CDR provides several configuration options for tuning validation performance, including concurrent bundle validation and skipping contained resource validation. See Validation Performance for details.

Validation Support Repository