πŸŽ“
Profiling with zen-lang
This feature is in beta. Introduced in August 2021 - v:2108 release.
We're switching to zen/schema as the main engine for the validation and configuration of Aidbox. Previously Aidbox provided validation with JSON Schema and Basic FHIR Profiles.
In this tutorial you will enable the US Core Patient Profile, extend and validate data against this profile.

Before start

Install the Devbox sample repo following this guide​
Make sure that you have the latest devbox:edge image
1
docker pull healthsamurai/devbox:edge
Copied!
Make sure your Devbox is configured to use devbox:edge image.
In the .env file find the line starting with AIDBOX_IMAGE and edit it to be like this if it is not:
.env
1
AIDBOX_IMAGE=healthsamurai/devbox:edge
Copied!

Create a zen project

Inside of the cloned Devbox directory create a zen project directory and open it. In this example zen project directory is my-zen-project/
1
mkdir my-zen-project
2
cd my-zen-project
Copied!
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
1
npm init -y
2
npm install @zen-lang/hl7-fhir-r4-core @zen-lang/hl7-fhir-us-core
Copied!
Create zen entry namespace.
my-zen-project/my-zen-devbox.edn
1
{ns my-zen-devbox}
Copied!
Create namespace with your profiles
my-zen-project/my-zen-profiles.edn
1
{ns my-zen-devbox
2
import #{hl7-fhir-us-core.us-core-patient}
3
​
4
MyPatientProfile
5
{:zen/tags #{zen/schema zenbox/profile-schema}
6
:confirms #{hl7-fhir-us-core.us-core-patient/schema}
7
:zenbox/type "Patient"
8
:zenbox/profileUri "urn:profile:MyPatientProfile"
9
:type zen/map
10
:require #{:birthDate}}}
Copied!
Import the profiles namespace in the entry namespace
my-zen-project/my-zen-devbox.edn
1
{ns my-zen-devbox
2
import #{my-zen-profiles}}
Copied!

Setup Devbox to use Zen project

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

Start Devbox and check if your profile is loaded

Start Devbox using this guide (perform steps from Devbox directory, not in zen project dir)
Open Devbox 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

Start validation

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

Example project

​The example project from this page
Last modified 22d ago