Gebruik van STOP-schema's en schematrons

Inleiding

De implementatie van de standaard is vastgelegd in XML Schema Documents (XSD) en ISO Schematrons. De XML-schema's specificeren de structuur van de XML waarmee een STOP-module uitgewisseld moet worden. De schematrons implementeren de bedrijfsregels waaraan de informatie moet voldoen, voor zover die bedrijfsregels toegepast kunnen worden op de XML in afzondering. Bedrijfsregels die betrekking hebben op de samenhang tussen informatie in STOP modules zijn niet als schematron beschikbaar.

De wijze van implementatie en de locatie van de schema's en schematrons is geheel machineleesbaar gemaakt:

  • Het schemakoppeling.xml bestand geeft per STOP-module aan in welk schema de module is gedefinieerd, en in welke schematrons bedrijfsregels zijn opgenomen.

  • Het bestand verwijst naar de schema's en schematrons via een URL; de schema's en schematrons zijn van dit adres te downloaden. Als de STOP-schema's afhankelijk zijn van andere schema's, dan worden die ook via een URL gelokaliseerd.

  • Het is ook mogelijk alle gebruikte schema's en schematrons te downloaden. STOP levert catalogs waarin de relatie staat tussen de URL en de te downloaden bestanden.

  • Niet alle XML-gerelateerde software kan schematrons uitvoeren. Als service worden daarom ook vertalingen in XSLT van schematrons beschikbaar gesteld.

Schemakoppeling.xml

Het schemakoppeling bestand beschrijft de implementatie van de verschillende STOP-modules. Een voorbeeld van een STOP-module zoals vastgelegd in schemakoppeling.xml:

<Documenttype>
  <localName>ExpressionIdentificatie</localName>
  <namespace>https://standaarden.overheid.nl/stop/imop/data/</namespace>
  <implementatie>
    <Schema>
      <type>XML-schema</type>
      <locatie>https://standaarden.overheid.nl/stop/1.0.4/imop-data.xsd</locatie>
    </Schema>
    <Schema>
      <type>schematron</type>
      <locatie>https://standaarden.overheid.nl/stop/1.0.4/imop-aknjoin.sch</locatie>
    </Schema>
  </implementatie>
</Documenttype>

Het voorbeeld betreft de module Expression-identificatie dat in XML geïmplementeerd is via het ExpressionIdentificatie-element. Voor dit element gelden ook bedrijfsregels. In het schemakoppeling-bestand wordt de module geïdentificeerd via het XML element (localName en namespace). De implementatie staat in implementatie weergegeven.

Voor elke STOP module wordt één Schema met type XML-schema vermeld waarin het XML-element is gespecificeerd.

  • Als de STOP-module als een geheel XML-document wordt uitgewisseld dan kan het schema gebruikt worden om het XML-document te valideren.

  • Als de STOP-module wordt uitgewisseld als onderdeel van een XML-document (en dus niet het root element van het XML-document is), dan zal het schema dat het gehele XML-document beschrijft al het juiste schema importeren.

  • Als de STOP-module als geheel door een externe standaard wordt geïmplementeerd (bijvoorbeeld Symbology Encoding (SE) voor de GIO symbolisatie) dan wordt ofwel verwezen naar het externe schema, ofwel naar een STOP-specifieke uitgeklede versie van dat schema waarin alleen de toegestane elementen zijn opgenomen. Het is daarom van belang de schemakeuze op basis van het schemakoppeling bestand te maken en niet op basis van de XML namespace of het xsi:schemaLocation in de XML.

Als er bedrijfsregels geïmplementeerd zijn voor de STOP-module, dan zijn er één of meer Schema elementen met als type schematron. Deze wijzen naar de schematron waarin de bedrijfsregels zijn opgenomen. De schematrons moeten toegepast worden op elk (geheel) XML-document dat de STOP-module bevat. Dus niet alleen als het XML-element het root element van het XML document is, maar ook als het XML-element op een andere positie in het document voorkomt.

Vewerking van STOP-XML-documenten is alleen gegarandeerd als het document valide is ten opzichte van het XML-schema en de bedrijfsregels in de schematrons. De foutmeldingen uit XML-schema-validatie zijn afhankelijk van de gebruikte XML-parser en worden niet door STOP voorgeschreven. Als de XML niet aan de bedrijfsregels voldoet, dan resulteert het uitvoeren van een schematron in één of meer JSON-objecten, gescheiden door komma's (en met een komma aan het einde). Door de laatste komma weg te halen en [ ] er omheen te zetten ontstaat een valide JSON object-array. Voorbeeld van de uitkomst van een schematron:

  {
    "code": "STOP0005",
    "melding": "De alinea voor element Divisietekst met id content_o_1 bevat geen tekst. Verwijder de lege alinea",
    "ernst": "fout"
    "element": "Divisietekst",
    "eId": "content_o_1"
  },
  {
    "code": "STOP1000", 
    "melding": "De identifier /join/id/proces/pv30/2020/Instelling.Verordening bevat een punt. Dit is niet toegestaan. Verwijder de punt.",
    "ernst": "fout"
    "ID": "/join/id/proces/pv30/2020/Instelling.Verordening"
  },

