Aidbox configuration
API
Profiling and validation
Terminology
FHIR Implementation Guides
App development guides
Security & Access Control
Integrations
Tools
CodeSystem
Overview
​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. If it contains listed Concepts at the moment of saving a CodeSystem, then Aidbox saves submitted Concepts as separate resources. 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 the case when your code system is big, Aidbox strongly recommends to create the CodeSystem resource separately and upload Concepts in parts.
CRUD
Create
​
CodeSystem resource can be created as a FHIR resource with embedded concepts itself. This approach is applicable for those cases when 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.Request
Response
1
POST [base]/CodeSystem
2
​
3
{
4
"resourceType" : "CodeSystem",
5
"id": "custom-eye-color",
6
"status": "draft",
7
"url": "http://code.system/eyes.color",
8
"content": "example",
9
"concept" : [
10
{
11
"code": "ec-bn",
12
"display": "Brown"
13
},
14
{
15
"code": "ec-be",
16
"display": "Blue"
17
},
18
{
19
"code": "ec-gn",
20
"display": "Green"
21
},
22
{
23
"code": "ec-hl",
24
"display": "Hazel"
25
},
26
{
27
"code": "ec-h",
28
"display": "Heterochromia"
29
}
30
]
31
}
Copied!
1
STATUS: 201
2
​
3
{
4
"resourceType": "CodeSystem",
5
"id": "custom-eye-color"
6
"url": "http://code.system/eyes.color",
7
"status": "draft",
8
"content": "example"
9
}
Copied!
As you can see, the request returns only
CodeSystem meta information (url, status, content....), and does not return concept listed in that 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.Request
Response
1
GET [base]/CodeSystem?system=http://code.system/eyes.color
Copied!
1
STATUS: 200
2
​
3
{
4
"resourceType": "Bundle",
5
"type": "searchset",
6
"entry": [
7
{
8
"resource": {
9
"id": "custom-eye-color-ec-bn",
10
"code": "ec-bn",
11
"system": "http://code.system/eyes.color",
12
"display": "Brown",
13
"resourceType": "Concept"
14
}
15
},
16
{
17
"resource": {
18
"id": "custom-eye-color-ec-be",
19
"code": "ec-be",
20
"system": "http://code.system/eyes.color",
21
"display": "Blue",
22
"resourceType": "Concept"
23
}
24
},
25
{
26
"resource": {
27
"id": "custom-eye-color-ec-gn",
28
"code": "ec-gn",
29
"system": "http://code.system/eyes.color",
30
"display": "Green",
31
"resourceType": "Concept"
32
}
33
},
34
{
35
"resource": {
36
"id": "custom-eye-color-ec-hl",
37
"code": "ec-hl",
38
"system": "http://code.system/eyes.color",
39
"display": "Hazel",
40
"resourceType": "Concept"
41
}
42
},
43
{
44
"resource": {
45
"id": "custom-eye-color-ec-h",
46
"code": "ec-h",
47
"system": "http://code.system/eyes.color",
48
"display": "Heterochromia",
49
"resourceType": "Concept"
50
}
51
}
52
],
53
"total": 5,
54
......
55
}
Copied!
Another way to create
CodeSystem is a separate creation of the CodeSystem body and Concepts.For example, lets create a CodeSystem with a 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.Request
Response
1
POST [base]/CodeSystem
2
​
3
{
4
"resourceType": "CodeSystem",
5
"id": "custom-ucum-subset",
6
"url": "http://code.system/ucum.subset",
7
"status": "active",
8
"content": "complete"
9
}
Copied!
1
STATUS: 201
2
​
3
{
4
"id": "custom-ucum-subset",
5
"resourceType": "CodeSystem"
6
"url": "http://code.system/ucum.subset",
7
"status": "active",
8
"content": "complete"
9
}
Copied!
And then, create all listed concepts. We can create a set of concepts via multiple
POST requests or via one Transaction request.Multiple requests
Transaction request
1
POST [base]/Concept
2
​
3
{
4
"resourceType": "Concept",
5
"system": "http://code.system/ucum.subset",
6
"code": "%",
7
"display": "%",
8
"definition": "Persent"
9
}
10
​
11
POST [base]/Concept
12
​
13
{
14
"resourceType": "Concept",
15
"system": "http://code.system/ucum.subset",
16
"code": "/uL",
17
"display": "/uL",
18
"definition": "PerMicroLiter"
19
}
20
​
21
POST [base]/Concept
22
​
23
{
24
"resourceType": "Concept",
25
"system": "http://code.system/ucum.subset",
26
"code": "[iU]/L",
27
"display": "IU/L",
28
"definition": "InternationalUnitsPerLiter"
29
}
30
​
31
......
32
​
33
POST [base]/Concept
34
​
35
{
36
"resourceType": "Concept",
37
"system": "http://code.system/ucum.subset",
38
"code": "umol/L",
39
"display": "umol/L",
40
"definition": "MicroMolesPerLiter"
41
}
Copied!
1
POST [base]
2
​
3
{
4
"type": "transaction",
5
"entry": [
6
{
7
"request": {
8
"method": "POST",
9
"url": "/Concept"
10
},
11
"resource": {
12
"resourceType": "Concept",
13
"system": "http://code.system/ucum.subset",
14
"code": "%",
15
"display": "%",
16
"definition": "Persent"
17
}
18
},
19
{
20
"request": {
21
"method": "POST",
22
"url": "/Concept"
23
},
24
"resource": {
25
"resourceType": "Concept",
26
"system": "http://code.system/ucum.subset",
27
"code": "/uL",
28
"display": "/uL",
29
"definition": "PerMicroLiter"
30
}
31
},
32
{
33
"request": {
34
"method": "POST",
35
"url": "/Concept"
36
},
37
"resource": {
38
"resourceType": "Concept",
39
"system": "http://code.system/ucum.subset",
40
"code": "umol/L",
41
"display": "umol/L",
42
"definition": "MicroMolesPerLiter"
43
}
44
}
45
]
46
}
Copied!
Read
The
read operation works same as the FHIR read interaction.Request
Response
1
GET [base]/CodeSystem/custom-eye-color
Copied!
1
STATUS: 201
2
​
3
{
4
"resourceType": "CodeSystem",
5
"id": "custom-eye-color"
6
"url": "http://code.system/eyes.color",
7
"status": "draft",
8
"content": "example"
9
}
Copied!
Update
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.
Delete
On delete
CodeSystem, Aidbox deletes CodeSystem resource, and marks each Concept with the deprecated = true.Request
Response
1
DELETE [base]/CodeSystem/custom-eye-color
Copied!
1
STATUS: 201
2
​
3
{
4
"url": "http://code.system/eyes.color",
5
"status": "draft",
6
"content": "example",
7
"id": "custom-eye-color",
8
"resourceType": "CodeSystem"
9
}
Copied!
Let's check all concepts of the system.
Request
Response
1
GET [base]/Concept/?system=http://code.system/eyes.color
Copied!
1
STATUS: 200
2
​
3
{
4
"resourceType": "Bundle",
5
"type": "searchset",
6
"entry": [
7
{
8
"resource": {
9
"id": "custom-eye-color-ec-bn",
10
"deprecated": true,
11
"code": "ec-bn",
12
"system": "http://code.system/eyes.color",
13
"display": "Brown",
14
"resourceType": "Concept"
15
}
16
},
17
{
18
"resource": {
19
"id": "custom-eye-color-ec-be",
20
"deprecated": true,
21
"code": "ec-be",
22
"system": "http://code.system/eyes.color",
23
"display": "Blue",
24
"resourceType": "Concept"
25
}
26
},
27
{
28
"resource": {
29
"id": "custom-eye-color-ec-gn",
30
"deprecated": true,
31
"code": "ec-gn",
32
"system": "http://code.system/eyes.color",
33
"display": "Green",
34
"resourceType": "Concept"
35
}
36
},
37
{
38
"resource": {
39
"id": "custom-eye-color-ec-hl",
40
"deprecated": true,
41
"code": "ec-hl",
42
"system": "http://code.system/eyes.color",
43
"display": "Hazel",
44
"resourceType": "Concept"
45
}
46
},
47
{
48
"resource": {
49
"id": "custom-eye-color-ec-h",
50
"deprecated": true,
51
"code": "ec-h",
52
"system": "http://code.system/eyes.color",
53
"display": "Heterochromia",
54
"resourceType": "Concept"
55
}
56
}
57
],
58
"total": 5,
59
......
60
}
Copied!
Operations
FHIR specification
Status
Documentation and samples
Last modified 1yr ago