Local Terminlogy

Objectives

Create a local CodeSystem and ValueSet for use in the resource validation.
Explore how canonical resources with different versions exist in the same FHIR Server

Before you begin

Set up the local Aidbox instance using the Getting Started guide. It will make sure that the Aidbox version is greater than or equal to 2507

Add the following environment variables to the docker-compose.yaml file for the aidbox.environment section:

aidbox:
    ...
    environment:
      ....
      FHIR_TERMINOLOGY_ENGINE: hybrid
      FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: https://tx.health-samurai.io/fhir

You can read about those settings here.

Creating and Uploading a FHIR package

Let's create the FHIR Package that contains:

CodeSystem with three codes
ValueSet that includes all the content from the CodeSystem
Profile for the ServideRequest resource that binds the ServiceRequest.code element to the ValueSet and makes this binding required.

Create a folder structure for the FHIR package with the following command mkdir -p mypackage/input/resources

Create the JSON file with the CodeSystem FHIR resource: mypackage/input/resources/CodeSystem-tutorial-service-codes.jsonwith the following content:

{
  "resourceType": "CodeSystem",
  "id": "tutorial-service-codes",
  "url": "http://example.com/fhir/CodeSystem/tutorial-service-codes",
  "version": "1.0.0",
  "name": "TutorialServiceCodes",
  "title": "Tutorial Service Codes",
  "status": "active",
  "experimental": false,
  "date": "2024-01-01",
  "publisher": "Tutorial Example",
  "description": "A sample code system for tutorial purposes containing service request codes",
  "caseSensitive": true,
  "content": "complete",
  "count": 3,
  "concept": [
    {
      "code": "consultation",
      "display": "Medical Consultation",
      "definition": "A general medical consultation service"
    },
    {
      "code": "lab-test",
      "display": "Laboratory Test",
      "definition": "Laboratory testing service"
    },
    {
      "code": "imaging",
      "display": "Medical Imaging",
      "definition": "Medical imaging service including X-ray, MRI, CT scan"
    }
  ]
}

Create the JSON file with the ValueSet FHIR resource: mypackage/input/resources/ValueSet-tutorial-service-codes.jsonwith the following content:

{
  "resourceType": "ValueSet",
  "id": "tutorial-service-codes",
  "url": "http://example.com/fhir/ValueSet/tutorial-service-codes",
  "version": "1.0.0",
  "name": "TutorialServiceCodes",
  "title": "Tutorial Service Codes ValueSet",
  "status": "active",
  "experimental": false,
  "date": "2024-01-01",
  "publisher": "Tutorial Example",
  "description": "ValueSet containing codes for service request types in tutorial examples",
  "compose": {
    "include": [
      {
        "system": "http://example.com/fhir/CodeSystem/tutorial-service-codes"
      }
    ]
  }
}

Create the JSON file with the FHIR profile: mypackage/input/resources/StructureDefinition-tutorial-service-request.json with the following content:

{
  "resourceType": "StructureDefinition",
  "id": "tutorial-service-request",
  "url": "http://example.com/fhir/StructureDefinition/tutorial-service-request",
  "version": "1.0.0",
  "name": "TutorialServiceRequest",
  "title": "Tutorial Service Request Profile",
  "status": "active",
  "experimental": false,
  "date": "2024-01-01",
  "publisher": "Tutorial Example",
  "description": "A ServiceRequest profile for tutorial purposes with required binding to tutorial service codes",
  "fhirVersion": "4.0.1",
  "kind": "resource",
  "abstract": false,
  "type": "ServiceRequest",
  "baseDefinition": "http://hl7.org/fhir/StructureDefinition/ServiceRequest",
  "derivation": "constraint",
  "differential": {
    "element": [
      {
        "id": "ServiceRequest",
        "path": "ServiceRequest",
        "short": "Tutorial Service Request",
        "definition": "A service request with required binding to tutorial service codes"
      },
      {
        "id": "ServiceRequest.code",
        "path": "ServiceRequest.code",
        "short": "Service code from tutorial ValueSet",
        "definition": "The code for the service being requested, must be from the tutorial service codes ValueSet",
        "min": 1,
        "binding": {
          "strength": "required",
          "valueSet": "http://example.com/fhir/ValueSet/tutorial-service-codes"
        }
      }
    ]
  }
}

Create the mypackage/package.json file:

{
  "name": "tutorial-fhir-package",
  "version": "1.0.0",
  "description": "A tutorial FHIR package with ServiceRequest profile and required bindings",
  "fhirVersions": ["4.0.1"],
  "dependencies": {
    "hl7.fhir.r4.core": "4.0.1"
  },
  "author": "Tutorial Example",
  "license": "MIT"
}

The mypackage folder structure at this point should look like this:

mypackage
├── input
│   └── resources
│       ├── CodeSystem-tutorial-service-codes.json
│       ├── StructureDefinition-tutorial-service-request.json
│       └── ValueSet-tutorial-service-codes.json
└── package.json

Create tar.gz file for FHIR package with the following command:
```
cd mypackage && tar -czf ../tutorial-fhir-package-1.0.0.tgz .
```
Open Aidbox UI and navigate to the "FAR" tab. Click the "Import package" button. Select the tutorial-fhir-package-1.0.0.tgz file and click Import

