Wiki

Clone wiki

best-practice / De facto-konventioner för datatyper

De facto-konventioner för datatyper

Version Datum Ändringar Person
1 2013-10-22 - Björn Genfors
2 2013-12-16 Justerat beskrivningen av HSAIdType och orgUnitHSAId (enligt issue 221) Björn Genfors
3 2014-02-17 Justerat schema-innehåll Khaled Daham
4 2014-03-21 -Lagt till ResultType, som används för att hantera logiska fel.
-Lagt till !RoleCode 0..1 i LegalAuthenticatorType (behov fanns i kontrakten för bild och EKG).
-Lagt till länkar till lista över vanligt förekommande kodverk och identifierare på lämpliga ställen.
Björn Genfors
5 2014-05-13 -Lagt till PQIntervalType.
-Justerat DateType att tillåta variabel noggrannhet.
-Förtydligat beskrivningen av vissa typer och/eller fält.
Björn Genfors
6 2014-08-21 Uppdaterad beskrivning för DateType och TimeStampType. Khaled Daham
7 2014-09-10 -Korrigerat dokumentation för DateType för att revertera möjligheten till variabel noggrannhet (kompatibilitetsbekymmer med ISO-standarder)
-Lagt till en ny typ, PartialDateType, för att bära information om datum med variabel noggrannhet.
Björn Genfors
8 2015-09-09 -Korrigerat ActorType.name till ActorType.personName. Björn Genfors
9 2016-06-28 Uppdaterat ActorType och OrgUnitType till ny typ framtagen inom arbetet för JoL Thomas Siltberg
10 2016-09-15 Tog bort ResultType för att få konsistens med regelverk och andra anvisningar Tommy Carlsson
11 2016-11-16 Lade tillbaka ResultType med struktur överensstämmande med regelverk och andra anvisningar Tommy Carlsson
12 2017-02-15 Förtydligat att elementen för att returnera logiska fel inte ska definieras som egen typ. Elementen ska inkluderas i svarstypen. Tommy Carlsson
13 2020-04-28 Tagit bort felaktiga element i ResultType och tillfört definition av PartialDateValueType i PartialDateType Arvid Thunholm
14 2020-09-10 Korrigering av datatyperna PQType och PQInterval för att stödja trailing zeros samt fixat formatering Arvid Thunholm
15 2020-11-03 Uppdatering av CVType och IIType Thomas Siltberg
16 2020-11-18 Uppdatering av information om PatientSummaryHeaderType Claudia Ehrentraut
17 2021-12-01 Ändrat multiplicitet för code och codeSystem i CVType från 1..1 till 0..1 Tobias Blomberg

Här dokumenteras best-practices för datatypshantering i tjänstekontrakt

Denna sida syftar till att öka återanvändningen av datatyper, och i förlängningen verka för återanvändbara profiler.

Gemensamma informationskomponenter

I tjänstekontraktsbeskrivningarna används ett antal komponenter som är gemensamma för vissa meddelanden i flera domäner eller inom denna domän, och dessa beskrivs i detta avsnitt.

Observera att med anledning av att tjänstekontrakten även kan stödjas av producentsystem som saknar (fullständig) HSA-id-information så är HSA-id-attribut i beskrivningarna nedan valfria. Se även avsnittet ”Informationssäkerhet” ovan.

ActorType

Information om medarbetare i vård- och omsorg som genomfört den behandling som rapporteras genom tjänstekontrakt i denna domän.

Namn Datatyp Beskrivning Kardinalitet
hsaId HSAIdType HSA-id för personen 0..1
personName string Namn på personen. Minst ett av dessa fälten hsaId och name ska anges. 0..1
personTelecom string Telefon till personen. 0..1
personEmail string Epostadress till personen. 0..1
personAddress string Postadress till personen. 0..1

CVType

En CVType är en referens till ett begrepp som definieras i ett externt kodverk (kodsystem, terminologi eller ontologi). Se vanligt förekommande kodverk. En CVType kan innehålla en enkel kod, det vill säga en hänvisning till ett begrepp som definieras direkt av det refererade kodverket, eller den kan innehålla ett uttryck i någon syntax definierad av det refererade kodverket som kan utvärderas, exempelvis begreppet "vänster fot" som är ett postkoordinerat uttryck byggt från den primära koden "FOT" och bestämningen "VÄNSTER".

Namn Datatyp Beskrivning Kardinalitet
code string Kod eller uttryck definierad enligt kodverket. 0..1
codeSystem string Kodverket som definierar koden. 0..1
codeSystemName string Kodverkets namn i klartext. 0..1
codeSystemVersion string Versionsangivelse som har definierats specifikt för det givna kodverket. 0..1
displayName string Den läsbara representationen (klartext) av koden eller uttrycket som definierat av kodverket. 0..1
originalText string Texten så som sedd och/eller vald av användaren som har matat in den, och som representerar användarens avsedda betydelse. 0..1

