XML-schema's

Inleiding

Op deze pagina staan de XML-schema's van:

• de lijsten die door MedMij Beheer aan Bron en Uitgever voor uiteenlopende doelen ter beschikking worden gesteld;
• de rapporten die door Deelnemers moeten kunnen worden opgeleverd;
• de Catalogus.

De XML-schema's zijn een implementatie van de relevante logische modellen in XML-syntax en vervullen daarom de rol van technisch model. XML past bij de hiërarchische structurering waarop al in de logische modellen is ingezet. 

Net als op het conceptuele niveau van het metamodel en op het logisch niveau van het logische model, verschijnen op het technische niveau ook invarianten. XML is zelfs in staat om sommige van die invarianten geautomatiseerd te controleren. In zulke XML-validatie wordt gecontroleerd of een zeker XML-bestand voldoet aan de structuur van een zeker XML-schema. Ook het MedMij Afsprakenstelsel maakt van deze gelegenheid gebruik door van ontvanger van de vier lijsten te eisen zo'n validatie uit te voeren. De XML-schema's daarvoor worden als onderdeel van het MedMij Afsprakenstelsel beschikbaar gesteld. Deze validatie biedt extra zekerheid over de juistheid van de verspreide lijsten en draagt zo bij aan de betrouwbaarheid van het functioneren van het MedMij-netwerk.

Toch zijn er nog verschillende manieren om het logische model van de lijsten in hun XML-schema's te vertalen. In het MedMij Afsprakenstelsel zijn daarbij de volgende afwegingen gebruikt:

• Alle typen en elementen die worden gebruikt voor een van de lijsten of rapporten, zijn in het XML-schema van de betreffende lijst of het betreffende rapport gedefinieerd. Er is dus geen gebruik gemaakt van een basisschema. Zo wordt de afhankelijkheid tussen de XML-schema's beperkt en wordt het gemakkelijker een van de schema's aan te passen zonder dat de andere schema's gewijzigd worden. De definities moeten echter blijven passen bij het metamodel en het logische model; een aanpassing in een van deze modellen maakt aanpassing noodzakelijk van alle XML-schema's die door de wijziging geraakt worden.
• Bij het logische model van de lijsten en rapporten horen vier technische componenten. De hoogste klasse van elke component wordt het rootelement van het betreffende XML-schema. De attributen van de abstracte klassen bovenaan (MedMijBeheerlijst en MedMijRapport) worden over de technische modellen van de vier lijsten, respectievelijk de twee rapporten, verspreid. Er is dus voor elke lijst of rapport een apart XML-schema. Daardoor is de homonymie van Gegevensdienst en Gegevensdiensten geen probleem meer en kunnen in de namen de achtervoegsels _ZAL, _GNL,  _OCL, _BR en _PR achterwege blijven.
• De Catalogus vormt kent een zelfstandig logisch model. De klasse Catalogus uit het logisch model dient als root element van het XML-schema van de Catalogus.
• Net als in de stap van het metamodel naar de logische modellen blijft de granulariteit van de klassen hetzelfde: er worden geen klassen samengenomen om een compacter schema te maken.
• Alle klassen en attributen uit het logische model zijn gemodelleerd als elementen in het XML-schema. Daarmee is een eenduidige vertaling mogelijk van het logische model; er behoeft geen onderscheid tussen elementen en attributen te worden aangebracht. Elementen bieden meer mogelijkheden dan attributen en genieten daarom (als generieke keuze) de voorkeur.

Schema's

Alleen de hierboven genoemde bestanden, met de aangegeven release en versie, mogen worden gebruikt in deze release van het MedMij Afsprakenstelsel.

Voorbeeldbestanden

Van elke lijst is een voorbeeldbestand beschikbaar. Dit bestand maakt geen deel uit van de formele specificaties van het MedMij Afsprakenstelsel. De Catalogus kent geen voorbeeldbestand.

Tijdaspect

Het metamodel en de logische modellen, met hun invarianten, werken "door de tijd". Zij beschrijven hoe de klassen samenhangen op elk moment. De XML-bestanden voor de lijsten zijn echter specifieke momentopnames van de instanties van de klassen. Er moet daarom een tijdselement worden toegevoegd om lijsten die op verschillende momenten zijn gegenereerd, uit elkaar te kunnen houden, en om in retrospectief de geldigheidstermijn van een lijst te kunnen vaststellen.

