For AI agents: the documentation index is at /docs/aidbox/llms.txt. A Markdown version of this page is available at /docs/aidbox/notebooks.md or by requesting it with the Accept: text/markdown header.
Aidbox Docs
All notebooks

Aidbox Terminology

Aidbox approach to terminologies

15 cells · updated Aug 29, 2022

Run in Aidbox
This is a read-only view. Responses shown were saved when the notebook was published — open it in your own Aidbox to run the cells against live data.

In Aidbox, all terminology services are built around non-FHIR Concept resource type. Concept resource represents concept element from the CodeSystem resource type. Concept resource behaves like other FHIR resources: you can CRUD & Search it. Concept structure essentially follows the structure of Coding data type with some additional attributes.

ℹ Reasoning behind using concept as a separate resource described in details here.

Aidbox FHIR terminology API docs

Create custom terminology

To create a custom terminology you just need to create CodeSystem, Concept and ValueSet resources. This can be done using regular FHIR CRUD API.

REST Send Cells run only inside Aidbox. Use Run in Aidbox above to open this notebook in your own instance. 
PUT /CodeSystem/custom-eye-color
content-type: text/yaml
accept: text/yaml

status: draft
content: not-present
url: http://example.org/CodeSystem/eyes.color
Response: Body
Status: 201 
url: http://example.org/CodeSystem/eyes.color
status: draft
content: not-present
id: custom-eye-color
resourceType: CodeSystem
meta: {lastUpdated: '2022-08-29T10:12:41.347865Z', createdAt: '2022-08-29T10:12:41.347865Z', versionId: '3'}
REST Send Cells run only inside Aidbox. Use Run in Aidbox above to open this notebook in your own instance. 
PUT /Concept/eyes-color-ec-hl
content-type: text/yaml
accept: text/yaml

system: http://example.org/CodeSystem/eyes.color
code: ec-hl
display: Hazel 
designation:
  display:
    ge: Braun
    ru: Карий
Response: Body
Status: 200 
code: ec-hl
system: http://example.org/CodeSystem/eyes.color
display: Hazel
designation:
  display: {ge: Braun, ru: Карий}
id: eyes-color-ec-hl
resourceType: Concept
meta: {lastUpdated: '2021-11-22T15:55:22.887603Z', createdAt: '2021-11-22T15:50:56.498137Z', versionId: '393'}
REST Send Cells run only inside Aidbox. Use Run in Aidbox above to open this notebook in your own instance. 
PUT /ValueSet/eye-color
content-type: text/yaml
accept: text/yaml


description: Eye color
status: draft
compose:
  include:
  - system: http://example.org/CodeSystem/eyes.color
name: EyeColor
url: http://example.org/ValueSet/eye-color
Response: Body
Status: 200 
url: http://example.org/ValueSet/eye-color
name: EyeColor
status: draft
compose:
  include:
  - {system: 'http://example.org/CodeSystem/eyes.color'}
description: Eye color
id: eye-color
resourceType: ValueSet
meta: {lastUpdated: '2021-11-22T15:55:49.952985Z', createdAt: '2021-11-22T15:55:49.952985Z', versionId: '396'}

Import existing terminology

Import is not much different than create, the only difference is that Concept resourceType doesn't exist in FHIR and this data is contained inside CodeSystem resources. Aidbox automatically extracts CodeSystem.concept into separate Concept resources when CodeSystem is created via FHIR CRUD. There's also terminology/$import endpoint it works like bulk $load

Posting CodeSystem with included concepts via FHIR CRUD API

As a result, you will get set of Concept resources and CodeSystem resource

REST Send Cells run only inside Aidbox. Use Run in Aidbox above to open this notebook in your own instance. 
POST fhir/CodeSystem
content-type: text/yaml
accept: text/yaml

resourceType: CodeSystem
id: custom-eye-color
status: draft
url: http://code.system/eyes.color
content: example
concept:
- code: ec-bn
  display: Brown
- code: ec-be
  display: Blue
- code: ec-gn
  display: Green
- code: ec-hl
  display: Hazel
- code: ec-h
  display: Heterochromia
Response: Body
Status: 201 
url: http://code.system/eyes.color
status: draft
concept:
- {code: ec-bn, display: Brown}
- {code: ec-be, display: Blue}
- {code: ec-gn, display: Green}
- {code: ec-hl, display: Hazel}
- {code: ec-h, display: Heterochromia}
content: example
id: custom-eye-color
resourceType: CodeSystem
meta:
  lastUpdated: '2021-11-23T13:02:56.688627Z'
  versionId: '533'
  extension:
  - {url: 'ex:createdAt', valueInstant: '2021-11-22T15:43:29.705979Z'}

Import eye colors terminology via /terminology/$import endpoint

REST Send Cells run only inside Aidbox. Use Run in Aidbox above to open this notebook in your own instance. 
POST /terminology/$import
content-type: text/yaml
accept: text/yaml

url: https://storage.googleapis.com/aidbox-public/eyecolors.ndjson.gz
Response: Body
Status: 200 
result: {Concept: 5, ValueSet: 1, CodeSystem: 1}

Lookup and validation

Lookup can be done in two ways:

  1. Using regular FHIR Search API on Concept resource
  2. Using FHIR Terminology API $lookup operation

To validate a code FHIR Terminology API operation $validate-code is supported

FHIR Search API on Concept

REST Send Cells run only inside Aidbox. Use Run in Aidbox above to open this notebook in your own instance. 
GET /fhir/Concept?code=ec
accept: text/yaml
Response: Body
Status: 200 
resourceType: Bundle
type: searchset
meta: {versionId: '419'}
total: 1
link:
- {relation: first, url: '/fhir/Concept?code=ec&page=1'}
- {relation: self, url: '/fhir/Concept?code=ec&page=1'}
entry:
- resource:
    code: ec-hl
    system: http://example.org/CodeSystem/eyes.color
    display: Hazel
    designation:
      display: {ge: Braun, ru: Карий}
    id: eyes-color-ec-hl
    resourceType: Concept
    meta: {lastUpdated: '2021-11-22T15:55:22.887603Z', createdAt: '2021-11-22T15:50:56.498137Z', versionId: '393'}
  fullUrl: https://publtest.edge.aidbox.app/Concept/eyes-color-ec-hl
  link:
  - {relation: self, url: 'https://publtest.edge.aidbox.app/Concept/eyes-color-ec-hl'}
REST Send Cells run only inside Aidbox. Use Run in Aidbox above to open this notebook in your own instance. 
GET /CodeSystem/$lookup?system=http://example.org/CodeSystem/eyes.color&code=ec-hl
accept: text/yaml
Response: Body
Status: 200 
resourceType: Parameters
parameter:
- {name: display, valueString: Hazel}
- name: designation
  value:
    display: {ge: Braun, ru: Карий}
- {name: name, value: null}
REST Send Cells run only inside Aidbox. Use Run in Aidbox above to open this notebook in your own instance. 
GET /ValueSet/eye-color/$validate-code?code=ec-hl
accept: text/yaml
Response: Body
Status: 200 
resourceType: Parameters
parameter:
- {name: result, valueBoolean: true}