Open	RIV Tekniska Anvisningar Tjänsteschema   Version 2.2 ARK_0005 2024-09-18

Innehållsförteckning

1 Inledning

Detta dokument beskriver regelverket RIV Tekniska Anvisningar Tjänsteschema 2.0.

Open

Anvisningen i sitt sammanhang

1.1 Målgrupp

Denna anvisning riktar sig till dem som ska specificera XML-scheman för tjänstekontrakt i en nationell tjänsteinteraktion. Anvisningen innehåller endast regeluppsättningen. För bakgrund, motiv, krav samt de principer som ligger till grund för framtagning av reglerna hänvisas till RIV Tekniska Anvisningar - Översikt 2.0

1.2 Syfte

Syftet med denna anvisning är att beskriva designregler och namngivningsregler för interoperabilitet samt riktlinjer för att bygga in stöd för versionshantering i tjänstescheman.

Ett uttalat syfte med tjänstescheman är att de ska kunna användas oberoende av kommunikationsstandard. Många tjänstescheman kommer dock att skapas i syfte att importeras i WSDL-filer. Reglerna för tjänstescheman är därför baserade på WS-Basic Profiles regelverk för WS-I Basic Profile - Version 1.1. Målet med anvisningen är att optimera för interoperabilitet vid användning av web-service-baserade RIV TA-profiler utan att göra tjänstescheman beroende av web-services för transport och kuvertering

1.3 Tillgänglighet

Detta dokument är publicerat under licensen Creative Commons CC-BY-SA (Sammanfattning - Erkännande-DelaLika 2.5 - Creative Commons ).

Det betyder att du fritt får kopiera, distribuera och skapa bearbetningar av anvisningarna under förutsättning att upphovsmannen Sveriges Kommuner och Regioner anges, men inte på ett sätt som antyder att de godkänt eller rekommenderar din användning av verket.

2. Beskrivning av namnregler

Namngivningsregler i detta dokument är formulerade enligt följande uppställning:

1. Tjänstedomänens prefix: ${domänPrefix}, t ex riv eller riv-application

2. Tjänstedomänens namn: ${tjänsteDomän}, t ex clinicalprocess:activity:request

3. Tjänsteinteraktionens namn: ${tjänsteInteraktion}, t ex GetRequest

4. Tjänsteinteraktionsroll: ${roll} = Initiator eller Responder, motsvarande tjänsteinteraktionsroller initiativtagare och utförare

5. Tjänsteinteraktionens version:
   m.n = förkortning av ${majorVersion}.${minorVersion}
   m = förkortning av ${majorVersion}

6. Operationens namn: ${operation}, t ex MakeBooking

3. Detaljerade regler

Regel #1, designmönster för tjänstescheman

"Venetian Blind” http://www.xfront.com/GlobalVersusLocal.html skall användas som designmönster för tjänstescheman. Designmönstret Venetian Blind innebär följande:

• Den interna strukturen i ett meddelande byggs upp med hjälp av globalt deklarerade typer. Med ”globalt deklarerade” menas deklarationer som görs direkt under schema-elementet.

• Endast rotelementet är deklarerat som ett globalt element. I web-service-fallet innebär det att request- och response-elementen är globalt deklarerade element medan resten är typer.

Anm. I vissa fall kan även andra element än request och response behöva vara globala, t ex används element-referenser till globala element i importerade scheman för att stödja versioneringsstrategin, se nedan.

Motiv: Interoperabilitet, WS-I Basic Profile

Regel #2, namn på xsd-filen

Schema-filen för ett tjänstekontrat bör namnges enligt följande regel: ${tjänsteInteraktion}${roll}_${m.n}.xsd

Observera utökningsscheman namnsätts enligt ${tjänsteInteraktion}${roll}_${m.n}_ext.xsd

Motiv: Att ha med versionsnummer i namnet på källkodsfiler är generellt sett något man försöker undvika då det försvårar användning av versionshanteringsverktyg (t ex Subversion, Microsoft Visual Studio). I fallet med tjänsteschema behöver man dock kunna hantera flera olika versioner samtidigt (i byggsystem mm) och för att underlätta den hanteringen ingår versionsnumret i filnamnet på tjänstekontrakt.

