The CodeSystem
resource specifies a set of Concepts included in this code system.
​Aidbox assumes a separate creation of the CodeSystem
resource and a set of Concepts
composing it. This means that the CodeSystem resource describes only meta information of the code system: url, name, publisher, etc. Whereas Concept resources describe the content of the code system and are associated with the code system by the Concept.system attribute with the same value as the CodeSystem.url element.
For FHIR conformance, we allow to create the CodeSystem resource with a list of included concepts. In the moment of saving a CodeSystem, if it contains listed Concepts, then Aidbox saves submitted Concepts as separate resources, and the CodeSystem resource itself is saved without the concept attribute. This method of the CodeSystem creation may be used for small dictionaries (generally, not more than 100 concepts). In case when your code system is big, Aidbox strongly recommends to create the CodeSystem resource separately and upload Concepts in parts.
​CodeSystem
resource can be created as a FHIR resource with embedded concepts itself. This approach is applicable for those cases if your code system contains a small number of concepts, usually no more than 100.
For example, we will create a CodeSystem
for eye color containing Brown
, Blue
, Green
, Hazel
, Heterochromia
coded concepts.
POST [base]/CodeSystem​{"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"}]}
STATUS: 201​{"resourceType": "CodeSystem","id": "custom-eye-color""url": "http://code.system/eyes.color","status": "draft","content": "example"}
As you can see, the request returns only CodeSystem
meta information (url, status, content....), and does not return concept
listed in then request. It is because Aidbox
divides CodeSystem
to CodeSystem
body and contained concepts list, and creates all concepts as independent Concept
resources.
And if we get Concept
with system
= http://code.system/eyes.color
, we will receive all concepts for this CodeSystem.
GET [base]/CodeSystem?system=http://code.system/eyes.color
STATUS: 200​{"resourceType": "Bundle","type": "searchset","entry": [{"resource": {"id": "custom-eye-color-ec-bn","code": "ec-bn","system": "http://code.system/eyes.color","display": "Brown","resourceType": "Concept"}},{"resource": {"id": "custom-eye-color-ec-be","code": "ec-be","system": "http://code.system/eyes.color","display": "Blue","resourceType": "Concept"}},{"resource": {"id": "custom-eye-color-ec-gn","code": "ec-gn","system": "http://code.system/eyes.color","display": "Green","resourceType": "Concept"}},{"resource": {"id": "custom-eye-color-ec-hl","code": "ec-hl","system": "http://code.system/eyes.color","display": "Hazel","resourceType": "Concept"}},{"resource": {"id": "custom-eye-color-ec-h","code": "ec-h","system": "http://code.system/eyes.color","display": "Heterochromia","resourceType": "Concept"}}],"total": 5,......}
Another way to create CodeSystem
is a separate creation of the CodeSystem body and Concepts.
For example, lets create CodeSystem with custom subset of Units of measurement (aka UCUM). We will compose this CodeSystem from the most common healthcare units of measure.
Code | Descriptive Name | Display |
% | Persent | % |
/uL | PerMicroLiter | /uL |
[iU]/L | InternationalUnitsPerLiter | IU/L |
kPa | KiloPascal | kPa |
ng/mL | NanoGramsPerMilliLiter | ng/mL |
U/L | UnitsPerLiter | U/L |
u[iU]/mL | MicroInternationalUnitsPerMilliLiter | uIU/mL |
ug/dL | MicroGramsPerDeciLiter | ug/dL |
ug/L | MicroGramsPerLiter | ug/L |
ug/mL | MicroGramsPerMilliLiter | ug/mL |
umol/L | MicroMolesPerLiter | umol/L |
For this subset, let's create the CodeSystem
resource.
POST [base]/CodeSystem​{"resourceType": "CodeSystem","id": "custom-ucum-subset","url": "http://code.system/ucum.subset","status": "active","content": "complete"}
STATUS: 201​{"id": "custom-ucum-subset","resourceType": "CodeSystem""url": "http://code.system/ucum.subset","status": "active","content": "complete"}
And then, create all listed concepts. We can create a set of concepts via multiple POST
requests or via one Transaction
request.
POST [base]/Concept​{"resourceType": "Concept","system": "http://code.system/ucum.subset","code": "%","display": "%","definition": "Persent"}​POST [base]/Concept​{"resourceType": "Concept","system": "http://code.system/ucum.subset","code": "/uL","display": "/uL","definition": "PerMicroLiter"}​POST [base]/Concept​{"resourceType": "Concept","system": "http://code.system/ucum.subset","code": "[iU]/L","display": "IU/L","definition": "InternationalUnitsPerLiter"}​......​POST [base]/Concept​{"resourceType": "Concept","system": "http://code.system/ucum.subset","code": "umol/L","display": "umol/L","definition": "MicroMolesPerLiter"}
POST [base]​{"type": "transaction","entry": [{"request": {"method": "POST","url": "/Concept"},"resource": {"resourceType": "Concept","system": "http://code.system/ucum.subset","code": "%","display": "%","definition": "Persent"}},{"request": {"method": "POST","url": "/Concept"},"resource": {"resourceType": "Concept","system": "http://code.system/ucum.subset","code": "/uL","display": "/uL","definition": "PerMicroLiter"}},{"request": {"method": "POST","url": "/Concept"},"resource": {"resourceType": "Concept","system": "http://code.system/ucum.subset","code": "umol/L","display": "umol/L","definition": "MicroMolesPerLiter"}}]}
The read
operation works same as the FHIR read
interaction.
GET [base]/CodeSystem/custom-eye-color
STATUS: 201​{"resourceType": "CodeSystem","id": "custom-eye-color""url": "http://code.system/eyes.color","status": "draft","content": "example"}
Aidbox does not support update for the CodeSystem resource.
In the terminology, it is a good practice not to update existing Coded Systems. Aidbox follows this principle. If you need to update any existing CodeSystem resource, you will have to explicitly delete this CodeSystem and re-create it again with your changes.
On delete CodeSystem
, Aidbox deletes CodeSystem
resource, and marks each Concept
with the deprecated
= true
.
DELETE [base]/CodeSystem/custom-eye-color
STATUS: 201​{"url": "http://code.system/eyes.color","status": "draft","content": "example","id": "custom-eye-color","resourceType": "CodeSystem"}
Let's check all concepts of the system.
GET [base]/Concept/?system=http://code.system/eyes.color
STATUS: 200​{"resourceType": "Bundle","type": "searchset","entry": [{"resource": {"id": "custom-eye-color-ec-bn","deprecated": true,"code": "ec-bn","system": "http://code.system/eyes.color","display": "Brown","resourceType": "Concept"}},{"resource": {"id": "custom-eye-color-ec-be","deprecated": true,"code": "ec-be","system": "http://code.system/eyes.color","display": "Blue","resourceType": "Concept"}},{"resource": {"id": "custom-eye-color-ec-gn","deprecated": true,"code": "ec-gn","system": "http://code.system/eyes.color","display": "Green","resourceType": "Concept"}},{"resource": {"id": "custom-eye-color-ec-hl","deprecated": true,"code": "ec-hl","system": "http://code.system/eyes.color","display": "Hazel","resourceType": "Concept"}},{"resource": {"id": "custom-eye-color-ec-h","deprecated": true,"code": "ec-h","system": "http://code.system/eyes.color","display": "Heterochromia","resourceType": "Concept"}}],"total": 5,......}
Aidbox supports all standard FHIR terminology CodeSystem operations.