Rapport SuwiML berichtstandaard Auteur: Paul Vriend, Dirk Temme Datum document: 03-11-2005 Versie: v0201 Status: Datum afdruk: donderdag 3 november 2005 SuwiML berichtstandaard v0201.doc - 1 van 103
Documenthistorie Datum en versienummer Auteur Opmerking 0.1, 18/09/2001, Draft v0100, 20/12/2001, Definitief Astrid Hackenberg Arjan Loeffen v0200, 21/07/2005, Definitief Paul Vriend Volledige revisie, aanpassing en uitbreiding n.a.v. toetsing in de praktijk. V0201, 03-11-2005 Dirk Temme Blz 35: NB verwijderd voor optionele velden met waarde Onbekend ; In de voorbeelden het gebruik van ElementFormDefault aangepast; Goedkeuring Datum Naam Functie v0100, 20/12/2001 Domeingroep Gegevens en Vertegenwoordiging Suwi keten. Berichten (DGB). v0201,??/??/2005 Domeingroep Gegevens en Berichten (DGB). Vertegenwoordiging Suwi keten. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 2 van 103
Inhoudsopgave 1. Inleiding 7 1.1. Doel 7 1.2. Leeswijzer 7 2. SuwiML berichtstandaard 8 2.1. Inleiding 8 2.2. SuwiML berichtidentificatie 10 2.3. Validatie 12 3. SuwiML basisschema 13 3.1. Inleiding 13 3.2. Gegevenstypen 13 3.3. Entiteiten 16 3.4. Hiërarchie 17 3.5. Automatisch tabellenbeheer 19 3.6. Versienummering 21 4. SuwiML berichtschema 24 4.1. Inleiding 24 4.2. SuwiML body 24 Structuur 24 Voorbeelden 31 Lege velden / waarden in een SuwiML bericht 35 Afleiden berichtschema uit basisschema 35 Soorten relaties 37 Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 3 van 103
Voorbeeld 41 4.3. Warning binnen SuwiML body 44 4.4. Clusters binnen SuwiML body 45 4.5. Beknopte samenvatting modellering SuwiML berichtschema 47 5. SuwiML berichtontwikkelingsmethodiek 49 5.1. Inleiding 49 5.2. Internationale ontwikkelingen mbt standaardisatie en berichtontwikkeling 49 UN/CEFACT Modelling Methodology 49 W3C 50 ISO 17113 50 ISO 11179 51 ebxml 51 Aanbevelingen met betrekking tot het berichtontwikkelingsproces 51 5.3. Het berichtontwikkelingsproces 52 Analyse, ontwerp, ontwikkeling 54 Implementatie en toepassing 54 5.4. Methodische ondersteuning van het berichtontwikkelingsproces 55 Procesmodel 55 State-transition-diagram 55 Time-sequence-diagram 55 Informatiemodel en berichthiërarchie 56 5.5. Specificatie van elektronische ketenberichten 56 Gegevensmodel 56 Berichtmodel 56 Specificatie van een elektronisch ketenbericht 58 Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 4 van 103
6. Definities 65 7. Referenties 68 Appendix A 71 Lijst met figuren Figuur 1: opbouw SuwiML berichtschemaset. 8 Figuur 2: opbouw SuwiML berichtschema vanuit SGR/SuwiML. 9 Figuur 3: samenhang van standaarden en schema s binnen SGR/SuwiML. 10 Figuur 4: voorbeeld van een SuwiML bericht met namespace verwijzingen. 11 Figuur 5: opbouw en onderlinge verhouding SuwiML basisschema modulen. 13 Figuur 6: voorbeeld van een onderdeel van de gegevenstypen-module. 14 Figuur 7: voorbeeld van een onderdeel van de gegevenstypen-module: Geslacht-Coded.xsd. 15 Figuur 8: voorbeeld van een onderdeel van de gegevenstypen-module: Geslacht-Typed.xsd. 16 Figuur 9: voorbeeld van een onderdeel van de entiteiten-module. 17 Figuur 10: opbouw en onderlinge verhouding SuwiML basisschema en SuwiML berichtschemaset. 17 Figuur 11: SOAP envelopeschema van een SuwiML Action berichtschema. 26 Figuur 12: SOAP envelopestructuur van een SuwiML Action berichtschema. 26 Figuur 13: SOAP envelopeschema van een SuwiML Reaction berichtschema. 28 Figuur 14: SOAP envelopestructuur van een SuwiML Reaction berichtschema. 29 Figuur 15: voorbeeld SuwiML Action bodyschema. 31 Figuur 16: voorbeeld SuwiML Reaction bodyschema. 33 Figuur 17: voorbeeld SuwiML Reaction response bericht. 34 Figuur 18: opbouw berichthiërarchie op basis van het SGR / het SuwiML basisschema. 37 Figuur 19: berichtinstantie irt SGR. 38 Figuur 20: berichtinstantie irt SGR met getypeerde relatie. 38 Figuur 21: berichtinstantie irt SGR met overerving van abstract datatype (eenvoudig). 38 Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 5 van 103
Figuur 22: berichtinstantie irt SGR met overerving van abstract datatype (complex). 39 Figuur 23: berichtinstantie irt SGR, getypeerde relatie met overerving van abstract datatype. 40 Figuur 24: berichtinstantie irt SGR met abstracte subtypes. 41 Figuur 25: voorbeeld Entiteit-Relatie diagram voor ClientSuwi. 42 Figuur 26: SuwiML Reaction bodyschema met een verbijzondering van het XML complextype voor ClientSuwi. 43 Figuur 27: voorbeeld SuwiML Reaction response bericht met een warning. 45 Figuur 28: modelleren van clusters binnen SuwiML body. 47 Figuur 29: berichtontwikkelingsproces. 49 Figuur 30: ISO 17113 development of messages. 50 Figuur 31: berichtontwikkelingsproces. 53 Figuur 32: schematisch voorbeeld van een gegevensmodel. 57 Figuur 33: voorbeeld van een berichtmodel op basis van het gegevensmodel in Figuur 32. 57 Figuur 34: voorbeeld van een berichtmodel op basis van het gegevensmodel in Figuur 32. 57 Figuur 35: voorbeeld van een berichtmodel op basis van het gegevensmodel in Figuur 32. 57 Figuur 36: voorbeeld van een berichtmodel op basis van het gegevensmodel in Figuur 32. 57 Figuur 37: voorbeeld van een berichtmodel op basis van het gegevensmodel in Figuur 32. 58 Figuur 38: berichtmodel voor ReintegratieadviesCwiUwv zoals vastgelegd in EC-Design. 71 Lijst met tabellen Tabel 1: opbouw SuwiML namespace. 11 Tabel 2: voorbeeldscenario van een aantal wijzigingen en de consequenties daarvan irt versienummers. 22 Tabel 3: opbouw SuwiML berichtschemaset. 25 Tabel 4: mogelijke combinaties van subelementen binnen het SuwiMLBody rootelement (onvermelde combinaties zijn niet mogelijk). 31 Tabel 5: beperkingen tav het gebruik van lege velden / waarden in een SuwiML bericht. 35 Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 6 van 103
1. Inleiding 1.1. Doel SGR/SuwiML heeft tot doel de (elektronische) gegevensuitwisseling tussen partijen in de Suwi keten te faciliteren. Dit betreft zowel het faciliteren van de ontwikkeling van de gegevensuitwisseling (het zo eenvoudig mogelijk maken van het definiëren en realiseren van de gegevensuitwisseling, in de vorm van berichten) als de ondersteuning van de operationele gegevensuitwisseling (het run-time gebruik van SGR/SuwiML). Voor de definitie van de inhoud van berichten en de codering van de uit te wisselen gegevens wordt gebruik gemaakt van SGR/SuwiML, in de vorm van het Suwi Gegevensregister en extensies hierop voor uitwisseling in XML-formaat. SGR/SuwiML faciliteert het snel en eenduidig definiëren van de berichtinhoud (middels betekenis van gegevens, te gebruiken gegevenselementen, entiteiten en relaties), de berichtstructuur en de berichtnotatie (middels XML-tags, SuwiML basisschema, SuwiML berichtschema s). Dit document beschrijft de functionele en technische richtlijnen voor het definiëren en uitwisselen van SuwiML berichten met betrekking tot de inhoudelijke structuur van de gegevens die moeten worden verstuurd. Dit document beschrijft de opzet en het gebruik van het SuwiML basisschema voor het definiëren van de body van SuwiML berichten. Daarmee biedt dit document een beschrijving voor het samenstellen van SuwiML berichtschema s alsook toepassingsonafhankelijke richtlijnen voor het realiseren van gegevensuitwisseling tussen de partijen in de Suwi keten. De SuwiML berichtstandaard is bedoeld voor zowel informatieanalisten als software-engineers en is zowel gericht op het ontwikkelen van berichten als op de wijze waarop applicaties operationeel met berichten moeten omgaan. 1.2. Leeswijzer Hoofdstuk 2 geeft een algemene introductie op SGR/SuwiML en geeft een inleidende beschrijving van de SuwiML berichtstandaard. Hoofdstuk 3 geeft een detail beschrijving van de opbouw en structuur van het SuwiML basisschema. Hoofdstuk 4 geeft een detail beschrijving van de opbouw en structuur van een SuwiML berichtschema. Hoofdstuk 5 geeft een detail beschrijving van de SuwiML berichtontwikkelingsmethodiek. Hoofdstuk 6 geeft een beknopt overzicht van de gehanteerde definities. NB. dit document veronderstelt dat de lezer een redelijke kennis van de XML en XML Schema standaard heeft. Voor meer informatie over deze en andere XML gerelateerde standaarden wordt verwezen naar de website van de W3C: http://www.w3c.org. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 7 van 103
2. SuwiML berichtstandaard 2.1. Inleiding Alle betrokken partijen binnen de Suwi keten wisselen gegevens uit op basis van het Suwi Gegevensregister (SGR). Het SGR is het gegevensmodel met alle voor gemeenschappelijk gegevensgebruik in de Suwi keten relevante attributen, entiteiten en relaties. Zie het document Suwi Gegevensregister deel 1 en 2 (http://www.bkwi.nl) voor de inrichting van het SGR. SuwiML berichten, zoals deze worden verzonden tussen de betrokken partijen in de Suwi keten, worden afgeleid van het SGR. Entiteiten en attributen in het SGR keren terug als XML elementen in een SuwiML bericht. Een SuwiML bericht is opgemaakt als een hiërarchische reeks van XML gecodeerde gegevens. Berichten die behoren tot één berichttype, zijn te verdelen in twee groepen: het initiërende bericht, de Action, en het reagerende bericht, de Reaction. De structuur en inhoud van een SuwiML bericht wordt gevalideerd aan de hand van het SuwiML berichtschema dat eraan ten grondslag ligt. In SuwiML wordt de definitie van een logisch berichttype vastgelegd in twee SuwiML berichtschema s met elk drie afzonderlijke XML Schema s (een envelope-, header- en bodyschema voor het Action berichtschema en een envelope-, header- en bodyschema voor het Reaction berichtschema). Het Action berichtschema en het Reaction berichtschema samen vormen de SuwiML berichtschemaset voor het betreffende berichttype. Figuur 1 geeft hier een voorbeeld van. SuwiML berichtschemaset action UwvDossierPersoon-EnvelopeAction.xsd import SuwiML-Header.xsd import reaction UwvDossierPersoon-EnvelopeReaction.xsd import import UwvDossierPersoon-BodyAction.xsd UwvDossierPersoon-BodyReaction.xsd Figuur 1: opbouw SuwiML berichtschemaset. Een op deze wijze gemodelleerd berichttype is onderdeel van een generieke methode voor het uitwisselen van berichten. Deze methode omvat de technische richtlijnen voor het definiëren en uitwisselen van SuwiML berichten met betrekking tot de envelopestructuur (het transportmiddel) en de wijze van verzending (het transport). De envelopestructuur wordt verplicht gebaseerd op de SOAP standaard. Zie het document SuwiML transactiestandaard voor een beschrijving van deze generieke methode voor het uitwisselen van berichten. De SuwiML berichtstandaard beschrijft de wijze waarop de SuwiML body moet worden vormgegeven op basis van de bouwstenen vastgelegd in het SuwiML basisschema. De SuwiML berichtstandaard maakt deel uit van SGR/SuwiML. SGR/SuwiML bestaat uit de volgende onderdelen: Suwi Gegevensregister (aangeduid als SGR: het gegevensmodel met alle voor gemeenschappelijk gegevensgebruik in de Suwi keten relevante attributen, entiteiten en relaties); Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 8 van 103
SuwiML basisschema (een XML Schema via welke de datatype informatie voor alle entiteiten en gegevenstypen uit het SGR in XML Schema formaat beschikbaar wordt gesteld); SuwiML transactiestandaard (technische richtlijnen voor het definiëren en uitwisselen van SuwiML berichten met betrekking tot de envelopestructuur (het transportmiddel) en de wijze van verzending (het transport)); SuwiML berichtstandaard (functionele en technische richtlijnen voor het definiëren en uitwisselen van SuwiML berichten met betrekking tot de inhoudelijke structuur van de gegevens die moeten worden verstuurd). In Figuur 2 worden de relaties tussen de verschillende onderdelen van SGR/SuwiML, noodzakelijk voor de opbouw van een SuwiML bericht, schematisch weergegeven. Het SuwiML basisschema is het XML synoniem voor het Suwi Gegevensregister en is van invloed op alle onderdelen van een SuwiML bericht. De SuwiML transactiestandaard schrijft de SOAP envelopestructuur voor, alsmede de stuurgegevens binnen de SuwiML header. De SuwiML berichtstandaard schrijft de opbouw van de SuwiML body voor. Suwi Gegevensregister SuwiML basisschema SuwiML berichtschema SOAP envelope SOAP header SuwiML header SOAP body SuwiML transactiestandaard SuwiML body SuwiML berichtstandaard Figuur 2: opbouw SuwiML berichtschema vanuit SGR/SuwiML. Een SuwiML bericht bestaat altijd uit een envelope die een header (de stuurgegevens) en een body (de berichtgegevens) bevat. De opbouw van een bericht door envelope, header en body staat beschreven in de SuwiML transactiestandaard en is gebaseerd op de SOAP standaard. Dit document, de SuwiML berichtstandaard, beschrijft de vormgeving van de body (de feitelijke berichtinhoud) van een SuwiML bericht. In Figuur 3 wordt de samenhang van de binnen SGR/SuwiML gebruikte standaarden en schema s ten opzichte van elkaar weergegeven. Aan de linkerkant worden de gebruikte standaarden weergegeven en benoemd. De standaarden gezamenlijk beschrijven een generiek SuwiML bericht. De rechterkant toont een voorbeeld van een SuwiML bericht. De SuwiML transactiestandaard maakt gebruik van de standaard SOAP envelopestructuur en specificeert voor een bericht het headerschema met daarin de stuurgegevens. De SuwiML berichtstandaard specificeert de wijze waarop het bodyschema moet worden vormgegeven met behulp van het SuwiML basisschema. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 9 van 103
Een SuwiML berichtschemaset wordt ontwikkeld door de ontwikkelaars binnen een project en is geënt op de formele richtlijnen zoals vastgesteld door SGR/SuwiML. Bij het samenstellen van een SuwiML berichtschemaset wordt gebruik gemaakt van het SuwiML basisschema, welke als grondslag dient voor alle SuwiML berichtschema s. De berichtschemaset moet voordat het in gebruik kan worden genomen, worden getoetst aan de voorgeschreven SGR/SuwiML standaard. Deze toetsing wordt uitgevoerd door de beheerder/uitvoerder van SGR/SuwiML, i.e. het BKWI. W3C standaard SOAP SOAP - ENV: Envelope SGR / SuwiML SuwiML header BerichtIdentificatie RouteInformatie BerichtType IndTestbericht etc. Transactie SuwiML body Request Gegevens - Response uitwisseling Redirect functionele Fault, Warning inhoud Acknowledgement SuwiML basisschema entiteiten gegevenstypen module module Generiek bericht Header Body Voorbeeld berichtinstantie ( request ) <? xml version ="1.0" encoding ="UTF - 8"?> <SOAP - ENV: Envelope xmlns :SOAP - ENV=" http :// schemas. xmlsoap. org /soap/ envelope /" xmlns : smlb =" http :// www. suwi. nl / SuwiML / BodyAction / UwvDossierPersoon - v0302" xmlns : smlh =" http :// www. suwi. nl / SuwiML / Header - v0200" xmlns : xsi =" http :// www.w3. org /2001/ XMLSchema - instance " xsi : schemalocation =" http :// schemas. xmlsoap. org /soap/ envelope / UwvDossierPersoon - v0302 - b07 - EnvelopeAction. xsd "> <SOAP - ENV: Header > <smlh:suwimlheader> <RouteInformatie> </RouteInformatie> <BerichtIdentificatie> </BerichtIdentificatie> <Transactie> </Transactie> </smlh:suwimlheader> </SOAP - ENV: Header > <SOAP - ENV:Body> <smlb:suwimlbody> < : > < smlb <Request> : Request > </Request> smlb : Request > </ smlb : SuwiMLBody > </smlb:suwimlbody> </SOAP - ENV:Body> </SOAP - ENV: Envelope > Figuur 3: samenhang van standaarden en schema s binnen SGR/SuwiML. 2.2. SuwiML berichtidentificatie SuwiML berichten worden beschreven in verscheidene schema s: een envelope-schema, een header-schema en een body-schema. De berichtschema's die de Action en Reaction beschrijven, vormen samen een SuwiML berichtschemaset, die hoort bij een bepaald berichttype. Om de verschillende schema s te onderscheiden wordt gebruik gemaakt van namespaces. Een namespace is een unieke naam die een specifiek definitiegebied aanduidt. Door een schema te definiëren binnen een eigen namespace worden conflicten voorkomen in naamgeving en kan eenduidigheid worden gewaarborgd van XML element- en type definities. Bij het vaststellen van een namespace moet rekening worden gehouden met de BerichtNaam, VersieMajor en VersieMinor (onderdeel van BerichtType) en het interactietype (Action of Reaction). De namespaces binnen SuwiML worden als volgt opgebouwd: Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 10 van 103
Schema Namespace Prefix Basisschema http://www.suwi.nl/suwiml/basis-v<versiemajor><versieminor> sml bijv.: http://www.suwi.nl/suwiml/basis-v0200 Body http://www.suwi.nl/suwiml/body<interaction>/<berichtnaam>v<versiemajor><versieminor> smlb bijv.: http://www.suwi.nl/suwiml/bodyaction/uwvdossierpersoon-v0302 bijv.: http://www.suwi.nl/suwiml/bodyreaction/uwvdossierpersoon-v0302 Header http://www.suwi.nl/suwiml/header-v<versiemajor><versieminor> smlh bijv.: http://www.suwi.nl/suwiml/header-v0200 Envelope http://schemas.xmlsoap.org/soap/envelope/ SOAP- ENV Tabel 1: opbouw SuwiML namespace. Ieder SuwiML bericht wordt in de vorm van een SOAP envelope verstuurd. Dit betekent dat de SuwiML header en de SuwiML body in de SOAP envelope worden geïntegreerd. De koppeling tussen namespace en URL (locatie) wordt gemaakt met behulp van een XML Schema instance constructie, getoond in het XML voorbeeld in Figuur 4. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:smlh = "http://www.suwi.nl/suwiml/header-v0200" xmlns:smlb = "http://www.suwi.nl/suwiml/bodyaction/uwvdossierpersoon-v0302" xmlns:xsi = "http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation = "http://schemas.xmlsoap.org/soap/envelope/ UwvDossierPersoon-v0302-b07-EnvelopeAction.xsd"> <SOAP-ENV:Header> <smlh:suwimlheader> <RouteInformatie> <Bron>... </Bron> <Bestemming>... </Bestemming> <Tussenstation>... </Tussenstation> </RouteInformatie> <BerichtIdentificatie>... </BerichtIdentificatie> <Transactie>... </Transactie> </smlh:suwimlheader> </SOAP-ENV:Header> <SOAP-ENV:Body> <smlb:suwimlbody> <Request>... </Request> </smlb:suwimlbody> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Figuur 4: voorbeeld van een SuwiML bericht met namespace verwijzingen. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 11 van 103
2.3. Validatie Een SuwiML berichtschema is een formele beschrijving van een bericht conform SGR/SuwiML. De zendende partij heeft de verplichting om een, volgens het vastgestelde SuwiML berichtschema, valide bericht te versturen. De ontvanger moet ieder binnenkomend bericht valideren tegen het bijbehorende vastgestelde SuwiML berichtschema alvorens het intern verder te verwerken. NB. binnen een bericht wordt middels het statement xsi:schemalocation verwezen naar de locatie van het gerelateerde SuwiML berichtschema waar automatisch tegen gevalideerd kan worden. Om nu te voorkomen dat de verzender van het bericht de vrijheid heeft te verwijzen naar een willekeurig XML Schema op een willekeurige locatie, is het verplicht om bij de implementatie van iedere afzonderlijke gegevensuitwisseling ervoor te zorgen dat tegen een vooraf vastgesteld en op een specifieke locatie geplaatst SuwiML berichtschema wordt gevalideerd. Dit ongeacht de verwijzing in het xsi:schemalocation statement in het bericht. Parsers die inkomende berichten automatisch verwerken moeten de verwijzing in het xsi:schemalocation statement dus feitelijk negeren, en gebruik maken van het vooraf vastgestelde en op een specifieke locatie geplaatste SuwiML berichtschema. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 12 van 103
3. SuwiML basisschema 3.1. Inleiding Het SuwiML basisschema wordt direct afgeleid uit het SGR en bestaat uit een verzameling 'standaard componenten' op basis waarvan SuwiML berichtschema s worden gedefinieerd. Het SuwiML basisschema bestaat uit twee modulen: de gegevenstypen-module en de entiteiten-module (zie Figuur 5). Hierin worden alle SGR-attributen zoals Sofi-nummer en SGR-entiteiten zoals ClientSuwi gedefinieerd. De relaties tussen entiteiten worden niet in het SuwiML basisschema gedefinieerd, deze worden (met het SGR als uitgangspunt) voor ieder afzonderlijk berichttype vastgelegd in de Action en Reaction SuwiML berichtschema s. SuwiML basisschema Entiteiten-module SGRentiteiten-v0200-b01.xsd SuwiML-v0200-b01-Include-Coded.xsd SuwiML-v0200-b01-Include-Typed.xsd include Gegevenstypen-module SGRgegevenstypen-v0200-b01.xsd include CdAoKlasse-v0200-b01-Coded.xsd include include Coded or Typed per <type> CdAoKlasse-v0200-b01-Typed.xsd include Figuur 5: opbouw en onderlinge verhouding SuwiML basisschema modulen. 3.2. Gegevenstypen Het SGR is een gegevensmodel welke alle voor gemeenschappelijk gegevensgebruik in de Suwi keten relevante attributen, entiteiten en relaties bevat. Iedere entiteit in het SGR bevat een aantal attributen, ieder attribuut verwijst naar een domeindefinitie voor het waardenbereik. In de gegevenstypen-module zijn alle SGR domeindefinities als verzameling samengebracht. Ieder SGRattribuut uit de entiteiten-module verwijst naar een SGR domeindefinitie uit de gegevenstypenmodule. Dit type is simpel (een tekenreeks zoals SofiNr of een gecodeerd waardebereik zoals Geslacht) of complex (een structuur zoals StandaardBedr), al naar gelang de aard van de SGR domeindefinitie die eraan ten grondslag ligt. Simpele typen worden als XML simpletype in het basisschema opgenomen; complexe typen worden als XML complextype gedefinieerd. De entiteiten-module en de gegevenstypen-module vormen samen het SuwiML basisschema. De entiteiten-module maakt gebruik van de SGR domeindefinities vastgelegd in de gegevenstypenmodule. Zowel de entiteiten-module als de gegevenstypen-module worden beiden in één en dezelfde namespace gedefinieerd: http://www.suwi.nl/suwiml/basis-v<versiemajor><versieminor>. Vanuit een SuwiML berichtschema wordt het SuwiML basisschema geïntegreerd met behulp van een Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 13 van 103
SuwiML basisschema-include-bestand: <BerichtNaam>-v<VersieMajor><VersieMinor>-b<Buildnr>- Include.xsd. Het SuwiML basisschema -include-bestand incorporeert de entiteiten-module en de gegevenstypen-module. Bij het opstellen van een SuwiML berichtschema mag het SuwiML basisschema (de entiteiten-module en de gegevenstypen-module) niet worden aangepast. Zie ook Figuur 5 en Figuur 10. Alle SGR domeindefinities in de gegevenstypen-module zijn direct of indirect gebaseerd op XML Schema datatypen (built-in types), zoals string, integer, decimal, date etc. De XML Schema datatypen (built-in types) zijn gedefinieerd in de XML Schema standaard. Deze worden niet apart gedefinieerd binnen de SuwiML schema s. <?xml version="1.0" encoding="utf-8"?> <!-- SuwiML Basisschema gegevenstypen v0200-b01 02-12-2004 17:22:22 --> <schema targetnamespace = "http://www.suwi.nl/suwiml/basis-v0200" xmlns = "http://www.w3.org/2001/xmlschema" xmlns:sml = "http://www.suwi.nl/suwiml/basis-v0200"> <!-- SGR domeindefinities --> <simpletype name="aantaln2"> <restriction base="nonnegativeinteger"> <mininclusive value="0"/> <maxinclusive value="99"/> <totaldigits value="2"/> </restriction> </simpletype> <simpletype name="aantsvdagenarbeidsverleden"> <restriction base="nonnegativeinteger"> <mininclusive value="0"/> <maxinclusive value="52"/> <totaldigits value="2"/> </restriction> </simpletype> <simpletype name="abonneenr"> <restriction base="string"> <maxlength value="10"/> <pattern value="\d*"/> </restriction> </simpletype> <simpletype name="netnr"> <restriction base="string"> <maxlength value="5"/> <pattern value="\d*"/> </restriction> </simpletype> </schema> Figuur 6: voorbeeld van een onderdeel van de gegevenstypen-module. Figuur 6 toont een onderdeel van de gegevenstypen-module, waarin een aantal SGR domeindefinities worden gedefinieerd welke geen gecodeerd waardebereik hebben. De SGR domeindefinities Abonneenr en Netnr worden vastgelegd met behulp van XML simpletype definities, Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 14 van 103
welke worden gedefinieerd als built-in datatype string met pattern \d* en maxlength 10 respectievelijk 5. De SGR domeindefinities AantSvDagenArbeidsverleden en AantalN2 worden vastgelegd met behulp van XML simpletype definities, welke worden gedefinieerd als built-in datatype nonnegativeinteger met totaldigits 2, mininclusive 0 en maxinclusive 52 respectievelijk 99. <?xml version="1.0" encoding="utf-8"?> <!-- SuwiML Basisschema tabellen coded v0200-b01 02-12-2004 17:22:22 --> <schema targetnamespace = "http://www.suwi.nl/suwiml/basis-v0200" xmlns = "http://www.w3.org/2001/xmlschema" xmlns:sml = "http://www.suwi.nl/suwiml/basis-v0200"> <!-- Geslacht v0200-b01 tabeldefinitie met codelijst --> <simpletype name="geslacht"> <restriction base="string"> <enumeration value="0"> <annotation><documentation>onbekend</documentation></annotation> </enumeration> <enumeration value="1"> <annotation><documentation>mannelijk</documentation></annotation> </enumeration> <enumeration value="2"> <annotation><documentation>vrouwelijk</documentation></annotation> </enumeration> <enumeration value="9"> <annotation><documentation>niet gespecificeerd (het gegevenselement wordt niet gevoerd in de administratie)</documentation></annotation> </enumeration> </restriction> </simpletype> </schema> Figuur 7: voorbeeld van een onderdeel van de gegevenstypen-module: Geslacht-Coded.xsd. Figuur 7 toont een onderdeel van de gegevenstypen-module, waarin de SGR domeindefinitie voor Geslacht wordt gedefinieerd met een gecodeerd waardebereik. Geslacht wordt vastgelegd met behulp van een XML simpletype definitie, welke wordt gedefinieerd als built-in datatype string met daarop een restriction van enumerations 0, 1, 2 en 9, inclusief bijbehorende annotations. <?xml version="1.0" encoding="utf-8"?> <!-- SuwiML Basisschema tabellen typed v0200-b01 02-12-2004 17:22:22 --> <schema targetnamespace = "http://www.suwi.nl/suwiml/basis-v0200" xmlns = "http://www.w3.org/2001/xmlschema" xmlns:sml = "http://www.suwi.nl/suwiml/basis-v0200"> <!-- Geslacht v0200-b01 tabeldefinitie met type-aanduiding --> <simpletype name="geslacht"> <restriction base="string"> <length value="1"/> <pattern value="\d*"/> </restriction> </simpletype> </schema> Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 15 van 103
Figuur 8: voorbeeld van een onderdeel van de gegevenstypen-module: Geslacht-Typed.xsd. Figuur 8 toont een alternatieve SGR domeindefinitie voor Geslacht, waarbij het gecodeerde waardebereik bewust achterwege is gelaten. Ook deze SGR domeindefinitie is onderdeel van de gegevenstypen-module. Bij gebruik van het SuwiML basisschema wordt steeds precies één van de twee SGR domeindefinities (Coded of Typed) gebruikt voor validatie. De Coded validatie laat exact en alleen het vooraf gedefinieerde gecodeerde waardebereik toe voor de betreffende SGR domeindefinitie. De Typed validatie is milder van aard en laat alle mogelijke waarden toe die voldoen aan de XML simpletype definitie voor de betreffende SGR domeindefinitie; hierbij zijn dus ook waarden toegestaan die niet noodzakelijk in het gecodeerde waardebereik vallen. In het voorbeeld hierboven voor Geslacht, zou bij gebruik van de Typed definitie ook de waarde 6 zijn toegestaan, hoewel deze niet voorkomt in het gecodeerde waardebereik. 3.3. Entiteiten In de entiteiten-module wordt iedere SGR-entiteit gedefinieerd als een complex type (XML complextype). De SGR-attributen behorend bij een SGR-entiteit worden als een XML sequence van optionele elementen binnen het desbetreffende XML complextype gedefinieerd. Zoals gezegd verwijst ieder SGR-attribuut daarbij naar een SGR domeindefinitie uit de gegevenstypen-module. In de entiteiten-module worden geen SGR-relaties vastgelegd. De entiteiten-module is dus feitelijk een opsomming van losse SGR-entiteiten. Relaties tussen entiteiten worden (met het SGR als uitgangspunt) op berichtniveau vastgelegd, i.e. relaties worden in de Action en Reaction SuwiML berichtschema s vastgelegd. Figuur 9 toont een onderdeel van de entiteiten-module, waarin de entiteiten Vreemdelingendocument en Ziektekostenverzekering middels XML complextypes zijn gedefinieerd. Te zien is hoe de entiteit Vreemdelingendocument feitelijk een uitbreiding (XML extension) is van de entiteit VisDocument. Verder is te zien dat het attribuut NrVreemdelingendocument gebruik maakt van de SGR domeindefinitie NummerAN30 uit de gegevenstypen-module. <?xml version="1.0" encoding="utf-8"?> <!-- SuwiML Basisschema entiteiten v0200-b01 02-12-2004 17:22:22 --> <schema targetnamespace = "http://www.suwi.nl/suwiml/basis-v0200" xmlns = "http://www.w3.org/2001/xmlschema" xmlns:sml = "http://www.suwi.nl/suwiml/basis-v0200"> <!-- SGR entiteit definities --> <complextype name="visdocument"> <sequence> <element name="cdsrtvisdocument" type="sml:cdsrtvisdocument" minoccurs="0"/> <element name="cdlandvanuitgiftevisdocument" type="sml:landencdisoa2" minoccurs="0"/> </sequence> </complextype> <complextype name="vreemdelingendocument"> <complexcontent> <extension base="sml:visdocument"> Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 16 van 103
<sequence> <element name="cdsrtvreemdelingendocument" type="sml:cdsrtvreemdelingendocument" minoccurs="0"/> <element name="nrvreemdelingendocument" type="sml:nummeran30" minoccurs="0"/> <element name="dategeldigvreemdelingendocument" type="sml:datum" minoccurs="0"/> <element name="indarbeidtoegestaan" type="sml:stdindjn" minoccurs="0"/> <element name="indtewerkstelvergunningvereist" type="sml:stdindjn" minoccurs="0"/> <element name="indverlengingaangevraagd" type="sml:stdindnvt" minoccurs="0"/> </sequence> </extension> </complexcontent> </complextype> <complextype name="ziektekostenverzekering"> <sequence> <element name="verzekerdennr" type="sml:verzekerdennr" minoccurs="0"/> <element name="bedrpremieziektekostenverz" type="sml:standaardbedr" minoccurs="0"/> <element name="indaanvullendverzekerd" type="sml:stdindonb" minoccurs="0"/> <element name="bedrpremieaanvulziektekostenverz" type="sml:standaardbedr" minoccurs="0"/> </sequence> </complextype> </schema> Figuur 9: voorbeeld van een onderdeel van de entiteiten-module. 3.4. Hiërarchie De gegevenstypen-module en entiteiten-module bestaan uit een aantal XML Schema's. In Figuur 10 staat aangegeven hoe deze zich tot elkaar verhouden, en op welke wijze een berichtschema er gebruik van maakt. De entiteiten-module komt overeen met precies één XML Schema, te weten SGRentiteiten-v<VersieMajor><VersieMinor>-b<Buildnr>.xsd. Bij de gegevenstypen-module ligt de zaak complexer. action import UwvDossierPersoon-v0302-b07-EnvelopeAction.xsd SuwiML berichtschemaset SuwiML-v0200-Header.xsd reaction import UwvDossierPersoon-v0302-b07-EnvelopeReaction.xsd import UwvDossierPersoon-v0302-b07-BodyAction.xsd import UwvDossierPersoon-v0302-b07-Include.xsd import import UwvDossierPersoon-v0302-b07-BodyReaction.xsd SuwiML basisschema Entiteiten-module SGRentiteiten-v0200-b01.xsd include Gegevenstypen-module SGRgegevenstypen-v0200-b01.xsd include CdAoKlasse-v0200-b01-Coded.xsd include include Coded or Typed per <type> CdAoKlasse-v0200-b01-Typed.xsd include Figuur 10: opbouw en onderlinge verhouding SuwiML basisschema en SuwiML berichtschemaset. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 17 van 103
Gegevens kunnen naar diverse soorten SGR domeindefinities verwijzen. Naast de ongecodeerde domeindefinities gebaseerd op string, date, etc., al dan niet voorzien van een beperkend pattern, maxlength, etc., zijn er ook de gecodeerde domeindefinities op basis van XML enumerations. Deze XML enumerations beschrijven een lijst met specifieke codes (waarden) eventueel gecombineerd met een omschrijving. Een eenvoudig voorbeeld is de enumeration voor Geslacht, bestaande uit de codes 0, 1, 2 en 9, overeenkomend met de omschrijvingen Onbekend, Mannelijk, Vrouwelijk en Niet Gespecificeerd, zie Figuur 7. In dit voorbeeld is de lijst met codes statisch, i.e. hij wijzigt niet of nauwelijks. Er zijn echter ook dynamische codelijsten die vaak wijzigen. De structuur van de gegevenstypen-module is zodanig gekozen, dat codes kunnen wijzigen zonder de bijbehorende programmatuur te moeten herprogrammeren of herconfigureren. Het eenvoudigweg uploaden van de nieuwe codelijst moet volstaan om de programmatuur weer up-to-date te brengen. Iedere SGR domeindefinitie waarvoor een codelijst beschikbaar is, wordt vastgelegd in twee verschillende XML Schema varianten, een Coded en een Typed schema. De Coded variant beschrijft de domeindefinitie als een specifieke XML enumeration van codewaarden en codeomschrijvingen, waardoor een "strenge" validatie mogelijk is; Figuur 7 geeft een voorbeeld. De Typed variant beschrijft dezelfde domeindefinitie slechts als een pattern, waardoor een milde validatie mogelijk is, waarbij niet bestaande codes die wel binnen de type- en patterndefinitie passen, geen foutmelding opleveren; Figuur 8 geeft een voorbeeld. De keus voor Coded of Typed is afhankelijk van de toepassing, en wordt per SuwiML berichtschema vastgelegd in een apart <BerichtNaam>-v<VersieMajor><VersieMinor>-b<Buildnr>-Include.xsd schema, welke wordt afgeleid van één van de template schema s: SuwiML-v<VersieMajor><VersieMinor>-b<Buildnr>-Include-Coded.xsd of SuwiML-v<VersieMajor><VersieMinor>-b<Buildnr>-Include-Typed.xsd. Binnen het afgeleide berichtspecifieke include schema kan voor elke afzonderlijke domeindefinitie (waarvoor een codelijst beschikbaar is), gekozen worden of er gebruik wordt gemaakt van de Coded of Typed variant. De keuze voor het gebruik van Coded en/of Typed kan dus per berichttype verschillen. In het meest extreme geval wordt voor het ene berichttype alleen gebruik gemaakt van Coded en voor het andere berichttype alleen van Typed. Wat betreft de keuze voor Coded en/of Typed zijn twee strategieën denkbaar: 1. Zoveel mogelijk gebruik maken van de Coded variant; het berichtschema dwingt bij de validatie van berichten door de verzendende/ontvangende adapter de specifieke codewaarden af conform het SGR. Hiermee wordt de verwerking in de verzendende/ontvangende applicatie feitelijk ontlast, omdat daar dan zonder verdere controle mag worden aangenomen dat aan het vereiste codewaardebereik is voldaan. Voordeel van deze strategie is, dat er alleen gegarandeerd goede berichten worden verzonden/ontvangen en dat deze garantie reeds op adapternivo wordt afgedwongen. Nadeel van deze strategie is, dat bij aanpassingen van de aan het berichttype gerelateerde codelijsten, het berichtschema ook moet worden aangepast en in een nieuwe versie moet worden gepubliceerd en geïmplementeerd. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 18 van 103
2. Zoveel mogelijk gebruik maken van de Typed variant; het berichtschema dwingt bij de validatie van berichten door de verzendende/ontvangende adapter slechts het formaat af conform het SGR. Hiermee kan dus niet worden gegarandeerd dat ieder verzonden/ontvangen bericht alleen geldige codewaarden conform het SGR bevat. Hiermee wordt de verwerking in de verzendende/ontvangende applicatie feitelijk extra belast, omdat daar dan moet worden gecontroleerd of aan het vereiste codewaardebereik is voldaan. Voordeel van deze strategie is, dat bij aanpassingen van de aan het berichttype gerelateerde codelijsten, het berichtschema niet noodzakelijk hoeft te worden aangepast. Nadeel van deze strategie is, dat de applicaties zodanig moeten worden geconfigureerd, dat ze altijd aan de meest actuele set van codewaardebereiken voldoen. Bij de samenstelling en/of verwerking van berichten door de applicatie moet het codewaardebereik worden afgedwongen. Naar verwachting vindt in de toekomst de berichtuitwisseling plaats op basis van de Typed variant (strategie 2) en vindt de validatie tegen het codewaardebereik plaats in de diverse applicaties. Hiermee wordt de stabiliteit van de (operationele) elektronische ketenberichten bevorderd, hetgeen voordelen oplevert voor de beheerlast en implementatielast van berichtspecificaties. Het actueel houden van de codewaardebereiken binnen de applicaties vindt zoveel als mogelijk automatisch plaats door het inlezen van de nieuwste versie van het SuwiML basisschema. 3.5. Automatisch tabellenbeheer Omdat in de praktijk de gecodeerde waardebereiken van bepaalde SGR domeindefinities regelmatig wijzigen, moet ook het SuwiML basisschema hierop regelmatig worden aangepast. Voor het vastleggen van het SuwiML basisschema is een structuur bedacht, die het mogelijk maakt om volledig geautomatiseerd het SuwiML basisschema (of gerichte delen daarvan) te updaten. Deze structuur staat in sectie 3.4 beschreven en wordt vastgelegd in meerdere losse b estanden: SGRentiteiten-v<VersieMajor><VersieMinor>-b<Buildnr>.xsd Een alfabetische opsomming van alle SGR entiteiten en gegevenselementen (attributen), vastgelegd in een XML Schema. SGRgegevenstypen-v<VersieMajor><VersieMinor>-b<Buildnr>.xsd Een alfabetische opsomming van alle SGR domeindefinities waarvoor géén gecodeerd waardebereik bestaat, vastgelegd in een XML Schema. <Domeintag>-v<VersieMajor><VersieMinor>-b<Buildnr>-Coded.xsd Een apart XML Schema voor iedere SGR domeindefinitie waarvoor een gecodeerd waardebereik bestaat. Alle geldige codes zijn als XML enumerations gespecificeerd inclusief bijbehorende omschrijving. <Domeintag>-v<VersieMajor><VersieMinor>-b<Buildnr>-Typed.xsd Een apart XML Schema voor iedere SGR domeindefinitie waarvoor een gecodeerd waardebereik bestaat. Er wordt geen gebruik gemaakt van XML enumerations voor alle geldige codes, maar slechts van een beperkte formaatdefinitie waarin de toegestane lengte en karakters worden vastgelegd. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 19 van 103
<Domeintag>-v<VersieMajor><VersieMinor>-b<Buildnr>.xml Een aparte XML instance voor iedere SGR domeindefinitie waarvoor een gecodeerd waardebereik bestaat. Alle geldige codes zijn als waarden gespecificeerd inclusief bijbehorende omschrijving. Bovendien wordt hier per code vastgelegd wat de datum begin geldigheid en datum einde geldigheid is. Zoals gezegd worden alle onderdelen van het SuwiML basisschema vastgelegd in één en dezelfde namespace. Met behulp van het include bestand worden de afzonderlijke XML Schema onderdelen middels XML include statements ingelezen. Daarbij wordt voor iedere SGR domeindefinitie waarvoor een gecodeerd waardebereik bestaat, steeds een keuze gemaakt of er gebruik wordt gemaakt van Coded.xsd (strikte validatie tegen de feitelijk toegestane codes) of van Typed.xsd (slechts beperkte/milde validatie tegen de formaatdefinitie). Bovendien kan de verzameling XML instances, voor SGR domeindefinities met een gecodeerd waardebereik, met behulp van een tabelindex (SGRtabelindex-v<VersieMajor><VersieMinor>b<Buildnr>.xml), met verwijzingen naar de actuele bestandsnamen van deze XML instances, geautomatiseerd ingelezen worden door een applicatie. Op deze wijze is een applicatie dus altijd verzekerd van de meest actuele verzameling SGR tabellen/codelijsten. In combinatie met de hier beschreven tabelindex is ook een overzicht van SGR domeinverwijzingen (SGRdomeinverwijzingen-v<VersieMajor><VersieMinor>-b<Buildnr>.xml) beschikbaar. Het SGR domeinverwijzingen overzicht geeft per SGR gegevenselement (attribuut) aan van welke SGR domeindefinitie, inclusief aanduiding <VersieMajor><VersieMinor>, gebruik wordt gemaakt. In de beschreven structuur, leidt de toevoeging van een code aan het gecodeerde waardebereik van een SGR domeindefinitie dus slechts tot een nieuwe versie van het bijbehorende Coded.xsd bestand, de bijbehorende XML instance en het include bestand. De tabelindex wordt in lijn hiermee geactualiseerd en de domeinverwijzingen eventueel ook als de wijziging tot een nieuwe <VersieMajor><VersieMinor> leidt. SuwiML berichtschema s kunnen op een vergelijkbare manier als applicaties gebruik maken van de beschreven structuur van het SuwiML basisschema. Het idee hierbij is dat een bepaalde versie van een SuwiML berichtschema gebruik maakt van een bepaalde versie (freeze) van het SuwiML basisschema. Eventuele aanpassingen in het SuwiML basisschema worden dus pas in een volgende versie van het SuwiML berichtschema toegepast/gebruikt. De hier beschreven structuur voor het SuwiML basisschema moet er toe leiden dat de meest actuele set van bestanden waarin het SuwiML basisschema is vastgelegd, steeds on-line beschikbaar is. Alle (applicatiebeheerders van) ketenpartners kunnen nu op ieder gewenst moment het SuwiML basisschema of gerichte onderdelen daarvan, downloaden en binnen de eigen operationele omgeving implementeren. Hiermee kan het proces van het publiceren van SuwiML basisschema updates door het BKWI en het controleren, downloaden en installeren van deze updates door ketenpartners geautomatiseerd worden. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 20 van 103
3.6. Versienummering Indien voor een SGR domeindefinitie een code wordt toegevoegd, of een andere wijziging wordt doorgevoerd, dan heeft dit gevolgen voor de versienummering van het SuwiML basisschema. Tabel 2 geeft een overzicht van alle mogelijke wijzigingen en de consequenties voor de versienummering van het SuwiML basisschema. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 21 van 103
Soort wijziging SuwiML basisschema SuwiML-Include-Typed SuwiML-Include-Coded SGRentiteiten SGRgegevenstypen TypeX-Typed TypeX-Coded TypeY-Typed TypeY-Coded Initieel v0100-b01 v0100-b01 v0100-b01 v0100-b01 v0100-b01 v0100-b01 v0100-b01 v0100-b01 v0100-b01 Er wordt een code toegevoegd aan TypeX v0100-b02 v0100-b01 v0100-b02 v0100-b01 v0100-b01 v0100-b01 v0100-b02 v0100-b01 v0100-b01 Er wordt een code toegevoegd aan TypeY v0100-b03 v0100-b01 v0100-b03 v0100-b01 v0100-b01 v0100-b01 v0100-b02 v0100-b01 v0100-b03 Pattern [a-z] in TypeY wordt [a-z0-9] v0100-b04 v0100-b04 v0100-b03 v0100-b01 v0100-b01 v0100-b01 v0100-b02 v0100-b04 v0100-b03 Maximale lengte van TypeX wordt teruggebracht van 2 naar 1 positie v0101-b01 v0101-b01 v0101-b01 v0101-b01 v0101-b01 v0101-b01 v0101-b01 v0101-b01 v0101-b01 Er wordt een code toegevoegd aan TypeX v0101-b02 v0101-b01 v0101-b02 v0101-b01 v0101-b01 v0101-b01 v0101-b02 v0101-b01 v0101-b01 Pattern [a-z0-9] in TypeY wordt [a-z] v0102-b01 v0102-b01 v0102-b01 v0102-b01 v0102-b01 v0102-b01 v0102-b01 v0102-b01 v0102-b01 Er wordt een code toegevoegd aan TypeX v0102-b02 v0102-b01 v0102-b02 v0102-b01 v0102-b01 v0102-b01 v0102-b02 v0102-b01 v0102-b01 Grote structurele wijziging in Entiteiten/Attributen v0200-b01 v0200-b01 v0200-b01 v0200-b01 v0200-b01 v0200-b01 v0200-b01 v0200-b01 v0200-b01 Tabel 2: voorbeeldscenario van een aantal wijzigingen en de consequenties daarvan irt versienummers. De regels zijn in het kort als volgt. Als een domeindefinitie, attribuut of entiteit wordt gewijzigd, dan verandert ook het versienummer (versie major, versie minor en/of buildnummer) van het basisschema; Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 22 van 103
Als het waardebereik van de domeindefinities in het nieuwe basisschema (na het doorvoeren van de wijziging) het waardebereik van de domeindefinities in het oude basisschema (voor het doorvoeren van de wijziging) volledig bevat, dan wordt het buildnummer van het basisschema met één opgehoogd en wordt het buildnummer van het subschema waarin de betreffende domeindefinitie is opgenomen gelijkgesteld aan die van het basisschema. Alle andere subschema s blijven ongewijzigd en behouden het reeds geldende buildnummer. Voorbeelden zijn het toevoegen van een code, het beëindigen van de geldigheid van een code (waarbij de code dus niet wordt verwijderd), het uitbreiden van een pattern, het vergroten van de maxlength, het verlagen van de minoccurs en het verhogen van de maxoccurs. Ook het aanpassen van de omschrijving behorend bij een reeds bestaande code, resulteert in het ophogen van het buildnummer (mits de aangepaste omschrijving qua betekenis gelijk blijft aan de oorspronkelijke omschrijving); Als het waardebereik van de domeindefinities in het nieuwe basisschema (na het doorvoeren van de wijziging) het waardebereik van de domeindefinities in het oude basisschema (voor het doorvoeren van de wijziging) niet volledig bevat, dan verandert de versie minor van alle files. Alle buildnummers worden dan op 01 teruggezet. Voorbeelden zijn het verkleinen van de maxlength, het verlagen van de maxoccurs, het verhogen van de minoccurs, het beperken van een pattern, het wijzigen van de length, het verwijderen van een code of het aanpassen van de betekenis (omschrijving) van een code. Ook het veranderen van de naam van een entiteit of attribuut resulteert in het ophogen van de versie minor en het resetten van het buildnummer naar 01 ; Grote wijzigingen, zoals het qua betekenis en opbouw herdefiniëren van entiteiten en attributen, leiden tot een wijziging van de versie major. Alle versie minor en buildnummers worden dan op 01 teruggezet. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 23 van 103
4. SuwiML berichtschema 4.1. Inleiding Een SuwiML bericht wordt in een SOAP envelope verstuurd. Onderdeel van deze SOAP envelope zijn een header en een body. De header legt de stuurgegevens vast die van belang zijn voor de routering en de logistieke verwerking van het bericht. De body bevat de functionele inhoud die moet worden uitgewisseld. De SOAP envelope en SuwiML header worden beschreven in de SuwiML transactiestandaard. De SuwiML body wordt hier beschreven. Voor de theoretische onderbouwing van de berichtontwikkelingsmethodiek biedt hoofdstuk 5 uitkomst, in het bijzonder sectie 5.5. 4.2. SuwiML body Structuur Ieder SuwiML bericht dat wordt verzonden, is gerelateerd aan een SuwiML berichtschemaset. Een SuwiML berichtschemaset bestaat uit een SuwiML berichtschema voor het Action bericht en een SuwiML berichtschema voor het Reaction bericht. Een SuwiML berichtschema bestaat uit een SOAP envelopeschema dat een SuwiML headerschema en een SuwiML bodyschema importeert; zie Figuur 1, Figuur 11 en Figuur 13. Een SuwiML bodyschema beschrijft exact hoe de body van een specifiek berichttype wordt opgebouwd; zie Tabel 3, Figuur 12 en Figuur 14. Schema Bestand, Tag en Namespace SOAP envelope Action <BerichtNaam>-v<VersieMajor><VersieMinor>-b<Buildnr>-Envelope<Interaction>.xsd bijv.: UwvDossierPersoon-v0302-b07-EnvelopeAction.xsd <SOAP-ENV:Envelope> http://schemas.xmlsoap.org/soap/envelope/ Reaction <BerichtNaam>-v<VersieMajor><VersieMinor>-b<Buildnr>-Envelope<Interaction>.xsd bijv.: UwvDossierPersoon-v0302-b07-EnvelopeReaction.xsd <SOAP-ENV:Envelope> http://schemas.xmlsoap.org/soap/envelope/ SuwiML header Action SuwiML-v<VersieMajor><VersieMinor>-Header.xsd Reaction bijv.: SuwiML-v0200-Header.xsd <SOAP-ENV:Envelope> <SOAP-ENV:Header> <smlh:suwimlheader> http://www.suwi.nl/suwiml/header-v<versiemajor><versieminor> bijv.: http://www.suwi.nl/suwiml/header-v0200 Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 24 van 103
Schema SuwiML body Action Bestand, Tag en Namespace <BerichtNaam>-v<VersieMajor><VersieMinor>-b<Buildnr>-Body<Interaction>.xsd bijv.: UwvDossierPersoon-v0302-b07-BodyAction.xsd <BerichtNaam>-v<VersieMajor><VersieMinor>-b<Buildnr>-Include.xsd bijv.: UwvDossierPersoon-v0302-b07-Include.xsd <SOAP-ENV:Envelope> <SOAP-ENV:Body> <smlb:suwimlbody> http://www.suwi.nl/suwiml/body<interaction>/<berichtnaam>-<versiemajor><versieminor> bijv.: http://www.suwi.nl/suwiml/bodyaction/uwvdossierpersoon-v0302 Reaction <BerichtNaam>-v<VersieMajor><VersieMinor>-b<Buildnr>-Body<Interaction>.xsd bijv.: UwvDossierPersoon-v0302-b07-BodyReaction.xsd <BerichtNaam>-v<VersieMajor><VersieMinor>-b<Buildnr>-Include.xsd bijv.: UwvDossierPersoon-v0302-b07-Include.xsd <SOAP-ENV:Envelope> <SOAP-ENV:Body> <smlb:suwimlbody> http://www.suwi.nl/suwiml/body<interaction>/<berichtnaam>-<versiemajor><versieminor> bijv.: http://www.suwi.nl/suwiml/bodyreaction/uwvdossierpersoon-v0302 Tabel 3: opbouw SuwiML berichtschemaset. Gedurende het ontwikkelingstraject van een berichttype wordt de VersieMajor en de VersieMinor van de betreffende berichtschemaset zoveel mogelijk ongemoeid gelaten. Dit heeft als voordeel dat de namespaces voor de betreffende berichtschemaset ook stabiel blijven. Wijzigingen in de berichtspecificatie, i.e. in de berichtschemaset, worden opgevangen met behulp van het Buildnr; deze hoogt bij iedere wijziging steeds met één op. Zodra een berichtschemaset in productie wordt genomen, wordt de VersieMajor, de VersieMinor en het Buildnr gefixeerd ( bevroren ). Eventuele aanpassingen die daarna volgen, maken automatisch deel uit van een nieuw ontwikkelingstraject waaraan een nieuwe combinatie VersieMajor, VersieMinor wordt gerelateerd. In het algemeen geldt dus dat iedere functionele wijziging in de specificatie van een berichttype, die leidt tot een aanpassing van één of meer van de XML Schema s waaruit de berichtschemaset is opgebouwd, ook automatisch leidt tot een nieuwe build-/versieaanduiding voor de gehele berichtschemaset. Dus zelfs als bijvoorbeeld alleen het Action deel van een berichtschemaset moet worden aangepast, dan krijgt toch de gehele berichtschemaset een nieuwe build-/versieaanduiding. <?xml version="1.0" encoding="utf-8"?> <schema targetnamespace = "http://schemas.xmlsoap.org/soap/envelope/" xmlns = "http://www.w3.org/2001/xmlschema" xmlns:smlb = "http://www.suwi.nl/suwiml/bodyaction/uwvdossierpersoon-v0302" xmlns:smlh = "http://www.suwi.nl/suwiml/header-v0200" xmlns:soap-env = "http://schemas.xmlsoap.org/soap/envelope/" elementformdefault = "qualified"> <!--Importeer de SuwiML header.--> <import namespace="http://www.suwi.nl/suwiml/header-v0200" schemalocation="suwiml-v0200-header.xsd"/> <!--Importeer de berichtspecifieke action-body.--> Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 25 van 103
<import namespace="http://www.suwi.nl/suwiml/bodyaction/uwvdossierpersoon-v0302" schemalocation="uwvdossierpersoon-v0302-b07-bodyaction.xsd"/> <!--SOAP envelope aangepast voor SuwiML.--> <element name="envelope" type="soap-env:envelope"/> <complextype name="envelope"> <sequence> <element name="header" type="soap-env:header"/> <element name="body" type="soap-env:body"/> </sequence> </complextype> <complextype name="header"> <sequence> <element ref="smlh:suwimlheader"> <!--Gedefinieerd in het SuwiML headerschema.--> </element> </sequence> </complextype> <complextype name="body"> <sequence> <element ref="smlb:suwimlbody"> <!--Gedefinieerd in het berichtspecifieke bodyschema.--> </element> </sequence> </complextype> </schema> Figuur 11: SOAP envelopeschema van een SuwiML Action berichtschema. Een XML Schema definieert een rootelement en haar subelementen. Het rootelement van het SuwiML bodyschema is altijd <SuwiMLBody>. Figuur 12, Figuur 14 en Tabel 4 tonen welke subelementen binnen het <SuwiMLBody> rootelement kunnen voorkomen. Welk subelement in een bepaalde situatie voor mag komen hangt af van en correspondeert met het interactietype (Action of Reaction) en het CommunicatieType en het CommunicatieElement in de SuwiML header. Figuur 12: SOAP envelopestructuur van een SuwiML Action berichtschema. Auteur: Paul Vriend, Dirk Temme SuwiML berichtstandaard v0201.doc - 26 van 103