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 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

Last updated

Was this helpful?