• Elk XML-bestand kent een versie-aanduiding. Hiertoe wordt de combinatie van een Volgnummer en een Tijdstempel gebruikt. Hiermee wordt aan drie informatiebehoeften tegemoet gekomen:
  • Wanneer twee lijsten (van hetzelfde type) met opeenvolgende Volgnummers beschikbaar zijn, kan de geldigheidstermijn van de oudere lijst worden vastgesteld. Dat helpt bij de interpretatie van audit logs of foutopsporing.
  • Lijsten kunnen uniek worden geïdentificeerd. Dit kan aan de hand van Volgnummer of Tijdstempel, waarbij Volgnummer voor menselijke gebruikers vaak de meest intuïtieve zal zijn.
  • Per lijst kan worden nagegaan wanneer de laatste mutatie heeft plaatsgevonden. Dit zal in de regel een 'functionele' mutatie betreffen, geen foutherstel. Hieruit kan door vergelijking van opeenvolgende versies worden afgeleid wanneer de actuele lijst voor het laatst is gewijzigd; dat kan zinvol zijn bij het beoordelen van de effecten van changes of bij foutopsporing.
• Tijdstempel bestaat uit Datum, Tijd en Tijdzone-aanduiding, gebaseerd op xs:dateTime-type. Door voor een native XML-datatype te kiezen, wordt de implementatie vergemakkelijkt. Er geldt wel een restrictie op het element, dat afdwingt dat er altijd een Tijdzone-aanduiding wordt meegegeven.
• Voor de Catalogus geldt een uitzondering, en wordt gebruikgemaakt van een uitdrukking van de lokale Nederlandse datum (xs:date-type zonder tijdzone-aanduiding).

Releasebeheer

De bestandsnamen van de XML-schema's en XML-voorbeeldbestanden zijn zo gekozen dat zij niet wijzigen wanneer de inhoud van het XML-schema wijzigt. Dit vergemakkelijkt de implementatie van changes. Het is gebruikelijk om meta-informatie niet in de bestandsnaam op te nemen, maar in de XML-bestanden zelf (met name in de header). Daarom is het niet nodig om naast de informatie in het bestand, ook de bestandsnaam in te zetten voor versie-aanduiding.

Elk van de XML-schema's kent een eigen releasenummering. Zij kunnen daarmee onafhankelijk van elkaar worden aangepast. Daarmee wordt onnodige implementatielast bij een wijziging voorkomen. Het releasenummer is een geheel getal, om redenen van eenvoud. Altijd en alleen indien een XML-schema is gewijzigd, wordt het releasenummer met één opgehoogd.

De XML-schema's zijn integraal onderdeel van het afsprakenstelsel. Een wijziging van de XML-schema's leidt dan ook tot een nieuwe release van het afsprakenstelsel. Omgekeerd hoeft het niet zo te zijn dat een wijziging in de overige afspraken binnen het afsprakenstelsel, een wijziging van het XML-schema noodzakelijk maakt.

Omdat een wijziging in een XML-schema al snel tot incompatibiliteit met andere versies leidt (XML-bestanden die gebaseerd zijn op verschillende versies van het XML-schema zullen niet door het 'andere' XML-schema worden gevalideerd), is ervoor gekozen om het releasenummer op te nemen in de aanduiding van de namespace. Daarmee draagt een XML-bestand in de verwijzing naar de namespace tevens het releasenummer in zich. Zo wordt geborgd dat XML-bestanden niet met een verkeerde versie van het XML-schema worden gevalideerd.

