FHIR

FHIR settings

General

General FHIR settings

Enable FHIR compliant mode

Enforces FHIR compatibility when enabled:

• Adds various attributes and endpoints info to CapabilityStatement

• Sanitises CapabilityStatement (i.e. removes attributes containing null values and empty arrays)

• Adds /fhir to base URL for FHIR search parameters definitions in CapabilityStatement

• Adds BOX_WEB_BASE_URL in Bundle.link.url

• Adds FHIR date search parameter validation on lastUpdated search parameter

• Adds alg: RS256 entry for JWKS

• Changes validation error status to 422 (instead of 400)

• Changes cache-control header to no-store on authorization code auth flow (instead of no-cache, no-store, max-age=0, must-revalidate)

• Removes Bundle.entry if empty

ID	fhir.compliant-mode
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_COMPLIANT_MODE , AIDBOX_FHIR_COMPLIANT_MODE , BOX_COMPLIANT__MODE__ENABLED? , AIDBOX_COMPLIANCE
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Return 404 on deleting non-existent resources

Controls server response when deleting non-existing resources. When enabled, returns 404 (Not Found) status code instead of the default 204 (No Content). Follows FHIR REST implementation where DELETE operations on missing resources can signal resource absence rather than successful deletion.

ID	fhir.return-404-on-empty-delete
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_RETURN_404_ON_EMPTY_DELETE , BOX_FEATURES_HTTP_RETURN__404__ON__EMPTY__DELETE
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Transaction max isolation level

Sets the maximum (inclusive) isolation level for transactions. Can be overridden by the x-max-isolation-level header.

ID	fhir.transaction-max-isolation-level
Type	Enum
Values	none read-committed repeatable-read serializable
Default value	none
Environment variables	BOX_FHIR_TRANSACTION_MAX_ISOLATION_LEVEL , BOX_FEATURES_FHIR_TRANSACTION_MAX__ISOLATION__LEVEL
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	false — setting requires system restart

Validation

Validation settings

Enable FHIR Schema validation mode

Activates the FHIR Schema validation engine which replaces legacy ZEN and Entity/Attribute validation systems. Provides more comprehensive structure validation against the FHIR resource schemas, ensuring stronger conformance to FHIR specifications and more precise error reporting.

ID	fhir.validation.fhir-schema-validation
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_SCHEMA_VALIDATION , AIDBOX_FHIR_SCHEMA_VALIDATION
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	false — setting requires system restart

Enforce strict profile resolution

Requires all referenced profiles to be pre-loaded in Aidbox before validation. When enabled, validation fails if profiles referenced in resources are unknown to the server. Ensures complete validation integrity by preventing partial validation against unknown profiles.

ID	fhir.validation.strict-profile-resolution
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_VALIDATOR_STRICT_PROFILE_RESOLUTION , AIDBOX_VALIDATOR_STRICT_PROFILE_RESOLUTION_ENABLED
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	false — setting requires system restart

Enforce strict FHIR extension resolution

Requires all referenced extensions to be formally defined in profiles loaded to the server.

ID	fhir.validation.strict-extension-resolution
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_VALIDATOR_STRICT_EXTENSION_RESOLUTION , AIDBOX_VALIDATOR_STRICT_EXTENSION_RESOLUTION_ENABLED
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	false — setting requires system restart

Skip FHIR reference validation

Bypasses validation of resource references during FHIR operations. When enabled, allows creating and updating resources containing references to non-existent target resources. Useful for staged data loading or systems with eventual consistency but may compromise referential integrity.

ID	fhir.validation.skip-reference
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_VALIDATION_SKIP_REFERENCE , AIDBOX_FEATURES_VALIDATION_SKIP__REFERENCE , BOX_FEATURES_VALIDATION_SKIP__REFERENCE
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Correct Aidbox format

Transforms polymorphic extensions from FHIR format to Aidbox's internal format. When enabled, extensions like extension.*.valueString are stored as extension.0.value.string instead. Improves query performance and consistency in Aidbox-specific operations while maintaining FHIR compatibility in API responses.

ID	fhir.validation.correct-aidbox-format
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_CORRECT_AIDBOX_FORMAT , AIDBOX_CORRECT_AIDBOX_FORMAT
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

createdAt extension URL

Specifies the URL for the createdAt extension.

ID	fhir.validation.createdat-url
Type	String
Default value	ex:createdAt
Environment variables	BOX_FHIR_CREATEDAT_URL , AIDBOX_CREATED_AT_URL
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	false — setting requires system restart

JSON schema datetime

Enables strict datetime validation in JSON schema validation engine.

ID	fhir.validation.json-schema-datetime-regex
Type	String
Default value	#{}
Environment variables	BOX_FHIR_JSON_SCHEMA_DATETIME_REGEX , BOX_COMPATIBILITY_VALIDATION_JSON__SCHEMA_REGEX
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	false — setting requires system restart

Search

Search settings

Use correct range arithmetic in search

FHIR date search is range based. That is, dates are always converted to datetime ranges and then compared.

Historically, Aidbox uses slightly different range comparison arithmetic. Turn on this setting to use FHIR comparisons.

ID	fhir.search.comparisons
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_SEARCH_COMPARISONS , BOX_SEARCH_FHIR__COMPARISONS
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Enable FHIR-conformant (rev)include behavior

When set to true, the behavior of _include and _revinclude becomes FHIR conformant:

1. Without the :recur or :iterate modifier _(rev)include is only applied to the initial result.

2. With the :recur or :iterate modifier _(rev)include is repeatedly applied to the resources found in the previous step.

ID	fhir.search.include.conformant
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_SEARCH_INCLUDE_CONFORMANT , BOX_SEARCH_INCLUDE_CONFORMANT
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Authorize inline requests

Authorize inline requests (_revinclude and _include) with access policies. Learn more

ID	fhir.search.authorize-inline-requests
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_SEARCH_AUTHORIZE_INLINE_REQUESTS , BOX_SEARCH_AUTHORIZE_INLINE_REQUESTS
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Use semi join in chained searches

Use subselect for simple forward chain searches.

That is only one chain which doesn't contain intermediate hops.

This is a performance optimization which could require building additional indexes.

ID	fhir.search.chain.subselect
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_SEARCH_CHAIN_SUBSELECT , BOX_SEARCH_CHAIN_SUBSELECT
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Enable FHIR composite search parameters

Enable support for FHIR composite search parameters.

ID	fhir.search.composite-parameters
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_SEARCH_COMPOSITE_PARAMETERS , BOX_SEARCH_COMPOSITE__SEARCH
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	false — setting requires system restart

Iteration limit for (rev)include:iterate

Maximum number of iterations for _include and _revinclude with :recur or :iterate modifier.

The default value is 10. If set to 0, queries for _(rev)include will not be performed. If set to a negative value, no limit will be applied.

ID	fhir.search.include.iterate-max
Type	Int
Default value	10
Environment variables	BOX_FHIR_SEARCH_INCLUDE_ITERATE_MAX , BOX_SEARCH_INCLUDE_ITERATE__MAX
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Default search timeout

Default timeout value (seconds). Also uses as timeout for the count query.

ID	fhir.search.default-params.timeout
Type	Int
Default value	60
Environment variables	BOX_FHIR_SEARCH_DEFAULT_PARAMS_TIMEOUT , BOX_SEARCH_DEFAULT__PARAMS_TIMEOUT
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Default number of results per search page

This is the default value of the _count search parameter.

It limits number of results per page

ID	fhir.search.default-params.count
Type	Int
Default value	100
Environment variables	BOX_FHIR_SEARCH_DEFAULT_PARAMS_COUNT , BOX_SEARCH_DEFAULT__PARAMS_COUNT
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Default search result count estimation method

FHIR search response bundle may contain a result count estimation.

ID	fhir.search.default-params.total
Type	Enum
Values	none — omit estimation (fastest) estimate — use approximate value (fast) accurate — use exact value (could be slow)
Default value	accurate
Environment variables	BOX_FHIR_SEARCH_DEFAULT_PARAMS_TOTAL , BOX_SEARCH_DEFAULT__PARAMS_TOTAL
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

SQL operator to use for token search

Aidbox supports two variants of SQL queries to filter when using token search parameters:

ID	fhir.search.token-operator
Type	Enum
Values	@> — One GIN index per resource covers all token searches. Sometimes the Postgres planner can incorrectly estimate the index lookup cost, which leads to slow queries. #>> — Needs an index per #>> expression. If path to the target element contains arrays, @> will be used instead.
Default value	@>
Environment variables	BOX_FHIR_SEARCH_TOKEN_OPERATOR , BOX_SEARCH_TOKEN__OPERATOR
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

JSONB query engine

Aidbox engines for querying JSONB

ID	fhir.search.engine
Type	Enum
Values	knife — Legacy engine. Uses custom Postgres module in Aidboxdb and SQL functions fallback in other Postgres instances. Being phased out. jsonpath — JSONpath language is available starting from PostgreSQL 12.
Default value	knife
Environment variables	BOX_FHIR_SEARCH_ENGINE , BOX_SEARCH_ENGINE
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	false — setting requires system restart

Enable support for multiple languages in search

FHIR uses special extension to provide translations in resources. Enable this setting to turn on the _search-language parameter. This parameter (_search-language) specifies which language to use for search. i.e. which translation in a resource to use.

This feature requires Aidbox to build more complex (so possibly slower) queries. Leave this setting disabled if you don't need to search across translations.

ID	fhir.search.multilingual.enable
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_SEARCH_MULTILINGUAL_ENABLE , BOX_FEATURES_MULTILINGUAL_ENABLE__SEARCH__LANGUAGE
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Use Accept-Language header for search

Use the Accept-Language header to specify search language

See fhir.search.multilingual.enable for details.

ID	fhir.search.multilingual.use-accept-language-header
Type	Bool
Default value	(no default)
Environment variables	BOX_FHIR_SEARCH_MULTILINGUAL_USE_ACCEPT_LANGUAGE_HEADER , BOX_FEATURES_MULTILINGUAL_USE__ACCEPT__LANGUAGE__HEADER
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Use main value if translation is not found

When the _search-language parameter is used, Aidbox uses translation in FHIR extension for search.

If this setting is enabled, Aidbox additionally uses the main value (i.e. not in translation extension)

ID	fhir.search.multilingual.fallback
Type	Bool
Default value	true
Environment variables	BOX_FHIR_SEARCH_MULTILINGUAL_FALLBACK , BOX_FEATURES_MULTILINGUAL_FALLBACK
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Terminology

Terminology settings

FHIR terminology service base URL

Specifies the base URL of the terminology server used for code validation and ValueSet expansion operations. Required for validating coded elements against their ValueSets and CodeSystems. When not configured, code validation is skipped entirely.

ID	fhir.terminology.service-base-url
Type	String
Default value	(no default)
Environment variables	BOX_FHIR_TERMINOLOGY_SERVICE_BASE_URL , AIDBOX_TERMINOLOGY_SERVICE_BASE_URL
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Bulk Data Export

Bulk Data Export settings

Bulk storage provider

Storage provider for bulk export

ID	fhir.bulk-storage.provider
Type	Enum
Values	gcp — Google Cloud Platform aws — Amazon Web Services azure — Microsoft Azure: Cloud Computing Services
Default value	(no default)
Environment variables	BOX_FHIR_BULK_STORAGE_PROVIDER , BOX_BULK__STORAGE_BACKEND
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

GCP service account

GCPServiceAccount resource ID for $export

ID	fhir.bulk-storage.gcp.service-account
Type	String
Default value	(no default)
Environment variables	BOX_FHIR_BULK_STORAGE_GCP_SERVICE_ACCOUNT , BOX_BULK__STORAGE_GCP_SERVICE__ACCOUNT
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

GCP bucket

GCP bucket name for $export

ID	fhir.bulk-storage.gcp.bucket
Type	String
Default value	(no default)
Environment variables	BOX_FHIR_BULK_STORAGE_GCP_BUCKET , BOX_BULK__STORAGE_GCP_BUCKET
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

AWS service account ID

AWS Account resource ID for $export

ID	fhir.bulk-storage.aws.account
Type	String
Default value	(no default)
Environment variables	BOX_FHIR_BULK_STORAGE_AWS_ACCOUNT , BOX_BULK__STORAGE_AWS_ACCOUNT
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

AWS bucket

AWS S3 bucket name for $export

ID	fhir.bulk-storage.aws.bucket
Type	String
Default value	(no default)
Environment variables	BOX_FHIR_BULK_STORAGE_AWS_BUCKET , BOX_BULK__STORAGE_AWS_BUCKET
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime

Azure service account ID

Azure Container resource ID for $export

ID	fhir.bulk-storage.azure.container
Type	String
Default value	(no default)
Environment variables	BOX_FHIR_BULK_STORAGE_AZURE_CONTAINER , BOX_BULK__STORAGE_AZURE_CONTAINER
Sensitive	false — value will be visible in plaintext in Admin UI
Set via	Admin UI → Settings Environment variables
Hot reload	true — setting can be changed at runtime