Anvisning för utformning av nyttolast i tjänstekontrakt

 

Anvisning för utformning av nyttolast i tjänstekontrakt


Version 1.3
ARK_0061
2023-02-23

Innehållsförteckning

Revisionshistorik

Revision

Revisionsdatum

Beskrivning

Ändringarna gjorda av

Definitiv revision fastställd av

Revision

Revisionsdatum

Beskrivning

Ändringarna gjorda av

Definitiv revision fastställd av

1.0

2020-12-03

Revision 1.0 fastställd.

Thomas Siltberg, Arvid Thunholm, Lars Börjesson, Claudia Ehrentraut, Viktor Jernelöv

Tjänstekontraktsförvaltningen & Samverkansarkitektur

1.1

2021-12-03

Uppdaterat skrivningar i tillämpning av CVType då multiplicitet av element i datatypen har förändrats.

Lagt till avsnittet “Behov av olika “strikta CVType”.

Tobias Blomberg

 

1.2

2022-05-18

Lagt till informationsruta om vanligt tillämpade regler för elementen i CVType.

Tobias Blomberg

 

1.3

2023-02-23

Gjort förtydliganden gällande statisk och dynamisk kodverksanvändning.

Tobias Blomberg

 

1.4

2023-10-17

Lagt till avsnittet “När kodverk inte kan pekas ut”.

Tobias Blomberg

 

Referenser

Referens-id

Namn

Länk

Referens-id

Namn

Länk

R1

De facto-konventioner för datatyper (defacto-sidan)

https://bitbucket.org/rivta-domains/best-practice/wiki/De%20facto-konventioner%20f%C3%B6r%20datatyper.md

R2

Kodverkslistan

https://inera.atlassian.net/wiki/spaces/KINT/pages/3615655

R3

Lista över identifierare

https://inera.atlassian.net/wiki/spaces/KINT/pages/468746902

R4

Process för att skapa eller uppdatera kodverk

R5

RIV Tekniska Anvisningar

R6

VI-boken

Inledning

När nya tjänstekontrakt/domäner tas fram ska anvisningar som styr såväl den tekniska som informatiska utformningen följas. Anvisningar finns i form av RIV Tekniska Anvisningar [R5], VI-boken [R6], listor över kodverk och identifierare [R2, R3] samt De facto-konventioner för datatyper [R1].

Denna anvisning utgör ett stöd för de personer som arbetar med att beskriva innehållet i tjänstekontrakt, framförallt genom informationsspecifikationer och tjänstekontraktsbeskrivningar. Anvisningen omfattar i dagsläget information om hur vissa datatyper ska tillämpas.

Hur avsteg från det som beskrivs i anvisningarna, respektive detta dokument hanteras beskrivs under Gör avsteg.

Sätt datatyp

I befintliga tjänstekontrakt (XML-scheman) används ett antal datatyper (komplexa typer) som är gemensamma inom en domän eller för flera domäner. Dessa beskrivs på defacto-sidan [R1].

Följ nedanstående steg för att bestämma om en gemensam datatyp kan användas för ett attribut inom det tjänstekontrakt som du arbetar med:

  • bekanta dig med de datatyper som finns på defacto-sidan [R1]

  • avgör om någon eller några av de befintliga defacto-datatyperna som anges kan tillämpas för attributet i frågan

    • om någon eller några av de befintliga defacto-datatyperna kan användas, så ska de, i möjligaste mån, tillämpas i det formatet/den strukturen som är specat på defacto-sidan [R1]. OBS! Om avsteg ska göras från hur datatypen är utformad ska det hanteras enligt beskrivning under Gör avsteg.

    • om inga av de befintliga defacto-datatyperna kan användas för attributet i frågan är det tillåtet att använda sig av andra etablerade datatyper eller skapa egna komplexa typer. Kontakta förvaltare av defacto-datatyperna om du ser behov av att någon av dessa datatyper kan vara relevanta för andra tjänstekontrakt och därmed bör ingå i defacto-datatyperna.

