Innehållsförteckning

Introduktion

Syfte och bakgrund

Profileringsanvisningen innehåller riktlinjer som ska användas av Inera vid utveckling av FHIR-profiler. Syftet är att standardisera utvecklingen av FHIR-profiler för Ineras produkter, men kan även användas av andra parter som vill standardisera sitt informationsutbyte.

Anvisningen är inte en steg-för-steg guide för hur man skapar profiler i FHIR generellt.

Profileringsanvisningar från andra länder (Finlands profileringsanvisning, Nederländernas profileringsanvisning, Norges profileringsanvisning, Storbritanniens profileringsanvisning) och organisationer (Firelys profileringsanvisning) har tjänat som underlag för framtagning av denna anvisning.

Målgrupp

Målgruppen för profileringsanvisningen är informationsarkitekter, lösningsarkitekter och utvecklare som ska ta fram en FHIR-profil.

Målgruppen förväntas ha grundläggande kunskaper inom interoperabilitetsstandarden HL7 FHIR (nedan refererat till som FHIR) och vara bekanta med FHIR:s profileringsriktlinjer och metodik. Denna anvisning kompletterar och förtydligar de internationella riktlinjerna inom vissa områden.

Praktiska riktlinjer

Nedan listas praktiska riktlinjer som ska följas när FHIR-profiler skapas på Inera, respektive kan följas av andra aktörer som vill skapa FHIR-profiler.

Återanvänd existerande arbete

Börja alltid med att inventera tidigare nationella och internationella arbeten, både när du skapar en profil eller extension. Du kan använda någon av följande källor för att göra det:

• FHIR Package Registry

• Simplifier - FHIR collaboration platform

För profilering i Sverige ska basprofilerna från HL7 Sverige användas som grund.

Undvik att skapa extensions för sådant som FHIR redan stödjer, dvs. undersök om existerande attribut stödjer behovet utan att den semantiska betydelsen kompromissas.

Språk

Profiler och extensions bör dokumenteras på engelska. Detta gäller såväl namnsättning av nya attribut och element som beskrivningar och kommentarer. Anledningen är att de ska kunna användas av både svenska och internationella aktörer.

Namngivning

Innan du börjar bygga profiler, fastställ de namnkonventioner som du kommer att använda i ditt projekt, eftersom det kommer att bli mycket svårare att ändra dem senare. Några allmänna regler att följa finns nedan.

Profiler

• Använd namnet på din tjänst, din region eller annat sammanhang som prefix.

• Inkludera resurstypen i namnet på din profil.

• Format: [prefix][resursnamn]

• Använd PascalCase vid namngivning av profiler.

Exempel: RIVCareContact

Extensions

Definition av extension

• Använd ett läsvänligt och självförklarande namn.

• Format: [prefix][namn på extension]Extension

• Använd PascalCase för definition av extensions.

Exempel: RIVMiddleNameExtension

Användning av extension i profiler

• Använd ett läsvänligt namn utan prefix och utan suffixet extension.

• Format: [namn på extension]

• Använd camelCase för namngivning av extensions då de används i profiler.

Exempel: middleName

Slices

• Använd ett läsvänligt och självförklarande namn.

• Format: [namn på slice]

• Använd camelCase för namngivning av slices.

Exempel: nationelltReservnummer

Sökparametrar

• Sökparameterna ska i möjligaste mån matcha det element eller attribut i profilen som ligger närmast sökparametern.

• Prefix ska anges för sökparametrar för att understryka att det är en profilering: prefix-sökparameter.

• Format: [prefix]-[namn på sökparameter]

• Använd kebab-case för sökparametrar.

Exempel: riv-middle-name

Krav på metadata

Förutom de obligatoriska elementen som definieras i StructureDefinition ska nedanstående inkluderas vid definition av profiler, extensions, ValueSet- och CodeSystem-resurser.

För extensions ska även metadataelementet purpose inkluderas och innehålla en beskrivning på varför man har skapat denna extension.

Öppen eller sluten modellering

Beroende på profilens tänkta användningsområden bör du överväga en öppen eller en sluten modellering.

En öppen profil är mer generisk och har få begränsningar och kan lättare återanvändas, medan en sluten profil är mer specifik och har fler begränsningar men underlättar vid implementation. Nedanstående tabell listar för- och nackdelar med öppen och sluten modellering. Dessa är direktöversatta 1:1 från Nederländernas profileringsanvisning.

I de fall profiler tas fram för att stödja hela domäner och där tanken är att mer specifika profiler ska tas fram utifrån dessa är det alltså lämpligt att överväga en öppen modellering.