De XML-schema's en de voorbeeld-XML-bestanden krijgen daarnaast een versienummer mee. Het versienummer is een geheel getal en wordt bij elke wijziging in het bestand met één opgehoogd. Met behulp van versienummering kunnen bestandsversies gedurende de ontwikkeling uit elkaar worden gehouden. Het nummer is ook aanwezig in productieversies; het is daarmee niet noodzakelijk om bij een statuswijziging van een release van het MedMij Afsprakenstelsel de XML-producten aan te passen, ook als die inhoudelijk niet gewijzigd zijn. Het versienummer wordt opgenomen als commentaar in het bestand, omdat dat niet machine-leesbaar hoeft te zijn en er op deze manier een eenduidige systematiek bestaat voor de XML-schema's en de XML-voorbeeldbestanden. Het commentaar heeft de vorm: <!--File version: [versienummer]--> en bevindt zich op de tweede regel van een bestand. De versienummering is, om redenen van eenvoud en duidelijkheid, onafhankelijk van de releasenummering van de XML-schema's.

Namespaces

Voor de aanduiding van namespaces wordt gebruikgemaakt van een URL. Dit is de gemakkelijkste optie, omdat dit - anders dan bij een URN - geen namespaceregistratie bij IANA vereist. De namespace-URL kent de volgende opbouw: xmlns://afsprakenstelsel.medmij.nl/[naamLijst|naamRapport|"catalogus"]/release[releasenummer] .

• Een namespace-URL gebruikt xmlns:// als schema-aanduiding. Daarmee wordt duidelijk gemaakt dat het slechts een identificatie betreft, en dat de URL niet is bedoeld voor dereferencing (bijvoorbeeld om het XML-schema te downloaden).
• Het domein afsprakenstelsel.medmij.nl is een unieke hostname op het internet. Gebruik daarvan biedt zowel voldoende herkenbaarheid als uniciteit.
• De naamLijst kent één van de volgende waarden: Whitelist, OAuthclientlist, Zorgaanbiederslijst of Gegevensdienstnamenlijst.
• De naamRapport kent één van de volgende waarden: Beheerrapport of Portabiliteitsrapport.
• De aanduiding release is toegevoegd voor de menselijke leesbaarheid en daarmee duidelijkheid.

Waar het metamodel geen namen heeft gedefinieerd, kiezen we om redenen van consistentie en elegantie voor lowercase in de opbouw van de URL. Er wordt gebruikgemaakt van elementFormDefault = "qualified". Dit vergroot de leesbaarheid van de XML-schema's omdat er geen prefixes nodig zijn bij het definiëren van elementen, en doet niet af aan enige functionaliteit. 

Syntactische keuzes

De XML-schema's gaan uit van XML 1.0 en XML Schema 1.0 (opgebouwd uit specificaties aangaande structuur en datatypes). Deze versies bieden voldoende functionaliteit en kennen een zeer brede implementatie en ondersteuning.

De bestandsnaam van een XML-schema kent de opbouw MedMij_[naamLijst].xsd. De variabele naamLijst betreft één van de volgende waarden: Whitelist, OAuthclientlist, Zorgaanbiederslijst of Gegevensdienstnamenlijst.

De XML-schema's bevatten de XML Declaration <?xml version="1.0" encoding="UTF-8"?>. De aanwezigheid van een declaratie wordt aanbevolen door XML 1.0. De encoding is optioneel bij het gebruik van UTF-8. De encoding is echter toch expliciet omdat dit mogelijke onzekerheid over de bedoeling of het correct volgen van de specificaties voorkomt. Er wordt geen gebruik gemaakt van het pseudo-attribuut standalone, omdat er gebruik gemaakt wordt van XML-schema's in plaats van DTD's.

Omwille van de leesbaarheid zijn de XML-schema's pretty-printed; door het gebruik van regeleinden en inspringing wordt de leesbaarheid vergroot. Verder kent elk XML-schema een standaardvolgorde in haar opbouw:

• Het rootelement, voorafgegaan door de commentaartekst <!--Rootelement-->.
• De definitie van de logische klassen, voorafgegaan door de commentaartekst <!–Logische klassen-->.
• De definitie van de basisklassen, voorafgegaan door de commentaartekst <!--Basisklassen-->.

De volgorde waarin de klassen worden gedefinieerd is hierbinnen vrij.

De XML-schema's bevatten geen Byte Order Mark. Het gebruik van een Byte Order Mark is volgens XML 1.0 optioneel bij UTF-8. RFC 3629, hoofdstuk 6, stelt dat het Byte Order Mark verboden moet worden, daar waar UTF-8 verplicht wordt gesteld.