Regler

code
code ska vara en exakt match till en kod eller ett uttryck definierat av kodverket, som refereras till i codeSystem. Om kodverket definierar en kod eller ett uttryck som inkluderar mellanslag, ska koden inkludera mellanslaget. Ett uttryck kan endast användas där kodverket antingen definierar en uttryckssyntax, eller där det finns en allmänt accepterad syntax för kodverket.

Det åligger det mottagande systemet att bedöma om man kontrollerar huruvida det är ett uttryck som har skickats istället för en enkel kod, och utvärdera uttrycket istället för att behandla uttrycket som en kod. I vissa fall kan det vara oklart eller tvetydigt om koden representerar en enda symbol eller ett uttryck. Detta uppstår vanligtvis där kodverket definierar ett uttrycksspråk och sedan definierar prekoordinerade begrepp med symboler som matchar deras uttryck, t.ex. UCUM. I andra fall är det säkert att behandla uttrycket som en symbol. Det finns ingen garanti för att detta alltid är säkert: definitionerna i kodverket bör alltid konsulteras för att avgöra hur man ska hantera potentiella uttryck.

codeSystem
Kodverk ska refereras till genom en globalt unik identifierare, som möjliggör entydig hänvisning till standardkodverk eller andra lokala kodverk. Identifieraren ska vara en Universally Unique Identifier (UUID), Object Identifier (OID), eller Uniform Resource Identifier (URI). En CVType som har ett kodattribut ska ha ett kodverk som specificerar begreppsystemet som definierar koden.

codeSystemName
Syftet med ett kodverksnamn är att hjälpa en mänsklig tolkare av en kod att tolka codeSystem. Tjänstekonsumenter och tjänsteproducenter som använder codeSystemName ska INTE funktionellt förlita sig på kodverkets namn. Dessutom KAN de välja att inte implementera kodverkets namn men ska INTE avvisa instanser då namnet finns.

codeSystemVersion
Olika versioner av ett kodverk måste vara kompatibla. Per definition ska en kod ha samma betydelse i alla versioner av ett kodverk. Mellan versioner kan koder inaktiveras men inte tas bort eller återanvändas. Om klartexten av en kod ändras måste den fortfarande vara kompatibel (lika) mellan olika kodverksversioner.

displayName
Om ifylld, ska klartexten vara den läsbara representationen av koden eller uttrycket som definierat av kodverket vid tiden av datainmatningen. Om kodverket inte definierar en klartext för koden eller uttrycket, kan ingen tillhandahållas. Tjänstekonsumenter och tjänsteproducenter som hävdar direkt eller indirekt överensstämmelse KAN välja att inte implementera klartext men ska INTE avvisa instanser då klartext finns.

Huvudsyfte med klartexten är att stödja implementationsfelsökning, men kan även användas till andra tillämpningsspecifika ändamål som till exempel visning för användaren i gränssnittet.

originalText
Originaltexten kan användas i ett strukturerat användargränssnitt för att fånga vad användaren såg som en representation av koden på skärmen. I en situation där användaren dikterar eller direkt anger text är originaltexten den text som matats in eller yttrats av användaren. Originaltexten ska vara ett utdrag av relevant information i originalkällorna snarare än en pekare eller exakt reproduktion. Således ska originaltexten representeras i vanlig textform.

DatePeriodType

Ett datumintervall anges normalt sett med ett start- och ett slutdatum, men öppna intervall är tillåtna. Huruvida ändpunkterna inkluderas i intervallet eller ej bör tydligt beskrivas vid varje enskild tillämpning.

Namn Datatyp Beskrivning Kardinalitet
start DateType Periodens startdatum. Minst ett av start och end skall anges. 0..1
end DateType Periodens slutdatum. Minst ett av start och end skall anges. 0..1

DateType

Datum anges på formatet ”ÅÅÅÅMMDD”. Detta motsvarar den ISO 8601 och ISO 8824-kompatibla formatbeskrivningen ”YYYYMMDD”. Tidszon anges inte i meddelandeformaten. All information om datum och tidpunkter som utbyts via tjänsterna ska ange datum och tidpunkter i den tidszon som gäller/gällde i Sverige vid den tidpunkt som respektive datum- eller tidpunktsfält bär information om. Såväl tjänstekonsumenter som tjänsteproducenter skall med andra ord förutsätta att datum och tidpunkter som utbyts är i tidszonerna CET (svensk normaltid) respektive CEST (svensk normaltid med justering för sommartid).

Namn Datatyp Beskrivning Kardinalitet
date string Datum uttrycks på formatet ”ÅÅÅÅMMDD”. 1..1

HealthcareProfessionalType

Namn Datatyp Beskrivning Kardinalitet
authorTime TimeStampType Den tidpunkt då dokumentet skapades, eller annan tillämplig tidpunkt. 1..1
healthcareProfessionalHSAId HSAIdType HSA-id för vård- och omsorgspersonal. Skall anges om tillgänglig. 0..1
healthcareProfessionalName string Namn på vård- och omsorgspersonal. Om tillgängligt skall detta anges. 0..1
healthcareProfessionalRoleCode CVType Information om personens befattning. Om möjligt skall KV Befattning användas. 0..1
healthCareProfessionalOrgUnit OrgUnitType Den organisation som angiven vård- och omsorgsperson är uppdragstagare på. Om tillgängligt skall detta anges. 0..1
healthcareProfessionalCareUnitHSAId HSAIdType HSA-id för PDL-enhet som vård- och omsorgspersonen är uppdragstagare för. Skall anges om tillgänglig. 0..1
healthcareProfessionalCareGiverHSAId HSAIdType HSA-id för vårdgivaren, som är vårdgivare för den enhet som författaren är uppdragstagare för. Skall anges om tillgänglig. 0..1

HSAIdType

Namn Datatyp Beskrivning Kardinalitet
hsaId string HSA-id enligt definition från Inera AB. I de fall då HSA-id inte finns tillgängligt ska ett för källsystemet lokalt id användas. Lokala id:n får enbart användas i OrgUnitType, och då endast i undantagsfall. 1..1

IIType

En IIType är en numerisk eller alfanumerisk sträng som kan härledas till ett enskilt objekt eller entitet i ett känt system. Exempel är ett personnummer eller ett vårdkontakts-id. Se identifierare i nationella tjänstekontrakt.

Namn Datatyp Beskrivning Kardinalitet
root string En identifierare som i sig själv eller tillsammans med värdet för extension är universellt unik. Om extension anges är root en unik identifierare av namnrymden för värdet som anges i extension. 1..1
extension string En identifierare som tillsammans med värdet för root är universellt unik. Används om värdet på root inte är universellt unikt. 0..1

Regler

root
Identifieraren ska vara en Universally Unique Identifier (UUID), Object Identifier (OID), eller Uniform Resource Identifier (URI).

extension
Vissa scheman för identifierare definierar formateringsmöjligheter för deras kodvärden. Till exempel så skrivs personnumret vanligtvis med bindestreck, 19121212-1212. Bindestrecket bär dock ingen betydelse och kan utelämnas, som i 191212121212.

LegalAuthenticatorType

Används för att representera en signatur i samband med journalhandlingar.

Namn Datatyp Beskrivning Kardinalitet
signatureTime TimeStampType Tidpunkt för signering 1..1
legalAuthenticatorHSAId HSAIdType HSA-id för person som signerat dokumentet 0..1
legalAuthenticatorName string Namnen i klartext för signerande person 0..1
legalAuthenticatorRoleCode CVType Information om personens befattning. Om möjligt skall KV Befattning användas. 0..1

MultimediaType

Namn Datatyp Beskrivning Kardinalitet
id string Identitet på multimediaobjekt som används vid referenser inom multimediadokument. 0..1
mediaType MediaTypeEnum Mediatyper enligt HL7 1..1
value base64Binary Value är binärdata som representerar objektet. Ett och endast ett av value och reference ska anges. 0..1
reference anyURI Referens till extern bild i form av en URL. Ett och endast ett av value och reference ska anges. 0..1

OrgUnitType

Namn Datatyp Beskrivning Kardinalitet
orgUnitHSAId HSAIdType HSA-id för organisationsenhet. Om tillgängligt skall detta anges. I de fall HSA-id saknas kan ett för källsystemet unikt id användas. 0..1
orgUnitName string Namn på organisationsenhet. Om tillgängligt skall detta anges. 0..1
orgUnitTelecom string Telefon till organisationsenhet. 0..1
orgUnitEmail string Epost till organisationsenhet. 0..1
orgUnitAddress string Postadress till organisationsenhet. Skrivs på ett så naturligt sätt som möjligt, exempelvis:
”Storgatan 12
468 91 Lilleby”
0..1
orgUnitLocation string Text som anger namnet på plats eller ort för enhetens eller funktionens fysiska placering 0..1

PartialDateType

Kan beskriva ett datum med variabel noggrannhet.

Namn Datatyp Beskrivning Kardinalitet
format DateTypeFormatEnum Enum som beskriver datumets noggrannhet. Tillåtna värden är "YYYYMMDD", "YYYYMM" och "YYYY". 1..1
value string Sträng som håller själva datumet, och uttrycks på det format som anges i format. 1..1

PatientSummaryHeaderType

PatientSummaryHeaderType har utgått. Vid skapelse av nya tjänstekontrakt, resp. majoruppdateringar ska JoL-headern användas som finns beskrivit på Best-practice.

PersonIdType

Person-id är vanligtvis ett personnummer, men kan även vara samordningsnummer eller reservnummer. Syftar till att identifiera en privatperson.

Namn Datatyp Beskrivning Kardinalitet
id string Identiteten enligt den identitetstyp (type) som angivits. Om identiteten är av typ personnummer eller samordningsnummer skall denna anges med 12 tecken utan skiljetecken. 1..1
type string OID för typ av identifierare. 1..1

PQIntervalType

Typ som baseras på datatypen IVL_PQ enligt HL7, och som beskriver överföring av intervaller av mätbara värden (”Physical Quantity”). Ett intervall som är öppet i ena änden kan anges.

Tillåtna värden för ”unit” bestäms av http://unitsofmeasure.org/ucum.html. Dimension ska preciseras av fältregel vid tillämpning (ex. ”Massa”). Vaksamhet skall iakttagas vid konvertering mellan enheter.

Notera att den specialiserade datatypen decimal-primitive används istället för xmltyperna double/decimal. Decimal-primitive behåller signifikanta avslutande 0:or, till skillnad från de föregående. Denna lösning är tagen från HL7 FHIR Release 4 - datatyper.

Namn Datatyp Beskrivning Kardinalitet
low decimal-primitive Mätetal mätt i enheten som anges av ”unit”. Minst ett av fälten low och high måste anges. 0..1
high decimal-primitive Mätetal mätt i enheten som anges av ”unit”. Minst ett av fälten low och high måste anges. 0..1
unit string Enhet enligt [http://unitsofmeasure.org/ucum.html UCUM] 1..1

PQType

Typ som baseras på datatypen PQ enligt HL7, och som beskriver överföring av mätbara värden (”Physical Quantity”). Tillåtna värden för ”unit” bestäms av http://unitsofmeasure.org/ucum.html. Dimension ska preciseras av fältregel vid tillämpning (ex. ”Massa”). Vaksamhet skall iakttagas vid konvertering mellan enheter.

Notera att den specialiserade datatypen decimal-primitive används istället för xmltyperna double/decimal. Decimal-primitive behåller signifikanta avslutande 0:or, till skillnad från de föregående. Denna lösning är tagen från HL7 FHIR Release 4 - datatyper.

Namn Datatyp Beskrivning Kardinalitet
value decimal-primitive Mätetal mätt i enheten som anges av ”unit”. 1..1
unit string Enhet enligt [http://unitsofmeasure.org/ucum.html UCUM] 1..1

ResultType

Element för att returnera logiska fel i uppdaterande tjänster. Ska inte definieras som egen typ utan inkluderas i svarstypen.

Namn Datatyp Beskrivning Kardinalitet
resultCode ResultCodeEnum Kan endast vara OK, INFO eller ERROR. 1..1
resultText string En beskrivande text som kan visas för användaren. 0..1

TimePeriodType

Ett tidsintervall anges normalt sett med en start- och en sluttidpunkt, men öppna intervall är tillåtna. Huruvida ändpunkterna inkluderas i intervallet eller ej bör tydligt beskrivas vid varje enskild tillämpning.

Namn Datatyp Beskrivning Kardinalitet
start TimeStampType Periodens starttid. Minst ett av start och end skall anges. 0..1
end TimeStampType Periodens sluttid. Minst ett av start och end skall anges. 0..1

TimeStampType

Tidpunkter anges alltid på formatet ”ÅÅÅÅMMDDttmmss”, vilket motsvarar den ISO 8601 och ISO 8824-kompatibla formatbeskrivningen ”YYYYMMDDhhmmss”. Tidszon anges inte i meddelandeformaten. All information om datum och tidpunkter som utbyts via tjänsterna ska ange datum och tidpunkter i den tidszon som gäller/gällde i Sverige vid den tidpunkt som respektive datum- eller tidpunktsfält bär information om. Såväl tjänstekonsumenter som tjänsteproducenter skall med andra ord förutsätta att datum och tidpunkter som utbyts är i tidszonerna CET (svensk normaltid) respektive CEST (svensk normaltid med justering för sommartid).

Namn Datatyp Beskrivning Kardinalitet
timestamp string Tid uttrycks på formatet ”ÅÅÅÅMMDDttmmss”. 1..1

Updated