Vid valet av en öppen eller sluten modelleringsmodell bör även användandet av flaggan mustSupport respektive kardinaliteten 0..0 övervägas. Genom att ange kardinalitet 0..0 kan man utestänga viss information t.ex. i syftet uppgiftsminimering genom att förbjuda producenter att skicka denna. Profilen blir således mer stängd och svårare att implementera på en generell nivå. Genom att använda flaggan mustSupport kan man istället explicit uttrycka vilka element som konsumenten förväntas kunna stödja samtidigt som man inte stänger profilen för andra producenter. Notera dock att meningen av mustSupport inte är definierad av FHIR:s grundspecifikation, utan behöver definieras för respektive profil i metadatalement. MustSupport bör endast definieras i profiler och inte i extensions, då det inte är säkert att denna extension “måste stödjas” i alla användningsfall den ska användas i.

Terminologibindning

CodeSystem

Då nationella kodverk ska användas i profiler så ska motsvarande CodeSystem-resurs definieras i FHIR och göras tillgänglig för återanvändning av andra tjänster. Om möjligt ska resursen publiceras i en öppen FHIR terminologitjänst. Den förvaltning som äger kodverket ska också ansvara för förvaltningen av FHIR-resursen.

ValueSet

Alla kodade element i FHIR-profiler ska knytas till ett ValueSet med hjälp av ElementDefinition.binding.valueset.

Då man binder ett ValueSet hårt till ett kodsystem ska detta uttryckas genom att Coding.system sätts till “fixed”.

Datatyper

Kodade värden

Då värden kodas med hjälp av datatypen Coding ska elementen Coding.code och Coding.system sättas till obligatorisk: 1..1

Mätvärden

När datatypen Quantity används för att uttrycka mätvärden ska Quantity.value och Quantity.unit vara obligatoriskt, 1..1. Enheter ska anges enligt UCUM.

Identifierare

När datatypen Identifier används ska Identifier.system vara obligatoriskt, 1..1. Om det finns behov av att används en OID som namespace ska denna konverteras om till en URI.

Slicing

Följande sektion beskriver riktlinjer kring slicing och är tagen från Nederländernas profileringsanvisning.

Att välja diskriminator

Diskriminator bör väljas utifrån den mest specifika definitionen av slicen som möjligt samtidigt som man måste beakta prestandakostnaden i att välja en diskriminator som blir svår för en validerare att utvärdera. Använd mönster istället för en kombination av fasta värden för att hålla logiken enkel. Till exempel när slicing ska ske på datatypen Coding/CodeableCocept: använd ett mönstersegment om koden och systemet för en slice är fixerade. Om en slices urskiljs av olika CodeSystems är en diskriminator baserad på ett fast system att föredra framför en bindning till ett ValueSet. Använd det senare om flera CodeSystems kan användas inom en definierad slice. Undvik diskriminatortypen 'profil' eftersom denna är svår att utvärdera för en validerare.

Använd inte nästlad slicing

Nästlad slicing innebär att man lägger till en slice inom en slice. Detta fungerar inte så bra i FHIR - till exempel kan varken Java eller .Net validatorn hantera detta (för tillfället) - så undvik denna mekanism. Som ett alternativ kan du använda en diskriminator baserad på mönster/kod, och på varje slice.code kan du lägga till ett patternCodeableConcept med önskat system och värde. Detta har samma effekt; minst en kod från angivet system krävs, men andra kan läggas till.

Exemplifiera

Varje profil som tas fram ska ha en exempelresurs publicerad i JSON-format där alla obligatoriska data är populerade.

Publicering

Profiler, extensions, CodeSystem- och ValueSet-resurser ska dokumenteras och publiceras i sitt sammanhang i implementationsguider. Detta för att förbättra möjligheterna till samarbete och återanvändning av befintligt arbete.

Implementationsguiden ska uttrycka ett syftesspecifikt område för informationsdelning, alternativt kan den uttrycka en gemensam domän för återanvändning.

Implementationsguider som Inera tar fram ska publiceras öppet på http://inera.se/fhir/ig/[namn på implementationsguide].

URL för publicering

FHIR-resurser som tas fram inom profileringsarbete behöver ha en kanonisk URL. Den kanoniska URL:en bör leda till resursernas definition, men det är inte tvingande inom standarden. URL:en används främst för att identifiera resurserna och inte för publicering.

För resurser som tas fram av Inera ska definitionen av resursen kunna hämtas via den kanoniska URL:en.

Profiler och extensions som tas fram av Inera ska ha följande URL-struktur:

• http://[domän]/fhir/ig/[ig]/StructureDefinition/[namn]

Där

• [domän] = http://inera.se

• [ig] = Namn på implementationsguide, t.ex. tidbok

• [namn] = Namn på profil/extension, t.ex. RIVCareContact

Exempel på URL: http://inera.se/fhir/ig/tidbok/StructureDefinition/RIVCareContact

För andra organisationer ska samma struktur användas men domänen då bytas mot den egna.

CodeSystem-resurser som tas fram av Inera ska ha följande URL-struktur:

• http://[domän]/fhir/ig/[ig]/CodeSystem/[name]

ValueSet-resurser som tas fram av Inera ska ha följande URL-struktur:

• http://[domän]/fhir/ig/[ig]/ValueSet/[name]

Serialisering

Profiler, extensions, ValueSet- och CodeSystem-resurser ska stödja serialisering åtminstone i JSON format.