RIV Tekniska Anvisningar 2.1DomänschemaVersion 2.1.3 ARK_0006 2018-05-08 |
Utgåvehistorik
Utgåva | Revision Datum | Beskrivning | Ändringarna gjorda av | Definitiv revision fastställd av |
PA1 | 2011-06-27 | Dokumentet skapat | Marcus.krantz@callistaenterprise.se | |
A | 2011-10-19 | Fastställd revision | Arkitekturledningens tekniska expertgrupp, Center för eHälsa i samverkan | |
PB1 | 2011-12-14 | Uppdaterat dokumentet i och med byte av projektplats från Osor till Google code. Enbart ändringar under rubriken Referenser. | hans.thunberg@callistaenterprise.se | |
B | 2012-01-03 | Fastställd revision | Arkitekturledningens tekniska expertgrupp, Center för eHälsa i samverkan | |
C | 2013-06-19 | Ny revision efter CeHis nya processer | Arkitektur och regelverk, Center för eHälsa i samverkan | Arkitektur och regelverk, Center för eHälsa i samverkan |
2.1.1 | 2014-08-20 | Förtydligat regel #6 och flyttat XML-exempel till bilagor. | Mattias Nordvall, Inera | |
2.1.1 | 2014-09-26 | Lagt över i Inera mall och publiserat. | Lennart Eriksson, Inera | |
2.1.2 | 2015-12-17 | Uppdaterat länkar i referenstabell | Mattias Nordvall, Inera | |
2.1.3 | 2018-05-08 | Lagt till att även domänprefix kan ha olika värden, var förut hårt satt till "riv:" Förtydligat namnsättningsregler och struktur för domän resp interaktionsnivå Ändrat regel #4 från bör till skall | Björn Hedman, Inera | |
2.1.4 | 2019-11-20 | Förtydligat att domänprefix används för att signalera ansvarig domän men att ägandeskapet av en domän kan ändras utan att domänens namnrymd ändras. | Björn Hedman, inera |
Detta dokument beskriver regelverket RIV Tekniska Anvisningar Domänschema 2.1.
Denna anvisning riktar sig till dem som ska specificera XML-scheman för tjänstekontrakt i en nationell tjänstedomän. 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 [R2].
Syftet med denna anvisning är att beskriva designregler och namngivningsregler för de meddelandetyper som skall användas inom en tjänstedomän.
Detta dokument är publicerade under licensen Creative Commons CC-BY-SA (http://creativecommons.org/licenses/by-sa/2.5/se/). Det betyder att du fritt får kopiera, distribuera och skapa bearbetningar av anvisningarna, under förutsättning att upphovsmannen (Sveriges Kommuner och Landsting) anges (men inte på ett sätt som antyder att de godkänt eller rekommenderar din användning av verket).
Ref | Dokument | Beskrivning och ev. webbadress | Ansvarig |
[R1] | Beskrivning av ”Venetian Blind” | Dokumentet beskriver det designmönster som tillämpas för XML Schema design i denna anvisning. Webblänk till hemsidan: | Okänd. |
[R2] | Översikt RIV Tekniska Anvisningar | Bakgrund, motiv, krav samt de principer som ligger till grund för utvecklingen av denna anvisning. | Arkitekturledningens tekniska expertgrupp, SKL |
[R3] | W3C-rapport om utökningsbara XML-scheman | Beskriver problemställningar och strategier för design av meddelanden som ger bra stöd för versionshantering. Versioneringsstrategin som beskrivs i denna översikt och som tillämpas i RIV Teknisk Anvisning Tjänsteschema är baserad på strategi nr 2 i denna rapport. | W3C |
[R4] | WS-I Basic Profile | ”Defines the WS-I Basic Profile 1.1, consisting of a set of non-proprietary Web services specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability” | The Web Services Interoperability Organization och ISO |
"Venetian Blind" [R1] skall användas som designmönster för domänscheman. Designmönstret Venetian Blind innebär följande:
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 domänschema skall namnges enligt följande regel: ${tjänstedomän}_${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 domänschema 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 och tjänstescheman.
Exempel: itintegration_monitoring_1.0.xsd
Attributet targetNamespace på schema-elementet skall ha ett värde som definieras av följande regel: urn:${domänPrefix}:${tjänsteDomän}:${majorVersion}
Namngivningsregler för namespace är formulerade enligt följande uppställning:
Reglerna för namnsättning av domän finns mer utförligt beskrivna i dokumentet för domännamnsättning
Motiv:
Domänprefixet ska avspegla vilken organisation som ansvarar för support och utveckling av respektive domän.
Användningen av major-version i namnrymden är en av att följa fastslagen versioneringsstrategi [R3]. 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:
Nationell domän
urn:riv:itintegration:monitoring:1
Applikationsdomän
urn:riv-application:sob:apps:resident:1
Extern domän
urn:riv-lv.lv.reporting.pharmacovigilance
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>
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 [R3].
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>
För att skapa en ny minor-version av ett tjänsteschema, skall följande regler följas:
Motiv: Detta förfarande är en konsekvens av vald strategi för versionering [R3]. Se [R2] för ytterligare bakgrund.
Se även bilaga 1 och 2 för exempel på utökningar.
Domänscheman ska inte 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.
Detta är ett verkligt exempel från CRM-domänen där följande förändringar görs:
Ny minorversion: crm_scheduling_1.1.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:tns="urn:riv:crm:scheduling:1" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:m1="urn:riv:crm:scheduling:1.1"
targetNamespace="urn:riv:crm:scheduling:1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">
<xs:import namespace="urn:riv:crm:scheduling:1.1" schemaLocation="crm_scheduling_1.1_ext.xsd"/>
<xs:complexType name="SubjectOfCareType">
<xs:sequence>
<xs:element name="phone" type="xs:string" minOccurs="0"/>
<xs:element name="email" type="xs:string" minOccurs="0"/>
<xs:element name="address" type="xs:string" minOccurs="0"/>
<xs:element name="coaddress" type="xs:string" minOccurs="0"/> <xs:element ref="m1:firstName" minOccurs="0"/>
<xs:element ref="m1:middleName" minOccurs="0"/>
<xs:element ref="m1:lastName" 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: crm_scheduling_1.1_ext.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:tns="urn:riv:crm:scheduling:1.1" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:riv:crm:scheduling:1.1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">
<xs:element name="firstName" type="xs:string"/>
<xs:element name="middleName" type="xs:string"/>
<xs:element name="lastName" type="xs:string"/>
</xs:schema>
Vid nästa major-version görs följande förändringar:
Ny major-version: crm_scheduling_2.0.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:tns="urn:riv:crm:scheduling:2" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:riv:crm:scheduling:2" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">
<xs:complexType name="SubjectOfCareType">
<xs:sequence>
<xs:element name="phone" type="xs:string" minOccurs="0"/>
<xs:element name="email" type="xs:string" minOccurs="0"/>
<xs:element name="address" type="xs:string" minOccurs="0"/>
<xs:element name="coaddress" type="xs:string" minOccurs="0"/> <xs:element name="firstName" type=”xs:string” minOccurs="1"/>
<xs:element name="middleName" type=”xs:string” minOccurs="0"/>
<xs:element name="lastName" type=”xs:string” minOccurs="1"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Detta är ett fingerat exempel från CRM-domänen där följande tre nya element läggs till. Utökningen blir icke-bakåtkompatibel eftersom flera av elementen är obligatoriska (minoccurs=”1”). Om åtminstone det sista elementet är obligatoriskt så kan any-elementet behållas för framtida bruk.
Ny minorversion: crm_scheduling_1.1.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:tns="urn:riv:crm:scheduling:1" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:m1="urn:riv:crm:scheduling:1.1" targetNamespace="urn:riv:crm:scheduling:1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">
<xs:import namespace="urn:riv:crm:scheduling:1.1" schemaLocation="crm_scheduling_1.1_ext.xsd"/>
<xs:complexType name="SubjectOfCareType">
<xs:sequence>
<xs:element name="phone" type="xs:string" minOccurs="0"/>
<xs:element name="email" type="xs:string" minOccurs="0"/>
<xs:element name="address" type="xs:string" minOccurs="0"/>
<xs:element name="coaddress" type="xs:string" minOccurs="0"/> <xs:element ref="m1:firstName" minOccurs="1"/>
<xs:element ref="m1:middleName" minOccurs="0"/>
<xs:element ref="m1:lastName" minOccurs="1"/>
<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: crm_scheduling_1.1_ext.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:tns="urn:riv:crm:scheduling:1.1" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:riv:crm:scheduling:1.1" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.1">
<xs:element name="firstName" type="xs:string"/>
<xs:element name="middleName" type="xs:string"/>
<xs:element name="lastName" type="xs:string"/>
</xs:schema>
Vid nästa major-version integreras elementen från mellanliggande utökningsscheman i huvudschemat: crm_scheduling_2.0.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:tns="urn:riv:crm:scheduling:2" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:riv:crm:scheduling:2" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">
<xs:complexType name="SubjectOfCareType">
<xs:sequence>
<xs:element name="phone" type="xs:string" minOccurs="0"/>
<xs:element name="email" type="xs:string" minOccurs="0"/>
<xs:element name="address" type="xs:string" minOccurs="0"/>
<xs:element name="coaddress" type="xs:string" minOccurs="0"/> <xs:element name="firstName" type=”xs:string” minOccurs="1"/>
<xs:element name="middleName" type=”xs:string” minOccurs="0"/>
<xs:element name="lastName" type=”xs:string” minOccurs="1"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:schema>