Overview
Clinia borrows concepts from HL7's FHIR specification terminology to create its own terminology. There are 3 main elements to this terminology:
- Code system - declares the existence of and describes a code system, its key properties and its content.
- Concept - describes a real world concept with a code, within the context of a code system.
- Value set - specifies a set of codes drawn from one or more code systems, intended for use in a particular context. Value sets links code system definitions and their use in resources.
- Property binding - specifies the scope of a property by referencing a specific value set from which values should be taken from.
Usage
Code systems, concepts, value sets and bindings are used to create boundaries around the data contained inside resources. They allow for a better definition of what properties are and what values can and can not be stored inside a given property.
Code systems define which codes exist, and how they are understood. Because codes by themselves don't have any meaning, we call concept a code existing within the context of a code system.
If code systems are there to define available codes, value sets aggregate concepts from one or multiple code systems and make those concepts usable by resources in a particular context. By using property bindings, one can indicate that the values stored inside a certain property should be taken from a specific value set. This gives a context to the property and allow for better understanding and control over a property's value.
Concepts stored in properties should be stored using the Coding data type. This allow all the concept's information to be stored within the property so it is usable by all.
There exists a code system for all ISO 3166-1 alpha-2 country codes. Within this code system, every country code is represented as a concept. The meaning of the code af is defined by its use within this code system. Outside of this code system's context, the code af could mean any number of things.
{
"key": "iso-3166-country-code",
"version": "1",
"displayName": {
"en": "Country codes",
"fr": "Codes pays"
},
"concepts": [
{
"value": "af",
"displayName": {
"en": "Afghanistan",
"fr": "Afghanistan"
}
},
{
"value": "al",
"displayName": {
"en": "Albania",
"fr": "Albanie"
}
}
//...
]
}
There exists a value set containing all ISO 3166-1 alpha-2 country codes for north american countries. This value set contains only a limited number of concepts from the iso-3166-country-code code system.
{
"key": "north-american-iso-3166-country-code",
"version": "1",
"displayName": {
"en": "North American Country codes",
"fr": "Codes pays d'Amérique du Nord"
},
"concepts": [
{
"value": "ca",
"displayName": {
"en": "Canada",
"fr": "Canada"
}
},
{
"value": "us",
"displayName": {
"en": "United States of America",
"fr": "États Unis d'Amérique"
}
}
//...
]
}
Within a fictional resource type Example, there exists a supplier property bound to the north-american-iso-3166-country-code. All values for this property should be taken from the bound value set and stored as codings with their respective code, code system and version information.
Versioning
Most code systems evolve over time, due to corrections, clarifications, and changes to approach or underlying knowledge or reality. If these changes lead to the meanings of existing codes changing significantly, then the interpretation of the code system becomes version dependent.
For this reason, a code system should always be referenced by a pair of key/version attributes. It is why the Coding contains both a system and version attribute. This ensures that the meaning of a concept is clearly defined within the context of a specific version of a code system.
Ontology
Clinia utilizes code systems and value sets to provide users with a quick and easy way to navigate its healthcare ontology. Clinia's ontology establishes a directed graph of common and shared healthcare concepts that can be used within its information systems. Within this ontology, there exists 4 main categories:
- Speciality - describes a healthcare speciality, often-times the umbrella under which many healthcare services exist.
- Service - describes a healthcare service, like a treatment, a type of consultation, etc.
- Profession - describes a profession a healthcare professional can exercise.
- Overspecialization - describes a specialization of an existing concept.
For each of these categories, there exist a code system of the same name that gathers all concepts within this category. Since we do not want to directly use code systems when managing resources, there exists an equivalent value set for 2 of these code systems and they contain the exact same concepts as the code systems. These two value sets are speciality and profession.
In addition to these basic value sets, their exist value sets for many ontology concepts to describe their relationships to other concepts of the directed graph.
- For each Speciality, there is a value set with the speciality's id as
key, and this value set contains concepts from theserviceandoverspecializationcode systems. All the concepts from a speciality's value set are direct neighbors of the speciality in the ontology. - For each Service, there is a value set with the service's id as
key, and this value set contains concepts from theserviceandoverspecializationcode systems. All the concepts from a service's value set are direct neighbors of the service in the ontology. - For each Profession, there is a value set with the profession's id as
key, and this value set contains concepts from theserviceandoverspecializationcode systems. All the concepts from a profession's value set are direct neighbors of the profession in the ontology. - Overspecialization does not have neighbors.
It is important to understand that the directed nature of the graph means only certain resource types can be created under others. This is all detailed inside the Resource Types section of the documentation, but this is where the restrictions originate.
There exist a fictional clinic resource called 123 Clinic. After consulting the Speciality value set, I decide I want to create a new Cardiology department for this clinic. From the value set, I see that the Cardiology concept's value is 0001.
{
"key": "speciality",
"version": "1",
"displayName": {
"en": "Specialities",
"fr": "Spécialité"
},
"concepts": [
{
"value": "0001",
"displayName": {
"en": "Cardiology",
"fr": "Cardiologie"
},
"codeSystemKey": "speciality",
"version": "1"
},
{
"value": "0002",
"displayName": {
"en": "Psychology",
"fr": "Psychologie"
},
"codeSystemKey": "speciality",
"version": "1"
}
//...
]
}
I create a new Speciality resource referenceing both the existing clinic and the Cardiology concept.
{
"parent": {
"id": "123-clinic",
"referenceType": "clinic"
},
"concept": {
"value": "0001",
"displayName": [
{
"code": "en",
"value": "Cardiology"
},
{
"code": "fr",
"value": "Cardiologie"
}
],
"codeSystemKey": "speciality",
"version": "1"
}
}
I know that this clinic resource also offers specific Cardiology services. I can look for those supported services by fecthing the Cardiology value set.
{
"key": "0001",
"version": "1",
"displayName": {
"en": "Cardiology Services and Overspecializations",
"fr": "Services et surspécialization de cardiologie"
},
"concepts": [
{
"value": "10001",
"displayName": {
"en": "Heart transplant",
"fr": "Greffe du coeur"
},
"codeSystemKey": "service",
"version": "1"
},
{
"value": "10002",
"displayName": {
"en": "Cardiology consultation",
"fr": "Consultation en cardiologie"
},
"codeSystemKey": "service",
"version": "1"
},
{
"value": "10003",
"displayName": {
"en": "Abdominal CT scan",
"fr": "Scan abdominal"
},
"codeSystemKey": "service",
"version": "1"
}
//...
]
}
I create a new Service resource referencing the Cardiology Speciality resource and the Heart transplant concept.
{
"parent": {
"id": "speciality-0001",
"referenceType": "speciality"
},
"concept": {
"value": "10001",
"displayName": [
{
"code": "en",
"value": "Hearth transplant"
},
{
"code": "fr",
"value": "Greffe du coeur"
}
],
"codeSystemKey": "service",
"version": "1"
}
}
Now, when I fetch my 123 Clinic resource, I will also get the associated ontology resources.
{
"id": "123-clinic",
"name": "123 Clinic",
//...
"speciality": [
{
"id": "speciality-0001",
"parent": {
"id": "123-clinic",
"referenceType": "clinic"
},
"concept": {
"value": "0001",
"displayName": [
{
"code": "en",
"value": "Cardiology"
},
{
"code": "fr",
"value": "Cardiologie"
}
],
"codeSystemKey": "speciality",
"version": "1"
},
"service": [
{
"id": "service-10001",
"parent": {
"id": "speciality-0001",
"referenceType": "speciality"
},
"concept": {
"value": "10001",
"displayName": [
{
"code": "en",
"value": "Hearth transplant"
},
{
"code": "fr",
"value": "Greffe du coeur"
}
],
"codeSystemKey": "service",
"version": "1"
}
}
]
}
]
}
Endpoints
Get Value Set
Returns the value set for the id provided by the request. One can fetch a value set either by its id or its key.
GET /v1/value-sets/:key
Generic value sets are sets that are not part of the ontology. The available generic value sets are:
spoken-language- List of supported spoken languages, likefranden.professional-title- List of supported professional titles, likedranddre.administrative-gender- List of supported adminitrative gender, likemaleandfemale.age-category- List of supported age category, likechildrenandadults.booking-day- List of supported moments at which you can book an appointment for the current day, likesame-dayandday-before.ca-region- List of Canadian regions, likeqcandon.phone-use- List of supported phone types, likemainandreception.url-use- List of supported url types, likefacebookandtwitter.
Response
| Field | Type | Description |
|---|---|---|
id | Symbol | Unique identifier. |
key | Symbol | Unique, human-readable identifier. |
displayName | Dictionary<Symbol, Symbol> | Display name for the value set. |
includes | Array<Grouping> | Concepts part of the value set, grouped by code systems. |
Example
{
"id": "cd429379-821e-42e1-8d4c-815349534670",
"createdAt": "2021-10-12T18:24:09.651074Z",
"updatedAt": "2021-10-12T18:24:09.651074Z",
"key": "spoken-language",
"displayName": {
"en": "Language",
"fr": "Langue"
},
"includes": [
{
"system": "spoken-language",
"concepts": [
{
"system": "spoken-language",
"version": 1,
"value": "ar",
"displayName": {
"en": "Arabic",
"fr": "Arabe"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "pa",
"displayName": {
"en": "Punjabi",
"fr": "Pendjabi"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "es",
"displayName": {
"en": "Spanish",
"fr": "Espagnol"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "ur",
"displayName": {
"en": "Urdu",
"fr": "Ourdou"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "fr",
"displayName": {
"en": "French",
"fr": "Français"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "en",
"displayName": {
"en": "English",
"fr": "Anglais"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "bn",
"displayName": {
"en": "Bengali",
"fr": "Bengali"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "ta",
"displayName": {
"en": "Tamil",
"fr": "Tamoul"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "tl",
"displayName": {
"en": "Tagalog",
"fr": "Tagalog"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "hi",
"displayName": {
"en": "Hindi",
"fr": "Hindi"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "vi",
"displayName": {
"en": "Vietnamese",
"fr": "Vietnamien"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "ht",
"displayName": {
"en": "Creole",
"fr": "Créole"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "cantonese",
"displayName": {
"en": "Cantonese",
"fr": "Cantonais"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "mandarin",
"displayName": {
"en": "Mandarin",
"fr": "Mandarin"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "it",
"displayName": {
"en": "Italian",
"fr": "Italien"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "pt",
"displayName": {
"en": "Portuguese",
"fr": "Portugais"
}
}
]
}
]
}
Search Value Set Concepts
Returns a collection of concepts from a given value set after applying the request's filters.
GET /v1/value-sets/:key/concepts
Request Param
query- (string) specifies the chain of characters to search for in the concepts' display name.language- (string) specifies the language of the name the query should be applied to. If not specified, the query will be searched for in all languages.page- (int) specifies the page from which to return results from. Defaults to0.perPage- (int) specifies the page size. Defaults to20.
Response
| Field | Type | Description |
|---|---|---|
page | Integer | Current page. |
perPage | Integer | Number of results per page. |
total | Integer | Total number of results matching the query. |
data | Array<Concept> | List of concepts matching the query. |
Example
{
"page": 0,
"perPage": 20,
"total": 2,
"data": [
{
"system": "spoken-language",
"version": 1,
"value": "ta",
"displayName": {
"en": "Tamil",
"fr": "Tamoul"
}
},
{
"system": "spoken-language",
"version": 1,
"value": "tl",
"displayName": {
"en": "Tagalog",
"fr": "Tagalog"
}
}
]
}
Models
Concept
| Field | Type | Description |
|---|---|---|
value | Symbol | Code for the concept. |
system | Symbol | Key of the associated code system. |
version | Symbol | Version of the associated code system. |
displayName | Dictionary<Symbol, Symbol> | Display name for the value set. |
Concept Grouping
| Field | Type | Description |
|---|---|---|
system | Symbol | Key of the associated code system. |
concepts | Array<Concept> | List of concepts. |