Elk JSON-object in de validatieoutput heeft een veld code. Deze codes met de bijbehorend meldingen zijn opgesomd op het overzicht van de bedrijfsregels. De ernst geeft aan of het om een fout, waarschuwing of informatief gaat. De melding geeft een mensleesbare beschrijving die overeenkomt met de melding als beschreven in de bijbehorende bedrijfsregel en waarbij eventuele parameters zijn ingevuld. De overige attributen van het JSON object betreft de parameters zoals ze in de melding verwerkt zijn.

URL

Elk STOP-schema en schematron heeft een URL die voldoet aan het volgende patroon:

"https://standaarden.overheid.nl/stop/", [<schemaversie>, "/"], <schemanaam> 
  • https://standaarden.overheid.nl/stop/ is het domein waar de schema's beschikbaar worden gesteld. Deze locatie geeft nu een redirect naar het machineleesbare schema zoals deze is uitgeleverd op de STOP-gitlab-repository (middels raw)

  • <schemaversie> is het versienummer zoals gegeven in @schemaversie van de STOP-modules. Als deze niet wordt gebruikt in de URL, wordt verwezen naar de huidige, meest recente versie van het STOP-schema.

  • <schemanaam> is de bestandsnaam van het schema, inclusief extensie .xsd voor XML-schema of .sch voor schematrons

Bijvoorbeeld

  • https://standaarden.overheid.nl/stop/imop-tekst.xsd wijst naar de huidige versie van het tekst-schema

  • https://standaarden.overheid.nl/stop/1.0.4/imop-data.xsd verwijst naar versie 1.0.4 van het data-schema.

  • https://standaarden.overheid.nl/stop/1.0.4/imop-aknjoin.sch is de schematron waarin de bedrijfsregels rondom de naamgevingsconventie zijn opgenomen.

xsi:schemaLocation

Een URL volgens dit patroon kan worden gebruikt in een XML-document om het schema aan te wijzen waartegen het XML-document valideert. De XML Schema-standaard schrijft hier het gebruik van het attribuut @schemaLocation in de xsi-namespace voor.

De aanbevolen werkwijze is om de URL volgens bovenstaand patroon in dit attribuut @xsi:schemaLocation op te nemen. Omdat dit attribuut in de xsi:namespace "http://www.w3.org/2001/XMLSchema-instance" is gedefinieerd, moet deze namespace worden gedeclareerd als het attribuut wordt gebruikt. Het attribuut @xsi:schemaLocation bevat altijd één (of meer) door witruimte gescheiden "namespace-locatie-paren"; eerst de namespace, gevolgd door de locatie:

<?xml version="1.0" encoding="UTF-8"?>
<RegelingCompact 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="https://standaarden.overheid.nl/stop/imop/tekst/ 
                     https://standaarden.overheid.nl/stop/1.0.4/imop-tekst.xsd"
 xmlns="https://standaarden.overheid.nl/stop/imop/tekst/" 
 schemaversie="1.0.4">...</RegelingCompact> 

Nota bene

  • Het attribuut @xsi:schemaLocation MAG maar HOEFT niet ondersteund te worden door STOP-implementaties.

  • Het gebruik van relatieve paden (zoals ../stop/imop-tekst.xsd) of locale paden (zoals C:/STOP/xsd/imop-tekst.xsd) wordt AFGERADEN. Dit verlaagt de portabiliteit van de XML-bestanden.

  • Systemen die STOP-informatie ontvangen en willen valideren MOETEN de informatie uit schemakoppeling.xml gebruiken in plaats van @xsi:schemaLocation

Catalogs

In het schemakoppeling.xml bestand wordt naar schema's en schematrons verwezen via URLs. Het is niet altijd wenselijk om voor ieder gebruik een schema of schematron van het internet te downloaden. In de repository zijn naast de STOP schemata ook alle andere schema's verzameld.

Om een koppeling te leggen tussen de URL van schemata en de bestanden in de repository is een zogenaamde OASIS catalog nodig. Bij STOP wordt een aantal van deze catalogs bijgeleverd die alle relevante XSD/SCH-bestanden aanwijst.

Het formaat van deze catalogs is:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  ...
  <uri name="https://standaarden.overheid.nl/stop/1.0.4/imop-data.xsd" uri="imop-data.xsd"/>
  <uri name="https://standaarden.overheid.nl/stop/1.0.4/imop-aknjoin.sch" uri="imop-aknjoin.sch"/>
   ...
</catalog>

Elk uri element koppelt de URL van een schema of schematron (in het name attribuut) aan het bestand uit de repository, waarbij het uri attribuut het relatieve pad ten opzichte van de plaats van de catalogus vermeldt.

Vertalingen van schematrons

Een schematron is een standaard manier om in het XML-domein bedrijfsregels vast te leggen. Uitgebreidere XML-georiënteerde software kan een schematron direct uitvoeren.

Als dat niet het geval is, dan kan een schematron worden omgezet in een XSLT versie 2.0-transformatie volgens een standaard procedé. Als service worden bij STOP de XSLT2 transformaties uitgeleverd, inclusief catalog die de URL van de schematrons koppelt aan de XSLT-bestanden.

De STOP-schematrons en XSLT2 vertalingen zijn getest met Saxon Home Edition (aldaar vermeld als de Saxon HE editie), een open source XSLT/XQuery-implementatie.