Generella regler för tillämpning av datatyper

Vid tillämpning av en datatyp ska alla attribut som ingår i datatypen listas i fältregeltabellen i TKB:n, där nedanstående hantering för attributen gäller:

  • attributens namn och datatyp får inte ändras

  • attributens befintliga beskrivningar ska anges i TKB men får konkretiseras ytterligare om tillämpningen kräver det

  • attributen som är icke-obligatoriska, t.ex codeSystemName, codeSystemVersion, displayName samt originalText för CVType eller extension för IIType, får ändras till att vara obligatoriska om tillämpningen kräver det. Multipliciteten sätts då till 1..1. OBS! Om schematron eller andra sätt att validera används behöver de uppdateras.

Reglerna som beskrivs för datatyps-attributen under tabellen på defacto-sidan [R1] ska gälla vid tillämpningen. Schemat som finns för respektive datatyp på defacto-sidan [R1] ska användas.

Tillämpning av CVType

Datatypen CVType ska användas för att skicka kodade värden. Beskrivningen av datatypen och dess schema finns på defacto-sidan [R1].

CVType är uppbyggd av ett antal frivilliga element. Här följer dock två vanligt tillämpade regler:

  1. Om ett av elementen code, codeSystem eller displayName anges ska även de andra två anges.

  2. Om elementet originalText anges ska inget annat värde i CVType anges.

Huruvida dessa regler ska tillämpas eller ej måste dock beslutas i utvecklingsprojektet för respektive tjänstekontrakt baserat på verksamhetens behov.

Vid tillämpningen av CVType ska Generella regler för tillämpning av datatyper samt nedanstående anvisningar om val av kodverk, typ av kodverksanvändning och urval följas.

Välj kodverk

När datatypen CVType används ska, i de allra flesta fall, ett kodverk, alternativt ett urval pekas ut. Detta omfattar de koder som ska skickas för attributet i frågan. I befintliga tjänstekontrakt används olika kodverk som finns sammanställt på kodverkslistan [R2].

Följ nedanstående steg för att bestämma om ett kodverk kan användas för ett attribut inom det tjänstekontrakt som du arbetar med:

  • bekanta dig med de kodverk som finns på kodverkslistan

  • avgör om något av de befintliga kodverken som listas kan tillämpas för attributet i frågan

    • om något av de befintliga kodverken kan användas, så ska den refereras till i enlighet med datatypens utformning.

    • om inget av de befintliga kodverken kan användas för attributet i frågan kan det vara aktuellt att

      • skapa eller uppdatera ett kodverk. I detta fall ska processen för att skapa eller uppdatera kodverk [R4] följas.

      • använda sig av ett annat etablerat kodverk. Kontakta kodverksförvaltningen för att utreda om kodverket ska tas med i kodverkslistan.

I dokumentationens referenslista ska alltid referens till kodverkslistan [R2] anges.

När kodverk inte kan pekas ut

I vissa fall är det omöjligt eller oönskat att binda ett kodverk eller urval till ett attribut i tjänstekontraktet, dvs peka ut ett specifikt kodverk eller urval som ska användas. Detta kan t.ex. vara fallet om behovet av kodverk anses kunna variera i olika tillämpningar av tjänstekontraktet. När information om vilket kodverk eller urval som ska användas utelämnas från attributsbeskrivningen i tjänstekontraktet bör istället en interaktionsöverenskommelse upprättas för den aktuella tillämpningen (se mall här). Alternativt kan information om aktuella kodverk pekas ut direkt av tjänstekonsumenten i dennes egen dokumentation. På så vis kan användare av tjänstekontraktet informeras om hur information ska specificeras vid en viss tillämpning. Om inget kodverk eller urval pekas ut och ingen interaktionsöverenskommelse finns måste konsumenter av tjänstekontraktet kunna hantera alla koder som skickas.

I tjänstekontraktsbeskrivningen: När inget kodverk eller urval pekas ut, lägg till detta i attributets beskrivningen:

Det finns inget kodverk eller urval utpekat för detta attribut.

Tjänstekonsumenten kan i sin egen dokumentation hänvisa till en interaktionsöverenskommelse för att specificera giltiga kodverk eller urval för detta attribut. Om ingen sådan hänvisning finns krävs att tjänstekonsumenten kan hantera alla producerade koder. Detta görs vanligen genom att presentera displayName i sin helhet.

Exempel

I tjänstekontraktet GetObservations finns ett attribut som beskriver vilken typ av observation som registreras. Eftersom tjänstekontraktet används i olika tillämpningar (t.ex. sammanhållen journalföring, informationsöverföring till kvalitetsregister etc.) har man gjort bedömningen att inget enstaka kodverk kan anges i beskrivningen för attributet.

Istället har man tagit fram kompletterande interaktionsöverenskommelser som beskriver vilket kodverk som ska användas i olika tillämpningar. GetObservations används för presentation av tillväxtdata i Nationell Patientöversikt och i den interaktionsöverenskommelsen anges att för detta fält används SNOMED-CT när man skickar information om observation av, t.ex. längd, se här.

Bestäm typ av kodverksanvändning

Efter att ha bestämt vilket kodverk som ska användas behöver det utredas om en specifik version av kodverket ska användas för attributet i frågan (statisk kodverksanvändning) eller om koderna som skickas snarare bör härstamma från den senaste versionen av kodverket (dynamisk kodverksanvändning). Nedan anges när respektive typ av kodverksanvändning kan vara aktuellt.

  • Dynamisk kodverksanvändning

    • lägg in codeSystem som fixed value i XML-schemat (behöver inte göras för urval)

    • varken kontroll av koder eller version med hjälp av schematron-validering anses vara tillämpbart i detta scenario.

  • Statisk kodverksanvändning

    • ange kodverkets version som ska användas i beskrivningen för attributet codeSystemVersion

    • lägg in codeSystem, codeSystemName (om den finns) och codeSystemVersion som fixed values i XML-schemat

Hantera urval med koder från ett eller flera kodverk

I vissa tillämpningar ska urval från ett eller flera kodverk hanteras. I dessa fall ska det anges i TKB:ns beskrivning för attributet vilket urval som används. För codeSystem skickas kodverkets identifierare, inte urvalets.

En mall för att skapa urval finns på kodverkslistan [R2].

Tillämpningsexempel

Exempel #1 - dynamisk kodverksanvändning

Nedan ges ett exempel på hur CVTypen kan tillämpas för attributet careContactCode när ett urval med koder från ett kodverk används. Exemplet illustrerar en dynamisk kodverksanvändning. Exemplet omfattar hur attributet ska beskrivas i TKB:n samt i XML-schemat.

Enligt Generella regler för tillämpning av datatyper ska, vid tillämpning av en datatyp alla attribut som ingår i datatypen listas i fältregeltabellen i TKB:n. Det är tillåtet att konkretisera attributens beskrivningar, vilket har gjorts i nedanstående exemplet i form av de gul-markerade texterna. Datatypens icke-obligatoriska attribut får ändras till att vara obligatoriska om tillämpningen kräver det, men detta har inte varit aktuellt i nedanstående exemplet.

Namn

Typ

Beskrivning

Multiplicitet

Namn

Typ

Beskrivning

Multiplicitet

../../careContactCode

CVType

Kod som anger på vilket sätt vård- och omsorgskontakten är planerad att ske, alternativt skedde. Medlemmar i 58181000052100 |urval kontaktsätt| från kodverket Snomed CT SEs ska användas, se referens [R1].

Urvalet kan komma att kompletteras över tid vilket medför att konsumenter av kontraktet behöver vara förberedda på att nya koder kan tillkomma utan att versionen på kontraktet uppdateras.

0..1

../../../code

string

Kod eller uttryck definierad enligt kodverket.

1..1

../../../codeSystem

string

Kodverket som definierar koden. OID:en för Snomed CT SE ska anges, dvs “1.2.752.116.2.1.1”

1..1

../../../codeSystemName

string

Kodverkets namn i klartext, dvs. “Snomed CT SE”.

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

Nedan presenteras hur tillhörande XML-schemat ska vara utformat.

<xs:complexType name="careContactCode"> <xs:complexContent> <xs:restriction base="CVType"> <xs:sequence> <xs:element name="code" type="xs:string" /> <xs:element name="codeSystem" type="xs:string" fixed="1.2.752.116.2.1.1" /> <xs:element name="codeSystemName" type="xs:string" fixed="Snomed CT SE" minOccurs="0" /> <xs:element name="codeSystemVersion" type="xs:string" minOccurs="0" /> <xs:element name="displayName" type="xs:string" minOccurs="0" /> <xs:element name="originalText" type="xs:string" minOccurs="0" /> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType>

 

Exempel #2 - statisk kodverksanvändning

Nedan ges ett exempel på hur CVTypen kan tillämpas för attributet careContactCode. Exemplet illustrerar en statisk kodverksanvändning. Exemplet omfattar hur attributet ska beskrivas i TKB:n samt i XML-schemat.

Enligt Generella regler för tillämpning av datatyper ska, vid tillämpning av en datatyp alla attribut som ingår i datatypen listas i fältregeltabellen i TKB:n. Det är tillåtet att konkretisera attributens beskrivningar, vilket har gjorts i nedanstående exemplet i form av de gul-markerade texterna. Datatypens icke-obligatoriska attribut får ändras till att vara obligatoriska om tillämpningen kräver det, vilket har gjorts för attributen code, codeSystem och displayName i nedanstående exemplet.

Namn

Dokument

Kommentar

Länk

Namn

Dokument

Kommentar

Länk

R1

Kodverkslista

Finns på Webben

Namn

Typ

Beskrivning

Multiplicitet

Namn

Typ

Beskrivning

Multiplicitet

../../careContactCode

CVType

Kod som anger på vilket sätt vård- och omsorgskontakten är planerad att ske, alternativt skedde. Kodverket “Kv vårdkontakttyp” ska användas, se referens [R1]. Det är koderna från version 2.0 som ska skickas.

0..1

../../../code

string

Kod eller uttryck definierad enligt kodverket.

1..1

../../../codeSystem

string

Kodverket som definierar koden. OID:en för Kv vårdkontakttyp ska anges, dvs “1.2.752.129.2.2.2.25”

1..1

../../../codeSystemName

string

Kodverkets namn i klartext, dvs. “Kv vårdkontakttyp”.

0..1

../../../codeSystemVersion

string

Versionsangivelse som har definierats specifikt för det givna kodverket, dvs “2.0”.

0..1

../../../displayName

string

Den läsbara representationen (klartext) av koden eller uttrycket som definierat av kodverket.

1..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

Nedan presenteras hur tillhörande XML-schemat ska vara utformat.

<xs:complexType name="careContactCode"> <xs:complexContent> <xs:restriction base="CVType"> <xs:sequence> <xs:element name="code" type="xs:string" /> <xs:element name="codeSystem" type="xs:string" fixed="1.2.752.129.2.2.2.25" /> <xs:element name="codeSystemName" type="xs:string" fixed="Kv vårdkontaktyp" minOccurs="0" /> <xs:element name="codeSystemVersion" type="xs:string" fixed="2.0" minOccurs="0" /> <xs:element name="displayName" type="xs:string" /> <xs:element name="originalText" type="xs:string" minOccurs="0" /> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType>

Exempel #3 - Behov av olika “strikta” CVType

Om det, inom ramen för ett tjänstekontrakt, anses nödvändigt att ha två varianter av CVType där det för den ena är obligatoriskt att ange code och codeSystem kan två varianter av CVType tas fram. Detta kan se ut som i exemplet nedan.

CVcne - Coded Value, coded no exception

CVcwe - Coded Value, coded with exceptions

