Aidbox
Search…
🎓
Extend an IG with a custom zen profile
Enable the US Core Implementation Guide, extend and validate data against this profile.
Please start a discussion or contact us if you have questions, feedback or suggestions.

Install the Aidbox following this guide.
In the .env file find the line starting with AIDBOX_IMAGE and edit it to be like this if it is not:
.env
AIDBOX_IMAGE=healthsamurai/aidboxone:edge

Inside of the cloned Aidbox directory create a zen project directory and open it. In this example zen project directory is my-zen-project/
mkdir my-zen-project
cd my-zen-project
Inside of your zen project directory initialize npm package for your project and then install zen dependencies you need. FHIR R4 and US core v3 are used as dependencies in this example
npm init -y
npm install @zen-lang/hl7-fhir-r4-core @zen-lang/hl7-fhir-us-core
Create zen entry file in my-zen-project directory.
my-zen-aidbox.edn
{ns my-zen-aidbox}
Create namespace with your profiles.
my-zen-profiles.edn
{ns my-zen-profiles
import #{hl7-fhir-us-core.us-core-patient}
MyPatientProfile
{:zen/tags #{zen/schema zen.fhir/profile-schema}
:confirms #{hl7-fhir-us-core.us-core-patient/schema}
:zen.fhir/type "Patient"
:zen.fhir/profileUri "urn:profile:MyPatientProfile"
:type zen/map
:require #{:birthDate}}}
Import the profiles namespace in the entry namespace.
my-zen-aidbox.edn
{ns my-zen-aidbox
import #{my-zen-profiles}}

Go back to Aidbox directory and add configuration variables to the end of .env file:
.env
AIDBOX_ZEN_PROJECT=/my-zen-project # mind the / at the beginning of the dir name
AIDBOX_ZEN_ENTRY=my-zen-aidbox
AIDBOX_ZEN_DEV_MODE=enable # set this variable if you want to have
# zen reload namespaces on the fly as they change
To enable your Aidbox reading the zen project data add zen project directory volume mount. In the docker-compose.yaml file find the section aidbox: and add the following line under the volumes: section:
- "./my-zen-project:/my-zen-project"
The volumes section should be like this
services:
aidbox:
volumes:
- "./my-zen-project:/my-zen-project"
So the file should look like this:
docker-compose.yaml
version: '3.7'
services:
aidbox-db:
<...omitted...>
aidbox:
container_name: "aidbox"
image: "${AIDBOX_IMAGE}"
<...omitted...>
volumes:
- "./my-zen-project:/my-zen-project"
<...omitted...>

Start Aidbox.
docker compose up
Open Aidbox in your browser and click Profiles tab in the left menu:
You should see the list of zen namespaces loaded.
On this page you see the namespaces that are explicitly included in the zen project or used by Aidbox
Open your profile by clicking its name

Test the data against this profile using validate tab
If your profile is tagged zen.fhir/profile-schema it can be used to validate your data On FHIR CRUD API requests a profile will be applied if data includes :zen.fhir/profileUri in the meta.profile attribute:
Request
Response
Data is missing `birthDate` attribute, required by the profile
POST /Patient
Content-Type: text/yaml
name: [{given: [Harry], family: Potter}]
meta: {profile: ["urn:profile:MyPatientProfile"]}
An error has been returned
# status 422
resourceType: OperationOutcome
text:
status: generated
div: Invalid resource
issue:
- severity: fatal
code: invalid
expression:
- Patient.birthDate
diagnostics: ':birthDate is required'
Request
Response
Data contains `birthDate` required by profile
POST /Patient
Content-Type: text/yaml
name: [{given: [Harry], family: Potter}]
birthDate: "1980-07-31"
meta: {profile: ["urn:profile:MyPatientProfile"]}
# status 201
id: 20fdde9d-ede6-4edb-a16a-278ddfeef952
resourceType: Patient
name:
- given:
- Harry
family: Potter
birthDate: '1980-07-31'
meta:
profile:
- urn:profile:MyPatientProfile
lastUpdated: '2021-09-03T14:40:11.300957Z'
createdAt: '2021-09-03T14:40:11.300957Z'
versionId: '57'

The example project from this page
Copy link
Edit on GitHub
On this page
Before you start
Create a zen project
Setup Aidbox to use Zen project
Check if your profile is loaded
Start validation
Example project