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

Image Added

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 Översikt RIV Tekniska Anvisningar 2.1 [R2]

...

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

...

Schema-filen för ett tjänstekontrat bör namnges enligt följande regel: ${tjänsteInteraktion}${roll}_${m.n}.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, se [R8].

Exempel: MakeBookingResponder_1.0.xsd

...

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

Motiv: Användningen av major-version i namnrymden är en av att följa fastslagen versioneringsstrategi [R9]. 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 [R4] regel om ”operation signature”. Det också generellt goda förutsättningar för att implementera generella bryggor och tjänsteväxlar

Exempel: urn:riv:crm:scheduling:MakeBookingResponder:1

...

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”

...

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”

...

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

Exempel: Tjänstekontrakten för exempelapplikationerna [R5]

...

Schema-attributet version bör 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>

...

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

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

Exempel:

<xs:complexType name="SomeType">

<xs:sequence>

<xs:element name="someElement" type="xsd:string" />

<xs:element name="someOtherElement" type="xsd:int" />

<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded" namespace="##other"/>

</xs:sequence>

</xs:complexType>

Regel #9, nya element i utökningsschema

...

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:

<xs:simpleType name=”Å”>

<xs:annotation>

<xs:documentation>…</xs:documentation>

</xs:annotation>

<xs:restriction base=”xs:string”>

<xs:enumeration value=”Återställas helt” />

<xs:enumeration value=”Återställas delvis” />

<xs:enumeration value=”Det går inte att bedöma” />

</xs:restriction>

</xs:simpleType>

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.

...

Ett tjänstekontrakt ska inte definiera några egna fel (SOAP-exceptions). Istället bör följande struktur för felhantering tillämpas i svarsmeddelandet (för fråga-svar):

<xs:complexType name="MakeBookingResponseType">

<xs:sequence>

<xs:element name="bookingId" type="core:BookingIdType" minOccurs="0" maxOccurs="1" />

<xs:element name="resultCode" type="tns:ResultCodeEnum" minOccurs="1" maxOccurs="1" />

<xs:element name="resultText" type="xs:string" minOccurs="0" maxOccurs="1" />

<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence>

</xs:complexType>

<xs:simpleType name="ResultCodeEnum">

<xs:restriction base="xs:string">

<xs:enumeration value="OK"/>

<xs:enumeration value="ERROR"/>

<xs:enumeration value="INFO"/>

</xs:restriction>

</xs:simpleType>

Vid ett tekniskt fel levereras ett generellt undantag (SOAP-Exception). Exempel på felsituationer som rapporteras som tekniskt fel kan vara deadlock i databasen eller följdeffekter av programmeringsfel. Denna information bör loggas av tjänstekonsumenten. Informationen är inte riktad till användaren. Användaren kommer enbart att se ”tekniskt fel – inte detaljinformation. Den riktar sig till systemförvaltaren.

...

Motiv: Erfarenheter har visat att felhantering genom egen-definierade fel skapar interoperabilitetsproblem och försvårar hantering i intermediärer.

Exempel: Se tjänsteschemat i referensapplikationen.

...

Tjänsteschema, ny minorversion: GetAvailableTimeslotsResponder_1.1.xsd

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1" xmlns:m1="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">

<xs:import namespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" schemaLocation="GetAvailableTimeslotsResponder_1.1_ext.xsd" />

<xs:element name="GetAvailableTimeslots" type="tns:GetAvailableTimeslotsType" />

<xs:complexType name="GetAvailableTimeslotsType">

<xs:sequence>

<xs:element name="healthcare_facility" type="core:HsaIdType" minOccurs="1" maxOccurs="1" />

<xs:element name="bookingId" type="core:BookingIdType" minOccurs="0" maxOccurs="1" />

<xs:element name="startDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />

<xs:element name="endDateInclusive" type="core:DT" minOccurs="1" maxOccurs="1" />

<xs:element name="performer" type="core:HsaIdType" minOccurs="0" maxOccurs="unbounded" />

<xs:element name="timeTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />

<xs:element name="timeTypeID" type="core:TimeTypeIDType" minOccurs="0" maxOccurs="1" />

<xs:element name="careTypeName" type="xs:string" maxOccurs="1" minOccurs="0" />

<xs:element name="careTypeID" type="core:CareTypeIDType" minOccurs="0" maxOccurs="1" />

<xs:element ref="m1:subject_of_care" minOccurs="0"/>

<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>

</xs:sequence>

</xs:complexType>

</xs:schema>

Utökningsschema med element som tillkommit i 1.1: GetAvailableTimeslotsResponder _1.1_ext.xsd

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:1.1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">

<xs:element name="subject_of_care" type="core:SubjectOfCareIdType"/>

</xs:schema>

Vid nästa major-version integreras elementen från mellanliggande utökningsscheman i huvudschemat. Elementen kan nu göras obligatoriska (minOccurs=”1”) om så önskas.

Tjänsteschema, ny majorversion GetAvailableTimeslotsResponder _2.0.xsd

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:riv:crm:scheduling:1" xmlns:tns="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:2" targetNamespace="urn:riv:crm:scheduling:GetAvailableTimeslotsResponder:2" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">