<xs:complexType name="CVcneType"> <xs:sequence> <xs:element name="code" type="xs:string" /> <xs:element name="codeSystem" type="xs:string" /> <xs:element name="codeSystemName" type="xs:string" minOccurs="0" /> <xs:element name="codeSystemVersion" type="xs:string" minOccurs="0" /> <xs:element name="displayName" type="xs:string" minOccurs="0" /> <xs:element name="originalText" type="xs:string" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="CVcweType"> <xs:sequence> <xs:element name="code" type="xs:string" minOccurs="0" /> <xs:element name="codeSystem" type="xs:string" minOccurs="0" /> <xs:element name="codeSystemName" type="xs:string" minOccurs="0" /> <xs:element name="codeSystemVersion" type="xs:string" minOccurs="0" /> <xs:element name="displayName" type="xs:string" minOccurs="0" /> <xs:element name="originalText" type="xs:string" minOccurs="0" /> </xs:sequence> </xs:complexType>

 

Alternativ användning vid tillämpningen

Det är giltigt att använda CVTypen för att bara lagra den text som användaren matat in eller yttrade. I denna situation kommer originaltexten att existera utan kod. I en situation där koden tilldelas någon gång efter att texten matats in är originaltexten den text eller fras som använts som grund för att tilldela koden.

Tillämpning av IIType

Datatypen IIType ska användas för att skicka identifierare. Beskrivningen av datatypen och dess schema finns på defacto-sidan [R1]. Vid tillämpningen av IIType ska Generella regler för tillämpning av datatyper samt nedanstående anvisningar om val av identifierare följas. value

Välj identifierare

När datatypen IIType används behöver det väljas/pekas ut en identifierare. I befintliga tjänstekontrakt används olika identifierare som finns sammanställt på listan över identifierare [R3].

Följ nedanstående steg för att bestämma om en identifierare kan användas för ett attribut inom det tjänstekontrakt som du arbetar med:

  • bekanta dig med de identifierare som finns på på länkad sammanställning

  • avgör om någon av de befintliga identifierare som listas kan tillämpas för attributet i frågan

    • om någon av de befintliga identifierare kan användas, så ska den refereras till i enlighet med datatypens utformning.

    • om ingen av de befintliga identifierare kan användas för attributet i frågan kan det vara aktuellt att

      • använda sig av andra etablerat identifierare. Kontakta kodverksförvaltningen för att utreda om identifieraren ska tas med i sammanställningen.

I dokumentationens referenslista ska alltid referens till lista över identifierare [R3] anges.

Tillämpningsexempel

Nedan ges ett exempel på hur IIType kan tillämpas för attributet personId. Exemplet omfattar hur attributet ska beskrivas i TKB:n samt i XML-schemat.

Enligt Generella regler för tillämpning av datatyper ska, vid tillämpning av en datatyp alla attribut som ingår i datatypen listas i fältregeltabellen i TKB:n. Det är tillåtet att konkretisera attributens beskrivningar, vilket har gjorts i nedanstående exemplet i form av de gul-markerade texterna. Datatypens icke-obligatoriska attribut får ändras till att vara obligatoriska om tillämpningen kräver det, vilket har gjorts för attributet extension i nedanstående exemplet.

Namn

Dokument

Kommentar

Länk

Namn

Dokument

Kommentar

Länk

R1

Lista över identifierare

Finns på Webben

Namn

Typ

Beskrivning

Multiplicitet

Namn

Typ

Beskrivning

Multiplicitet

../../personId

IIType

Person- eller samordningsnummer.

1..1

../../../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. För personnummer ska OID ”1.2.752.129.2.1.3.1” anges, för samordningsnummer OID ”1.2.752.129.2.1.3.3”.

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. Personens faktiska personnummer eller samordningsnummer ska anges, t.ex. “191212121212”

1..1

Nedan presenteras hur tillhörande XML-schemat ska vara utformat.

Gör avsteg

Om avsteg görs från rådande anvisningar, resp. beskrivningar som finns i föreliggande dokumentet ska beslutet dokumenteras och motiveras i tjänstedomänens arkitekturella beslut (AB).