Anvisning för utformning av nyttolast i tjänstekontrakt

Version 1.1
ARK_0061
2021-12-03

Innehållsförteckning

Revisionshistorik

Referenser

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

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.

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.

• Statisk kodverksanvändning

  • främst aktuellt när det ska byggas logik på koderna som skickas, på producent-, resp. konsumentsidan. T.ex. statuskoder.

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

  • om ett begränsat antal koder ingår i kodverket, lägg till dessa som enumerations i XML-schemat

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

• Dynamisk kodverksanvändning

  • främst aktuellt för kodverk som uppdateras regelbundet, som t.ex. Snomed och ICD-10 och där koderna från den senaste versionen av kodverket ska visas upp på konsumentsidan.

  • i beskrivningen för attributet som är av typ CVType, ange efterföljande information: “Kodverket 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.” alt för urval “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.”

  • lägg in codeSystem som fixed value i XML-schemat (behöver inte göras för urval som hanterar koder från flera kodverk)

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

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 ska det skickas kodverkets identifierare, inte urvalets. När ett urval innehåller koder från två eller flera kodverk ska detta tydliggöras i beskrivningen genom att ange följande: “Urvalet innehåller koder från flera kodverk. Under codeSystem ska det anges identifieraren för det kodverket som koden som skickas tillhör. Detta medför att det kan skickas olika identifierare under codeSystem, beroende på vilket kodverk den skickade koden tillhör.“

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

Tillämpningsexempel

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

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

Exempel #2 - 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.

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

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

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.

I vissa fall kan det vara omöjligt eller oönskat att binda ett kodverk eller urval till ett attribut i tjänstekontraktet, t.ex. eftersom kodverket anses kunna variera i olika tillämpningar. Det är då tillåtet att lämna information om kodverket tomt.

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.

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