# Validation and Conformance 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](https://hapifhir.io/hapi-fhir/docs/validation/instance_validator.html), 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](/content/docs/validation_and_conformance/conformance_data.html). For terminology-specific features (CodeSystem, ValueSet, ConceptMap), see [Terminology](/content/docs/terminology/introduction.html). # 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](/content/docs/validation_and_conformance/conformance_data.html) for full details on each resource type. ## StructureDefinition [StructureDefinition](https://hl7.org/fhir/structuredefinition.html) 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](https://hl7.org/fhir/codesystem.html) 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](/content/docs/terminology/uploading.html). - 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](https://hl7.org/fhir/valueset.html) 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](/content/docs/terminology/introduction.html) 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](/content/docs/validation_and_conformance/packages_and_igs.html). - **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](/content/docs/validation_and_conformance/validation_support_repository.html) 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](/content/docs/fhir_repository/updating_data.html#patch/index.html) 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](/content/docs/hybrid_providers/index.html) or the [FHIR Gateway](/content/docs/fhir_gateway/index.html). Validation rules can be configured declaratively or through custom code: - **Declarative rules** are configured in the FHIR Storage module settings. See [**Repository Validation**](/content/docs/validation_and_conformance/repository_validation.html). - **Java-based rules** use a custom interceptor for advanced validation logic. See [Java Validation Rules](/content/docs/validation_and_conformance/repository_validation_java.html). - **JavaScript-based rules** implement validation logic in a JavaScript script. See [JavaScript Validation Rules](/content/docs/validation_and_conformance/repository_validation_javascript.html). - **Custom validation beans** add custom `IValidationSupport` implementations to the validation chain for custom code validation logic. See [Custom Validation Beans](/content/docs/validation_and_conformance/repository_validation_bean.html). ## 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](/content/docs/fhir_repository/fhir_endpoint_module.html) that have been paired with a FHIR Storage module, but also modules such as [Hybrid Providers](/content/docs/hybrid_providers/index.html) and the [FHIR Gateway](/content/docs/fhir_gateway/index.html). Unlike the repository mode, this mode is only able to perform a superficial validation of [Patch Operations](/content/docs/fhir_repository/updating_data.html#patch/index.html). 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**](/content/docs/validation_and_conformance/endpoint_validation.html) 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](https://terminology.hl7.org/)). Note that `POST CodeSystem/$lookup` against a remote terminology server is not currently supported on FHIR R5 endpoints. See [Remote Terminology Services](/content/docs/validation_and_conformance/remote_terminology_services.html) 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](/content/docs/validation_and_conformance/suppressing_messages.html) 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](/content/docs/validation_and_conformance/validation_performance.html) for details. Introduction Validation and Conformance [Introduction](/content/docs/validation_and_conformance/introduction.html) [Validation Support Repository](/content/docs/validation_and_conformance/validation_support_repository.html) [Validation Support Repository Options](/content/docs/validation_and_conformance/validation_support_repository_options.html) [Conformance Data](/content/docs/validation_and_conformance/conformance_data.html) [Repository Validation](/content/docs/validation_and_conformance/repository_validation.html) [Repository Validation: Java](/content/docs/validation_and_conformance/repository_validation_java.html) [Repository Validation: Javascript](/content/docs/validation_and_conformance/repository_validation_javascript.html) [Repository Validation: Custom Validation Beans](/content/docs/validation_and_conformance/repository_validation_bean.html) [Endpoint Validation](/content/docs/validation_and_conformance/endpoint_validation.html) [Packages and Implementation Guides](/content/docs/validation_and_conformance/packages_and_igs.html) [Package Registry Endpoint Module](/content/docs/validation_and_conformance/package_registry_endpoint_module.html) [Remote Terminology Services](/content/docs/validation_and_conformance/remote_terminology_services.html) [Suppressing Messages](/content/docs/validation_and_conformance/suppressing_messages.html) [Validation Performance](/content/docs/validation_and_conformance/validation_performance.html) [Automatic Provenance Injection](/content/docs/validation_and_conformance/automatic_provenance_injection.html) [Validation Support Repository](/content/docs/validation_and_conformance/validation_support_repository.html)