Metaandmed
Iga loend ja koodisüsteem on varustatud metaandmestikuga. Metaandmete soovitusliku koosseisu on kokku pannud Klassifikaatorite ja koodiloendite koordinatsioonikogu. Metaandmestik moodustab klassifikaatori/koodiloendi passi. Siinses juhendis on metaandmestik avaldatud loogilise andmemudelina ning metaandmed salvestatakse FHIR ressursi sees andmeelementides.
Üldised reeglid kõigile terminoloogiaressurssidele
- Väliste terminoloogiaressursside puhul (nt HL7) imporditakse ressurss tema algsete metaandmetega: id, url, name, and title. Eestikeelne nimetus on võimalik vajadusel lisada.
- Vaikimisi baasURL on https://fhir.ee/
| Andmeelement | Selgitus |
|---|---|
| id | Tüüpiliselt on id-ks nimetus väikeste tähtedega, tühikud asendada sidekriipsudega, ning täpitähed asendada vastavalt: ä-a, ö-o, õ-o, ü-y, š-sh, ž-zh. Kirjavahemärgid jms eemaldada. Soovituslik pikkus on kuni 30 tähemärki. Kui nimetus on oluliselt pikem, siis kaaluda loogilist lühendamist. Id peaks olema unikaalne ühe ressursitüübi piires (nt ValueSetil ja CodeSystemil võib olla sama id, kuid kahel ValueSetil mitte). |
| url | Kanoonilise URL (peamine identifikaator FHIRis) luuakse põhimõttel [baseURL]/[resource type]/[id], nt https://fhir.ee/ValueSet/mikroobi-kogus |
| fullURL | Ressursi aadress serveris. Kui id on määratud, siis tekitatakse automaatselt fullURL [serveri API endpoint]/[ressursi tüüp]/[id]--[versiooninumber], nt https://term.tehik.ee/fhir/ValueSet/mikroobi-kogus--4.0.0 |
| title | Nimetus, mis on kasutajatele kergesti arusaadav. Nimetus on reeglina eesti keeles, ingliskeelne nimetus on toodud translation elemendis. Nimetus peaks olema täpne ning piisavalt informatiivne ka väljaspool selle kasutuskonteksti. Nimetusse mitte lisada sõna “koodid”. Vaata ka allpool ConceptMap nimetuse loomist. |
| name | Masinsõbralik nimetus luuakse id-st ning ainult ühes keeles. Kasutada PascalCase’i (iga sõna suure tähega), tühikud ja kõik kirjavahemärgid peale ‘_’ eemaldada. Numbrid on lubatud. Akronüümid jäävad üleni suurtähtedega. Tähemärgilimiit on sama, mis id-l. Näiteks: ABOVeregrupp |
| identifier (OID) | OID on täiendav identifikaator ja kasutatakse URN kujul identifikaatori süsteemiga urn:ietf:rfc:3986. OIDi väärtus on kujul urn:oid:1.2.3. Versiooni OIDile lisandub identifier.use tunnus väärtusega “version” |
| status | Reeglina on staatus draft kuni avaldamiseni, avaldamise hetkel võib olla staatus active ning effectivePeriod.start kuupäev tulevikus. Kehtivuse lõppemisel märgitakse status väärtuseks “retired” ning lisatakse effectivePeriod.end kuupäev. |
| experimental | Märge viitab sellele, et ressurss on eksperimentaalne ehk mitte mõeldud reaalses andmevahetuses kasutamiseks (lubatud ainult testserveris). Seega ametlikult avaldatud ressurssidel on väärtus alati ‘false’. |
| version | Versiooninumber ärilisest vaatest, reeglina kasutame alati semantilist versioneerimist, kus versiooni esinumber peaks kattuma versiooni OIDi viimase numbriga. Väliste terminoloogiate puhul kasutame originaalis kasutatavat versiooninumbrit. |
| versioningAlgorithm | Reeglina ‘semver’, sest kasutame semantilist versioneerimist. Teatud juhtudel võib olla ka ‘date’ (nt SNOMED CT) või ‘alpha’ (alfabeetiline, nt EHAK) |
| publisher | Reeglina ‘TEHIK’ |
| contact | Reeglina ‘[email protected]’ |
| author | Omanik, reeglina organisatsioon. |
| description | Eesmärgi ja kasutuskoha kirjeldus. Vaikimisi on kirjeldus eestikeelne ning võimalik on lisada ka ingliskeelne tõlge. Kirjeldus on markdown formaadis ning lubatud on kasutada reavahetusi, esiletõstmisi ning linke lisamaterjalidele. |
| purpose | Eesmärk. Vabatahtlik andmeväli, kirjeldamaks koodisüsteemi eesmärki ning kasutuskohti pikemalt. Publitseerimiskeskusest migreeritud ressursside puhul ei ole täidetud ja seega hetkel harva kasutusel. |
CodeSystem
- Vaata üldisi reegleid ülalt.
| Andmeelement | Selgitus |
|---|---|
| url | Koodisüsteemi kanooniline URL tekitatakse https://fhir.ee/CodeSystem/[id] |
| identifier (OID) | Kui koodisüsteem ja loend on pärit samast publitseerimiskeskuse klassifikaatorist, on neil sama OID. |
| title | Koodisüsteemi tavapärane nimetus, mis võib olla ka akronüüm, juhul kui koodisüsteem on rohkem tuntud selle järgi. Nimetusse mitte lisada ressursi tüüpi “CodeSystem” või “CS”. Supplemendi puhul peaks nimetamisel lähtuma supplemendi eesmärgist: kui supplement on loodud ainult ühe loendi jaoks, on supplemendi nimi sama, mis loendil. Kui supplement on loodud üldisema eesmärgil ning on koodisüsteemi lahutamatu lisand (nt HL7 koodisüsteemide tõlked) või teenindab mitmeid loendeid (nt tehnilised koodid), siis peab nimi ka seda kajastama. |
| otherTitle | Paralleelne nimetus koodisüsteemile. Kasutusel vaid juhul, kui koodisüsteemil on mitu väga laialt kasutatavat nimetust. |
| caseSensitive | Märgitakse juhul, kui koodisüsteemi koodid on tõstutundlikud. Funktsionaalselt tõstutundlik on näiteks UCUM, samuti on tõstutundlikuks märgitud HL7 koodisüsteemid. |
| content | Reeglina on koodisüsteemid täielikud ehk ‘complete’. Koodisüsteemide lisandite (supplementide) puhul on väärtuseks ‘supplement’. Harvadel juhtudel on koodisüsteemist avaldatud on ainult osa, ning sel juhul kasutatakse väärtust ‘fragment’. |
| property | Koodisüsteemis kasutatavate tunnuste nimekiri koos tunnuse URI, nimetuse ning andmetüübiga. Enamkasutatavad tunnused (globaalsed tunnused) on kasutusel mitmetes koodisüsteemides ja avaldatud koodisüsteemidena (HL7 ja TEHIKu koodisüsteemid). Property URL on kujul [koodisüsteemi URL]#[property code] |
ValueSet
- Vaata üldisi reegleid ülalt
- Kui loend kasutab CodeSystem supplementi, on see märgitud vastavas extensionis.
| Andmeelement | Selgitus |
|---|---|
| url | Koodisüsteemi kanooniline URL tekitatakse https://fhir.ee/ValueSet/[id] |
| identifier (OID) | Kui koodisüsteem ja loend on pärit samast publitseerimiskeskuse klassifikaatorist, on neil sama OID. |
| title | Nimetuse mitte lisada ressursi tüüpi “ValueSet”, “loend” või “VS”. Samuti ei peaks nimetusse lisama sõna “koodid”. |
| compose.property | Tunnused, mis antakse vaikimisi kaasa ValueSet $expand operatsiooni puhul. Teisi koodisüsteemis toodud tunnuseid on võimalik pärida lisaks. |
| compose.include.system | Koodisüsteem, mille mõisteid loendisse kaasatakse (url). SNOMED CT puhul kasutame reeglina Eesti väljaande URLi “http://snomed.info/sct/11000181102”, sest tõlked ja üksikud mõisted on kättesaadavad ainult Eesti versioonis. Kuupäevalist versiooni reeglina ei kasuta, sisse peab olema lülitatud includeInactive, et oleks tagatud ajalooliste versioonide expansionite püsivus. Kui loend ja koodisüsteem on 1:1 vastavuses, siis viidatakse alati koodisüsteemi versioonile. Loendid, mis on kasutusel filtritena võivad olla ilma koodisüsteemi versioonita. |
ConceptMap
| Andmeelement | Selgitus |
|---|---|
| id | id võib olla pikem, sest peab sisaldama infot source’i ja target’i kohta ning vajadusel ka kontektsti kohta (vt title kirjeldust). |
| url | https://fhir.ee/ConceptMap/[id] |
| title | Nimetus järgib umbkaudu järgmist reeglit: Teema + source + target + vajadusel kontekst. Nt “Ravimvormide vastendus EDQM - SNOMED CT”. Loendiversioonide vahelise vastenduse puhul “Loendi nimi v1-v2 vastendus”. |
Kehtetuks tunnistamine
| Andmeelement | Selgitus |
|---|---|
| status | Kehtetu tunnistamisel kasutada staatust “retired” |
| version | Versiooninumber jääb samaks. |
| effectivePeriod | Kehtivuse lõpukuupäev on päev varasem kui uue versiooni kehtimahakkamise kuupäev. |
Koodisüsteemide puhul tehakse inaktiveeritud mõistete asendamist näitavad seosed replacedByCode ja replacedByCoding uue versiooni sisse.
Kui terminoloogiaressursist ei avaldata uut versiooni, vaid see on täielikult asendatud uue terminoloogiaressursiga, siis on võimalik uue ressursi juures kasutada andmeelementi replaces, et tekitada viide asendatud ressursile. Kui on vajalik mõistete tasandil seostamist uue ja vana koodisüsteemi vahel, siis luuakse ConceptMap või kasutatakse uues koodisüsteemis tunnust mapping.
Koodisüsteemi tunnused ja kirjeldused
Koodisüsteemide tunnused võivad olla üldises kasutuses (nt status, effectiveDate, parent) või spetsiifilised ühele koodisüsteemile (nt RFK lubatudMaaraja).
Sagedamini kasutatavad tunnused luuakse AKKs globaalsete tunnustena ning need tulevad reeglina kahest koodisüsteemist:
- FHIR Defined Concept Properties
- TEHIKu koodisüsteemides kasutatavad globaalsed tunnused [https://akk.tehik.ee/classifier/resources/code-systems/codesystem-concept-properties/summary]
Enamkasutatavad globaalsed tunnused (HL7 ja TEHIK):
| Kood | Nimetus | Kirjeldus | Andmetüüp |
|---|---|---|---|
| status | Staatus | HL7. Tunnus mõiste staatuse märkimiseks (active, retired, draft). | code |
| effectiveDate | Kehtivuse algus | HL7/TEHIK. Tunnus mõiste kehtivuse alguse märkimisel. HL7 defineerib selle kui viimane staatuse muutmise kuupäev, TEHIKu terminoloogiaressurssides mõiste kehtuks tunnistamine effectiveDate tunnust ei mõjuta. | dateTime |
| retirementDate | Kehtivuse lõpp | HL7. Mõiste kehtetuks tunnistamise kuupäev. | dateTime |
| replacedByCode | Asendav kood | TEHIK/HL7. Kehtetu koodi külge kuuluv tunnus, mis viitab seda asendavale koodile (tuleb kasutusele FHIR R6) | code |
| replacedByCoding | Asendav kood teises koodisüsteemis | TEHIK/HL7. Kehtetu koodi külge kuuluv tunnus, mis viitab seda asendavale koodile teises koodisüsteemis (tuleb kasutusele FHIR R6) | Coding |
| parent | Ülemmõiste | HL7. Tunnus, mis viitab mõiste vahetule vanemale. | code |
| groupedBy | Grupeeriv mõiste | TEHIK. Tunnus, mis viitab mõiste vanemale mingis kontekstis, nt on see kasutusel SNOMEDil põhinevate loendite hierarhia markeerimiseks juhul, kui loendis kasutatav hierarhia ei vasta koodisüsteemi hierarhiale. See tunnus aitab kasutajaliideses koodide kuvamisel ning seda ei arvestata koodisüsteemi $subsumes operatsioonil. | code |
| conceptOrder | Järjekorranumber | HL7 (extension). Abistav tunnus mõistete loogiliseks järjestamiseks, kui see on kasutuskogemuse seisukohalt oluline. Järjekorranumbrid määratakse selliste vahedega, et väiksemate muutuste korral ei peaks kogu koodisüsteemi järjekorranumbreid uuesti genereerima. Samuti on järjekorranumbrid piisavalt suured, et järjestamise tulemus oleks alfabeetilise ja numeerilise järjestamise korral sama. Järjekorranumbrid ei ole mõeldud kasutajaliideses väljakuvamiseks. | integer |
| comment | Kommentaar | HL7. Täiendav lisainfo mõiste või selle kasutamise kohta. Kasutatakse ka loendipõhistes supplementides, et pakkuda lisainfot mõiste kasutamise kohta just selle loendi kontekstis. | string |
| itemWeight | Arvväärtus | HL7. Tunnus, mida kasutatakse mõistega seotud arvväärtuse näitamiseks eelkõige skaalat kirjeldavate koodisüsteemide puhul. | decimal |
| notSelectable | Mittevalitav | HL7. Tunnus markeerib mõisteid, mis ei ole reeglina ette nähtud andmevahetuses kasutamiseks: nt vahepealkirju või täiendkoode. See, kas mõiste on kasutatav või mitte sõltub konkreetsest kasutuskohast, ja vajadusel on lubatud kasutada ka notSelectable märkega varustatud mõisteid. | boolean |
| ucum | UCUM notatsioon | TEHIK. Erinevates ühikuid sisaldavates koodisüsteemides mõistele vastava UCUM notatsiooni märkimiseks. Lubatud on kasutatud kogu UCUM grammatikat, mitte ainult põhikoode. Tunnuse väärtused tuleb valideerida. | code |
| mapping | Vastendus | TEHIK. Ekvivalentne mõiste teises koodisüsteemis (nt ümberkodeerimise puhul viitab kehtetuks tunnistatud koodisüsteemi mõistele) | Coding |
| synonym | Sünonüüm | HL7/TEHIK. Hetkel kasutusel üksikutes koodisüsteemides lühendi märkimiseks, kuid HL7 koodisüsteemis defineeritud alternatiivse koodina (kehtetu FHIR R6-s). TEHIKu koodisüsteemides asendab seda järk-järgult designation-use “abbreviation”. | string |
Enamkasutatavad kirjelduste tüübid
| Kood | Nimetus | Kirjeldus |
|---|---|---|
| definition | Definitsioon | Mõiste definitsioon. Publitseerimiskeskusest migreeritud andmetes on kohati tegemist pika nimetusega. |
| display | Nimetus | Vaikimisi nimetus mõiste kasutamisel |
| abbreviation | Lühinimetus | Lühendatud nimetus või akronüüm |
| inessive | Seesütlev | Nimetus seesütlevas käändes (nt ajaühikute puhul) |