Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dhanyasukumaran1/fhir_query_validator/llms.txt

Use this file to discover all available pages before exploring further.

FHIRQueryValidator can be configured at instantiation time to control validation strictness, target a specific FHIR version, and extend the built-in resource registry with custom resource types and search parameters.

​
Default configuration

With no arguments, the validator targets FHIR R4 and runs in strict mode — any unknown parameter name is treated as an error: 
from fhir_query_validator import FHIRQueryValidator

validator = FHIRQueryValidator()
# Equivalent to:
validator = FHIRQueryValidator(fhir_version="R4", strict=True)

​
Constructor parameters

​
fhir_version
string
default:"\"R4\""
The FHIR version to validate against. Currently "R4" is supported. Set this explicitly if you need version-specific validation behavior.
​
strict
bool
default:"True"
When True, unknown search parameters are reported as errors and result.is_valid is False. When False, unknown parameters produce warnings instead, and the query is still considered valid. Use False during development or when working with FHIR server extensions.
​
custom_resources
dict
default:"None"
A dictionary of custom resource type definitions to add to the validator’s registry. Useful when working with FHIR profiles, implementation guides, or proprietary extensions. Keys are resource type names; values are lists of valid search parameter names.
​
custom_parameters
dict
default:"None"
A dictionary of additional search parameters to add to existing resource types. Keys are resource type names; values are lists of additional parameter names to allow.

​
Strict mode vs. non-strict mode

In strict mode (the default), unknown parameters are errors: 
validator = FHIRQueryValidator(strict=True)
result = validator.validate_query("Patient?unknownParam=value")
print(result.is_valid)   # False
print(result.errors)     # ["Unknown search parameter 'unknownParam' for resource 'Patient'"]
print(result.warnings)   # []
In non-strict mode, unknown parameters produce warnings but the query is still considered valid: 
validator = FHIRQueryValidator(strict=False)
result = validator.validate_query("Patient?unknownParam=value")
print(result.is_valid)   # True
print(result.errors)     # []
print(result.warnings)   # ["Unknown search parameter 'unknownParam' for resource 'Patient'"]
Use non-strict mode during development or integration testing against FHIR servers that support custom search parameters. Switch to strict mode in production pipelines.

​
Custom resource types

If you work with FHIR implementation guides that define custom resource types (e.g., US Core profiles or custom extensions), add them via custom_resources: 
validator = FHIRQueryValidator(
    custom_resources={
        "CustomPatientProfile": [
            "identifier",
            "name",
            "birthdate",
            "custom-field",
            "enrollment-date",
        ]
    }
)

result = validator.validate_query("CustomPatientProfile?custom-field=value")
print(result.is_valid)  # True

​
Custom search parameters on existing resources

To add custom search parameters to standard FHIR resources without replacing the built-in definitions, use custom_parameters: 
validator = FHIRQueryValidator(
    custom_parameters={
        "Patient": ["preferred-language", "cohort-id", "study-arm"],
        "Observation": ["device-serial", "study-timepoint"],
    }
)

result = validator.validate_query("Patient?cohort-id=ABC123")
print(result.is_valid)  # True

​
Combining custom resources and parameters

validator = FHIRQueryValidator(
    strict=True,
    custom_resources={
        "ResearchSubject": ["identifier", "study", "status", "period", "individual"],
    },
    custom_parameters={
        "Patient": ["research-id", "trial-arm"],
    }
)

​
Creating multiple validator instances

You can maintain separate validator instances for different contexts — for example, one strict validator for production queries and one permissive validator for exploratory development: 
from fhir_query_validator import FHIRQueryValidator

# Strict validator for production pipeline
prod_validator = FHIRQueryValidator(strict=True)

# Permissive validator for notebook exploration
dev_validator = FHIRQueryValidator(strict=False)
Validator instances are stateless with respect to individual queries — you can safely reuse the same instance across many validate_query() and validate_batch() calls. Creating a new instance resets all custom configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us