Custom Resources using Entity
Entity & Attributes and Zen Schema are planned to be retired and will be replaced by FHIR Schema. Here’s a migration guide to help you transition your custom resources defined via Entity & Attributes / Zen Schema.
Defining a Custom Resource
Sometimes your data does not fit any existing FHIR resources. It is not always obvious that your data cannot be translated to FHIR because of some FHIR generalizations. The right first step is to go to FHIR comunity chat and ask your specific question about mapping to FHIR, or contact Health Samurai modeling team about your concern. If you are still sure that there is no appropriate resource in FHIR or it takes too much time to wait for it, you can define your own Custom Resources in Aidbox.
Custom Resources are defined exactly the same way as core FHIR resources. They can refer to existing resources, have uniform REST API for CRUD and Search, and participate in transactions.
Let's imagine that in our application we want to store user preferences such as UI configuration or personalized Patient List filters. It is expected that you have already created a box in Aidbox.Cloud. First of all, we have to define a new resource type by creating an Entity resource.
Create Definition
Access the REST console and paste the following request. You should see the response:
This means that the resource of the type Entity
was successfully created. When you create Entity
resources with type resource
, Aidbox will on the fly initialize a storage for new resource type and generate CRUD & Search REST API.
When you set the isOpen: true
flag, this means that the resource does not have any specific structure and that you can store arbitrary data. This is useful when you do not know the exact resource structure, for example, while working on a prototype. Later we will make its schema more strict and will constraint it with additional validations.
API of a Custom Resource
Let's check API for our custom resource UserSetting
. You can list UserSetting
resources by the standard FHIR URI template GET /{resourceType}
:
In the query-sql
we see what query is executed by Aidbox to get these resources and can see that the table usersetting
was created. You can test it with the DB Console using the following query:
Cool! Now, let's create first UserSetting
resource using the REST Console:
Try to get all user settings now:
Or execute the SQL query in the Aidbox.Cloud DB Console:
CRUD Operations with a Custom Resource
Also you can read, update, and delete UserSetting
resource with:
Refining the Structure of a Custom Resource
Awesome! We've got a nice API by providing a couple of lines of metadata. But the schema of our custom resource is currently too open and users can put any data into UserSetting
resource. For example, we can do this:
Describe Structure of Custom Resource
Now, let's put some restrictions and define our Custom Resource structure. To describe structure of a resource, we will use Attribute meta-resource. For example, we want to restrict the theme
attribute to be a string
value from the specific enumeration:
Validation of Incoming Resources
To validate incoming resources, Aidbox uses json-schema which is generated from Entity & Attribute meta-resources. Using $json-schema operation we can inspect which schema will be applied to UserSetting
resources:
As we see on the line 17 in the response above, the theme
property has now type string
and is restricted by the enumeration [dark, white]
.
Let's try to create an invalid resource now:
Restriction of Extra Attributes
We constrained only one attribute and because our Entity.isOpen = true
, this resource can have any additional attributes without a schema. We can turn this off by setting Entity.isOpen
to false
:
Now, let's inspect the schema:
And we see the schema keyword additionalProperties: false
(line 20 in the response above) which means that now our schema is closed. Let's test it by the request with additional property menu
:
In this tutorial you learned how to define and use Custom Resources in Aidbox. In future series we will show you how to add more advanced validations on Custom Resources and create custom endpoints to define your business logic. If you have any questions or suggestions, please provide us with your feedback!
Last updated