At this point, you should be able to see the loaded package in the packages list.

Testing the local terminology

Navigate to Aidbox UI -> REST Console and create a patient with id pt-1

POST /fhir/Patient
content-type: application/json
accept: application/json

{
  "resourceType": "Patient",
  "id": "pt-1"
}

Create a ServiceRequest that is valid against the profile we imported with the package.

POST /fhir/ServiceRequest
content-type: application/json
accept: application/json

{
  "meta": {
    "profile": [
      "http://example.com/fhir/StructureDefinition/tutorial-service-request"
    ]
  },
  "status": "active",
  "intent": "order",
  "code": {
    "coding": [
      {
        "code": "consultation",
        "system": "http://example.com/fhir/CodeSystem/tutorial-service-codes"
      }
    ]
  },
  "requester": {
    "reference": "Patient/pt-1"
  },
  "subject": {
    "reference": "Patient/pt-1"
  },
  "identifier": [
    {
      "value": "123"
    }
  ],
  "authoredOn": "2024-01-01"
}

The meta.profile property contains the profile we imported and the code.coding contains a valid code from the code system we imported.

Create the invalid Service Request Execute the following request:

POST /fhir/ServiceRequest
content-type: application/json
accept: application/json

{
  "meta": {
    "profile": [
      "http://example.com/fhir/StructureDefinition/tutorial-service-request"
    ]
  },
  "status": "active",
  "intent": "order",
  "code": {
    "coding": [
      {
        "code": "follow-up",
        "system": "http://example.com/fhir/CodeSystem/tutorial-service-codes"
      }
    ]
  },
  "requester": {
    "reference": "Patient/pt-1"
  },
  "subject": {
    "reference": "Patient/pt-1"
  },
  "identifier": [
    {
      "value": "123"
    }
  ],
  "authoredOn": "2024-01-01"
}

You will see the error:

The provided code 'http://example.com/fhir/CodeSystem/tutorial-service-codes#follow-up' was not found in the value set 'http://example.com/fhir/ValueSet/tutorial-service-codes|1.0.0

It's expected because the CodeSystem http://example.com/fhir/CodeSystem/tutorial-service-codes doesn't contain the code follow-up

Adding new code to the CodeSystem

Let's say we want to add a new code to the CodeSystem we imported in a package. We can do it without creating a new version of the FHIR package and reloading package to the FHIR Server. ValueSet references the CodeSystem without mentioning the exact code system version:

"compose": {
    "include": [
      {
        "system": "http://example.com/fhir/CodeSystem/tutorial-service-codes"
      }
    ]
  }

That means the Aidbox will look to the latest version of the CodeSystem available in the system when validating the actual code. You can read more about versioning for canonical resources here.

Create the new version of the CodeSystem by executing the request below Note that we increased the version to 1.0.1 and added a follow-up code.

PUT /fhir/CodeSystem/tutorial-service-codes
content-type: application/json
accept: application/json

{
  "resourceType": "CodeSystem",
  "id": "tutorial-service-codes",
  "url": "http://example.com/fhir/CodeSystem/tutorial-service-codes",
  "version": "1.0.1",
  "name": "TutorialServiceCodes",
  "title": "Tutorial Service Codes",
  "status": "active",
  "experimental": false,
  "date": "2024-01-01",
  "publisher": "Tutorial Example",
  "description": "A sample code system for tutorial purposes containing service request codes",
  "caseSensitive": true,
  "content": "complete",
  "count": 4,
  "concept": [
    {
      "code": "consultation",
      "display": "Medical Consultation",
      "definition": "A general medical consultation service"
    },
    {
      "code": "lab-test",
      "display": "Laboratory Test",
      "definition": "Laboratory testing service"
    },
    {
      "code": "imaging",
      "display": "Medical Imaging",
      "definition": "Medical imaging service including X-ray, MRI, CT scan"
    },
    {
      "code": "follow-up",
      "display": "Follow-up Appointment",
      "definition": "A follow-up appointment service for ongoing care"
    }
  ]
}

Note that it's not possible to update the content of the package loaded in Aidbox - the new version of the CodeSystem was created in the default - app.aidbox.main package.

Verify that the request for creating a follow-up ServiceRequest can now be executed successfully:

POST /fhir/ServiceRequest
content-type: application/json
accept: application/json

{
  "meta": {
    "profile": [
      "http://example.com/fhir/StructureDefinition/tutorial-service-request"
    ]
  },
  "status": "active",
  "intent": "order",
  "code": {
    "coding": [
      {
        "code": "follow-up",
        "system": "http://example.com/fhir/CodeSystem/tutorial-service-codes"
      }
    ]
  },
  "requester": {
    "reference": "Patient/pt-1"
  },
  "subject": {
    "reference": "Patient/pt-1"
  },
  "identifier": [
    {
      "value": "123"
    }
  ],
  "authoredOn": "2024-01-01"
}

PreviousUploading IG terminology content to external FHIR terminology server NextValidation Tutorials

Last updated 16 hours ago

Was this helpful?