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

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.

Transaction max isolation level

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

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.

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.

Enforce strict FHIR extension resolution

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

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.

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.

createdAt extension URL

Specifies the URL for the createdAt extension.

JSON schema datetime

Enables strict datetime validation in JSON schema validation engine.

Legacy FCE package

The name and version of the package from which Aidbox first-class extensions are generated Format: package-name#package-version

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.

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.

Authorize inline requests

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

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.

Enable FHIR composite search parameters

Enable support for FHIR composite search parameters.

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.

Default search timeout

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

Default number of results per search page

This is the default value of the _count search parameter.

It limits number of results per page

Default search result count estimation method

FHIR search response bundle may contain a result count estimation.

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:

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

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.

Use Accept-Language header for search

Use the Accept-Language header to specify search language

See fhir.search.multilingual.enable for details.

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)

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.

Terminology Engine

Controls how Aidbox handles terminology APIs

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.

Bulk Data Export

Bulk Data Export settings

Bulk storage provider

Storage provider for bulk export

GCP service account

GCPServiceAccount resource ID for $export

GCP bucket

GCP bucket name for $export

AWS service account ID

AWS Account resource ID for $export

AWS bucket

AWS S3 bucket name for $export

Azure service account ID

Azure Container resource ID for $export