Anm. Detta gäller principiellt sett också de XML Schema som importeras/inkluderas av att tjänsteschema och som beskriver RIV Meddelanden men denna anvisning täcker inte in utformning av dessa XML Scheman.

Exempel: MakeBookingResponder_1.0.xsd

Version i filnamnet: Versionen i filnamnet ska återspegla interaktionens logiska version och räknas alltså bara upp om strukturen för interaktionen förändras, övriga förändringar som sker rent tekniskt i filen påverkar inte versionen.

Om ett gemensamt schema har förändrats och bytt version och därigenom filnamn så behöver importen av detta i interaktionsschemat uppdateras men om inga objekt i interaktionen påverkas så behöver inte interaktionens version lyftas

Se även Bilaga1 "Exempel på utökning av tjänsteschema"

Regel #3, namn på target namespace

Attributet targetNamespace på schema-elementet för en tjänsteinteraktion skall ha ett värde som definieras av följande regel: urn:${domänPrefix}:${tjänsteDomän}:${tjänsteInteraktion}${roll}:${m}

(Reglerna för namnsättning av domänprefix och tjänstedomän finns mer utförligt beskrivna i dokumentet Domännamnsättning

Motiv:

Användningen av major-version i namnrymden är en av att följa fastslagen versioneringsstrategi se W3C Extending and Versioning Languages: XML Languages . Att ha en unik namnrymd per tjänstekontrakt (tjänsteinteraktion + roll) är en förutsättning för att följa WS-I Basic Profiles Basic Profile - Version 1.1 regel om ”operation signature”. Det också generellt goda förutsättningar för att implementera generella bryggor och tjänsteväxlar

Exempel:

Nationell domän

urn:riv:crm:scheduling:MakeBookingResponder:1

Regel #4, namn på element

Attributet ”name” på element som deklarerar request-element i tjänsteschemat skall ha ett värde som följer följande regel: ${operation}, t ex: MakeBooking

Attributet ”name” på element som deklarerar response-element i tjänsteschemat skall ha ett värde som följer följande regel ${operation}Response, t ex: MakeBookingResponse

Motiv: För konsistent namngivning skall element för in-parametrar ha samma namn som operationen.

Exempel: ”MakeBooking” respektive “MakeBookingResponse”

Regel #5, namn på typer

Attributet ”name” på element som deklarerar request-typer i tjänsteschemat bör ha ett värde som följer följande regel: ${operation}Type

Attributet ”name” på element som deklarerar response-typer i tjänsteschemat skall ha ett värde som följer följande regel: ${operation}ResponseType

Motiv: Enhetlighet.

Exempel: ” MakeBookingType” respektive  ” MakeBookingResponseType”

Regel #6, användning av schema-attributen elementFormDefault och attributeFormDefault

Schema-attributen elementFormDefault och attributeFormDefault skall sättas till "qualified" respektive "unqualified".

Motiv: För att versioneringsstrategin skall fungera är det viktigt att alla element i instans-dokument är namespace-qualified. Detta uppnås genom att sätta schema-attributet elementFormDefault till "qualified".

Regel #7, användning av schema-attributet version

Schema-attributet version skall sättas till "m.n"

Motiv: Då namnrymden inte innehåller minor-version, ger detta en dokumentation som följer intentionen med attributet.

Exempel: <schema ... version="1.0>

Regel #8, användning av any-element för utökningsbarhet

För att uppnå framåtkompatibilitet skall ett xsd:any element läggas in sist i alla komplexa typer som ska kunna utökas.

Motiv: För att uppnå framåtkompatibilitet måste man "förbereda" sina XML scheman för framtida utökningsbarhet. Detta är en del av den tillämpade strategin för versionering.

Exempel:

Regel #9, nya element i utökningsschema

För att lägga till nya element och skapa en ny minor-version av ett tjänsteschema, skall följande regler följas:

• Det nya elementet läggs till i befintligt schema närmast före any-elementet i den komplexa typ som ska utökas. Detta nya element har ingen typ, utan refererar (xsd:ref=”…”) element som är rotelement i en ny schema-fil (utöknings-schema)

  • Exempel  <xs:element ref="m1:financingOrganization" minOccurs="0" maxOccurs="unbounded" />

• För att ändringen ska vara bakåtkompatibel så måste det nya elementet ha attributet minoccurs=”0”. Det leder i sin tur att any-elementet måste tas bort. Detta för att uppfylla kravet på Unique Particle Attribution i Xml Schema 1.0. Följden blir att denna komplexa typ inte kan förändras fler gånger på ett bakåtkompatibelt sätt.

• Det nya elementet definieras i en ny schema-fil (utökningsschema) med ett namn som följer följande regel: ${tjänsteInteraktion}${roll}_${m.n}_ext.xsd

• Utökningsschemat ska ha en targetNamespace enligt följande regel: urn:$(domänPrefix):${tjänsteDomän}:${tjänsteInteraktion}${roll}:${m.n}

• Tjänsteschemat importerar (xsd:import) utöknings-schemat som ges namnrymdsalias enligt följande regel: m${n} 

  • Exempel: xmlns:m1='urn:riv:infrastructure:directory:organization:GetUnitResponder:2.2'

• Tjänsteschemats versionsattribut ändras till den nya minor-versionen.

• I nästa major-version av tjänsteschemat flyttas element-deklarationerna in från alla utökningsscheman (det finns ett för varje minor-version som tilkommit sedan förra major-versionen skapades). Dessutom läggs eventuellt borttagna any-element tillbaka, enligt regel #8.

Motiv: Detta förfarande är en konsekvens av vald strategi för versionering.

Se även Bilaga1 "Exempel på utökning av tjänsteschema"

Regel #10 Nationella tecken

Tjänstescheman ska undvika att använda nationella tecken i såväl elementnamn, attributnamn som vid listning av värdemämngder för uppräkningstyper. Följande exempel bör därför undvikas:

Motiv: För att undvika interoperabilitetsproblem bör man ej använda sig av nationella tecken när man definierar typer som kommer att användas i ett tjänstekontrakt. Ofta uppstår annars fel vid kodgenerering från schemat.

Regel #11, Felhantering och återrapportering

För logiska fel och återrapportering av status kan svar inkludera elementen resultCode och resultText. ResultCode kan endast ha värdena OK, INFO eller ERROR enligt följande:

Logiska fel

Ett logisk fel är en situation där behandlingen kan ha resulterat i ett, ur slutanvändarens perspektiv, oväntat utfall. För att klassas som ett logiskt fel måste tjänstebegäran utformats enligt överenskommelse (korrekt enligt XML-schema och tjänstekontraktsbeskrivning) och tjänsteproducentens behandling har inte misslyckats på grund av ett tekniskt fel hos vare sig tjänstekonsument eller tjänsteproducent enligt definitionen ovan. 

För återrapportering av logiska fel ska svaret innehålla ett element “resultCode” med värde ERROR och en textuell felbeskrivning av felet i element “resultText”.

ResultText skall loggas och kan visas upp för användaren i de fall då det är tillämpbart.

Exempel:

Återrapportering

Inget att rapportera

Om man inte har något speciellt att rapportera kring behandling av en tjänstebegäran kan man i svaret ändå inkludera elementet “resultCode” med värde OK och utelämna elementet “resultText”.

Exempel:

Meddelande till systemförvaltare

Om man efter lyckad behandling av en tjänstebegäran vill återrapportera information från behandlingen eller beskrivande text för returnerad data ska man i svaret inkludera elementet “resultCode” med värde OK och elementet “resultText” innehållande den text som ska loggas men inte visas för användaren.

Exempel:

Meddelande till användare

Om man efter lyckad behandling av en tjänstebegäran vill återrapportera ett meddelande, som tjänstekonsumenten kan välja att visa upp för en användare, ska man i svaret inkludera elementet “resultCode” med värde INFO och elementet “resultText” innehållande meddelandet som ska visas upp.

Exempel: