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	false
Environment variable	BOX_FHIR_COMPLIANT_MODE
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_RETURN_404_ON_EMPTY_DELETE
Deprecated environment variables	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 variable	BOX_FHIR_TRANSACTION_MAX_ISOLATION_LEVEL
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_SCHEMA_VALIDATION
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_VALIDATOR_STRICT_PROFILE_RESOLUTION
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_VALIDATOR_STRICT_EXTENSION_RESOLUTION
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_VALIDATION_SKIP_REFERENCE
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_CORRECT_AIDBOX_FORMAT
Deprecated environment variables	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 variable	BOX_FHIR_CREATEDAT_URL
Deprecated environment variables	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 variable	BOX_FHIR_JSON_SCHEMA_DATETIME_REGEX
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_SEARCH_COMPARISONS
Deprecated environment variables	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

Due to historical reasons Aidbox treats the _include and _revinclude parameters slightly differently from the behavior described in the specification (without FHIR-conformant mode on). The _(rev)include search parameter without the :iterate or :recurse modifier should only be applied to the initial ("matched") result. However, in Aidbox mode, it is also applied to the previous _(rev)include. The _(rev)include parameter with the :iterate(:recurse) modifier should be repeatedly applied to the result with included resources. However, in Aidbox mode, it only resolves cyclic references. In Aidbox mode, it is possible to search without specifying source type: GET /Patient?_include=general-practitioner, but in the FHIR-conformant mode it is not possible.

ID	fhir.search.include.conformant
Type	Bool
Default value	false
Environment variable	BOX_FHIR_SEARCH_INCLUDE_CONFORMANT
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_SEARCH_AUTHORIZE_INLINE_REQUESTS
Deprecated environment variables	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

When the search query does not use _has search parameters, use subselect instead of INNER JOIN for forward chain searches. This is a performance optimization which could require building additional indexes.

ID	fhir.search.chain.subselect
Type	Bool
Default value	false
Environment variable	BOX_FHIR_SEARCH_CHAIN_SUBSELECT
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_SEARCH_COMPOSITE_PARAMETERS
Deprecated environment variables	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 variable	BOX_FHIR_SEARCH_INCLUDE_ITERATE_MAX
Deprecated environment variables	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 variable	BOX_FHIR_SEARCH_DEFAULT_PARAMS_TIMEOUT
Deprecated environment variables	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 variable	BOX_FHIR_SEARCH_DEFAULT_PARAMS_COUNT
Deprecated environment variables	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 variable	BOX_FHIR_SEARCH_DEFAULT_PARAMS_TOTAL
Deprecated environment variables	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

Token and Reference search parameters use exact match.

Aidbox uses Postgres @> operator for this type of searches. The @> operator is the containment operator. It checks that FHIR resource contains some subresource.

The main advantage of the @> operator is that the single GIN index covers all token and reference searches. However sometimes Postgres planner can not build effecient query plan.

Alternatively in some cases it is possible to extract value directly using #>> operator. This operator extracts value from the given path. There is a limitation: path must not contain any arrays. Engines options:

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 variable	BOX_FHIR_SEARCH_TOKEN_OPERATOR
Deprecated environment variables	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 has two engines to search: jsonpath and jsonknife.

The engine is responsible for SQL generation for search operations. SQL by jsonpath and jsonknife is different for search parameter types: date, number, quantity, reference, string, token, uri. _lastUpdated, _createdAt senarch parameters and :missing modifier searches also differ by engine. jsonpath-engine:

jsonknife: *using indexes makes performance approximately the same

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. Has better performance for dates, number and quantity search parameters. Using indexes makes performance approximately the same jsonpath — <ul><li>JSONpath language is available starting from PostgreSQL 12.</li><li>supported by PostgreSQL without external extensions, can be used with managed PostgreSQL, e.g. Azure PostgreSQL</li><li>better performance for string search parameters and all string-related search (e.g. :text modifier)*</li><li>will be supported as main engine</li></ul>
Default value	knife
Environment variable	BOX_FHIR_SEARCH_ENGINE
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_SEARCH_MULTILINGUAL_ENABLE
Deprecated environment variables	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	false
Environment variable	BOX_FHIR_SEARCH_MULTILINGUAL_USE_ACCEPT_LANGUAGE_HEADER
Deprecated environment variables	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 variable	BOX_FHIR_SEARCH_MULTILINGUAL_FALLBACK
Deprecated environment variables	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 variable	BOX_FHIR_TERMINOLOGY_SERVICE_BASE_URL
Deprecated environment variables	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

Terminology Engine

Controls how Aidbox handles terminology APIs

ID	fhir.terminology.engine
Type	Enum
Values	legacy local hybrid
Default value	legacy
Environment variable	FHIR_TERMINOLOGY_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

External Terminology Server

Specifies the base URL of an external terminology server to be used in 'hybrid' terminology engine mode. This setting is ignored for other modes.

ID	fhir.terminology.engine.hybrid.external-tx-server
Type	String
Default value	(no default)
Environment variable	FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER
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

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 variable	BOX_FHIR_BULK_STORAGE_PROVIDER
Deprecated environment variables	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 variable	BOX_FHIR_BULK_STORAGE_GCP_SERVICE_ACCOUNT
Deprecated environment variables	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 variable	BOX_FHIR_BULK_STORAGE_GCP_BUCKET
Deprecated environment variables	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 variable	BOX_FHIR_BULK_STORAGE_AWS_ACCOUNT
Deprecated environment variables	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 variable	BOX_FHIR_BULK_STORAGE_AWS_BUCKET
Deprecated environment variables	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 variable	BOX_FHIR_BULK_STORAGE_AZURE_CONTAINER
Deprecated environment variables	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