GMN BCI Voorbeeldberichten

Voorbeeldberichten

Dit hoofdstuk bevat enkele voorbeeldberichten en van diverse onderdelen van de berichten een uitgebreide toelichting.

De eerste paragraaf beschrijft enkele voorbeeldberichten voor het registreren van nieuwe gegevens.

De tweede paragraaf beschrijft enkele voorbeeldberichten voor het corrigeren van geregistreerde gegevens.

De derde paragraaf bevat enkele XML-code snippets van interessante onderdelen die kunnen voorkomen in de BRO-verzoeken.

Registreren van gegevens

De volgende paragrafen beschrijven de beschikbare voorbeeldberichten, hun intentie en een summiere beschrijving van de inhoud.

De integrale voorbeeldberichten zijn te vinden op GMN Inname voorbeeldberichten in xml. 

01registrationRequestStartRegistration

Het voorbeeldbericht 01registrationRequestStartRegistration.xml bevat een registratieverzoek, waarmee de registratie van een nieuw registratieobject in de BRO wordt gestart.

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument. 

02registrationRequestMeasuringPoint

Het voorbeeldbericht 02registrationRequestMeasuringPoint.xml bevat een registratieverzoek, waarmee een meetpunt wordt toegevoegd aan een registratieobject dat al is opgenomen in de BRO. Het meetpunt speelt vanaf de eventDate (datum gebeurtenis) in het brondocument een rol binnen het meetnet. Het voorbeeldbericht borduurt voort op het voorbeeldbericht 01registrationRequestStartRegistration.xml.

NB 1: De combinatie van EventName (NaamGebeurtenis), eventDate (datum gebeurtenis) en measuringPointCode (meetpuntcode) moet uniek zijn binnen een registratieobject. Dit heeft tot gevolg er per meetpunt een GMN_MeasuringPoint (GMN-Meetpunt) brondocument in een registrationRequest (registratieverzoek) aangeboden moeten worden.

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument. 

03registrationRequestTubeReference

Het voorbeeldbericht 03registrationRequestTubeReference.xml bevat een registratieverzoek, waarmee van een meetpunt de actuele buisverwijzing wordt vervangen door een andere buisverwijzing. De vervangende buisverwijzingen vormt vanaf de eventDate (datum gebeurtenis) in het brondocument de monitoringbuis waarin een (de) gerelateerd(e) grondwaterstandonderzoek(en) en/of grondwatersamenstellingsonderzoek(en) uitgevoerd worden. Het voorbeeldbericht borduurt voort op de voorbeeldberichten 01registrationRequestStartRegistration.xml en 02registrationRequestMeasuringPoint.xml.

NB 1: De combinatie van EventName (NaamGebeurtenis), eventDate (datum gebeurtenis) en measuringPointCode (meetpuntcode) moet uniek zijn binnen een registratieobject. Dit heeft tot gevolg er per veranderende buisverwijzingen een GMN_TubeReference (GMN-Buisverwijzing) brondocument in een registrationRequest (registratieverzoek) aangeboden moeten worden.

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument. 

04registrationRequestMeasuringPointEndDate

Het voorbeeldbericht 04registrationRequestMeasuringPointEndDate.xml bevat een registratieverzoek, waarmee een meetpunt wordt beëindigd (buiten gebruik gesteld). Het meetpunten wordt vanaf de eventDate (datum gebeurtenis) in het brondocument niet meer gebruikt binnen de context van dit grondwatermonitoringnet. Het voorbeeldbericht borduurt voort op de voorbeeldberichten 01registrationRequestStartRegistration.xml en 02registrationRequestMeasuringPoint.xml.

NB 1: De combinatie van EventName (NaamGebeurtenis), eventDate (datum gebeurtenis) en measuringPointCode (meetpuntcode) moet uniek zijn binnen een registratieobject. Dit heeft tot gevolg dat per buiten gebruik gesteld meetpunt een GMN_MeasuringPointEndDate (GMN-EinddatumMeetpunt) brondocument in een registrationRequest (registratieverzoek) aangeboden moeten worden.

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument. 

05registrationRequestClosure

Het voorbeeldbericht 05registrationRequestClosure.xml bevat een registratieverzoek, waarmee de registratie van het gehele grondwatermonitoringnet wordt beëindigd.

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument. 

Gegevens corrigeren

Dit hoofdstuk bevat enkele voorbeeldberichten voor het corrigeren van bestaande gegevens (vervangen, verplaatsen, invoegen, verwijderen).

11replaceRequestStartRegistrationBronhouder

Het voorbeeldbericht 11replaceRequestStartRegistrationBronhouder.xml bevat een correctieverzoek, waarmee de waarde voor de bronhouder van een grondwatermonitoringnet wordt vervangen.

Het brondocument in dit replaceRequest vervangt het momenteel geregistreerde GMN_StartRegistration brondocument. Het voorbeeldbericht borduurt voort op het voorbeeldbericht 01registrationRequestStartRegistration.xml

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument. 

12replaceRequestStartRegistrationAspect

Het voorbeeldbericht 12replaceRequestStartRegistrationAspect.xml bevat een correctieverzoek, waarmee de waarde voor het groundwaterAspect (grondwateraspect) van een grondwatermonitoringnet wordt vervangen.

De waarde 'eigenCorrectie' van het attribuut correctionReason geeft aan dat de correctie is uitgevoerd op eigen initiatief van de bronhouder en/of dataleverancier en dus niet omdat het registratieobject in onderzoek is naar aanleiding van een terugmelding door een derde partij.

Het brondocument in dit replaceRequest vervangt het momenteel geregistreerde GMN_StartRegistration brondocument. Het voorbeeldbericht borduurt voort op het voorbeeldbericht 01registrationRequestStartRegistration.xml en het voorgaande correctie voorbeeldbericht.

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument. 

13replaceRequestStartRegistrationQualityRegime

Het voorbeeldbericht 13replaceRequestStartRegistrationQualityRegime.xml bevat een correctieverzoek, waarmee de waarde voor het qualityRegime (kwaliteitsregime) wordt vervangen. Merk op dat tegelijkertijd ook de waarden van andere attributen mogen worden aangepast, zodat de gegevens voldoen aan het IMBRO kwaliteitsregime, zoals in dit voorbeeld het attribuut startDateMonitoring.

Het brondocument in dit replaceRequest vervangt het momenteel geregistreerde GMN_StartRegistration brondocument. Het voorbeeldbericht borduurt voort op het voorbeeldbericht 01registrationRequestStartRegistration.xml en de voorgaande correctie voorbeeldberichten.

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument.

14moveRequestStartRegistration

Het voorbeeldbericht 14moveRequestStartRegistration.xml bevat een correctieverzoek, waarmee de startDateMonitoring (begindatum monitoring) van een grondwatermonitoringnet wordt gecorrigeerd, waardoor het punt op de tijdlijn van de materiële historie wordt verplaatst.

De waarde 'eigenCorrectie' van het attribuut correctionReason geeft aan dat de correctie is uitgevoerd op eigen initiatief van de bronhouder en/of dataleverancier en dus niet omdat het registratieobject in onderzoek is naar aanleiding van een terugmelding door een derde partij.

Het brondocument in dit replaceRequest vervangt het momenteel geregistreerde GMN_StartRegistration brondocument. Het voorbeeldbericht borduurt voort op het voorbeeldbericht 01registrationRequestStartRegistration.xml en de voorgaande correctie voorbeeldberichten.

Onderstaande figuur toont op hoofdlijnen de structuur van het registratieverzoek en het brondocument.

Code snippets.

Deze paragraaf bevat voor een aantal kleine, bijzondere stukken XML-code uit de voorbeeldberichten een gedetailleerde beschrijving.

De kop van een registrationRequest

De eerste regel van het voorbeeldbericht bevat de XML-proloog. Merk op dat de tekens volgens UTF-8 moeten worden gecodeerd. Dit is met name van belang voor speciale tekens, zoals à, á, ï.

Regel 2 t/m 9 bevatten de opening tag van het registrationRequest (registratieverzoek) als root XML-element en de namespaces van de gebruikte XML-schemadefinities (XSD's). De laatste twee XML-attributen (xmlns:xsi en xsi:schemaLocation) maken het mogelijk om het BRO-verzoek te valideren tegen de XSD-bestanden van de innamewebservice. Deze twee attributen mogen worden weggelaten. Regel 2 mag ook de opening tag van een replaceRequest(vervangverzoek), insertRequest (invoegverzoek), moveRequest (verplaatsverzoek) of deleteRequest (verwijderverzoek) zijn.

Na de disclaimer volgen vier transactiegegevens: requestReference (verzoekkenmerk), deliveryAccountableParty (bronhouder),broId(BRO-ID) en qualityRegime (kwaliteitsregime). Zie hoofdstuk 2 voor nadere informatie. Het attributbroID(BRO-ID) is bij eenregistrationRequest(registratieverzoek) niet toegestaan als hetsourceDocument(brondocument) een GMN_StartRegistrationis. Bij de andere types brondocumenten en bij de correctieverzoeken is dit attribuut verplicht.

Na de transactiegegevens volgt de opening tag van het sourceDocument (brondocument). Daarbinnen volgt het aan te bieden brondocument.

Het BRO-verzoek wordt afgesloten met de closing tags van het sourceDocument (brondocument) en het registrationRequest (registratieverzoek) c.q. het betreffende correctieverzoek.

<?xml version="1.0" encoding="UTF-8"?>
<ns1:registrationRequest 
        xmlns:ns="http://www.broservices.nl/xsd/brocommon/3.0" 
        xmlns:ns1="http://www.broservices.nl/xsd/isgmn/1.0" 
        xmlns:ns2="http://www.opengis.net/gml/3.2" 
        xmlns:xlin="http://www.w3.org/1999/xlink"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.broservices.nl/xsd/isgmn/1.0 https://schema.broservices.nl/xsd/isgmn/1.0/isgmn-messages.xsd"
    >
    <!-- Disclaimer: dit voorbeeldbericht valideert tegen de XSD van de innameservice.
         Het is niet gevalideert door de innamewebservice en is vaktechnisch/inhoudelijk niet voorbeeldig.
    -->
    <ns:requestReference>requestReference</ns:requestReference>
    <!--Optional:-->
    <!--ns:deliveryAccountableParty>27376655</ns:deliveryAccountableParty-->
    <!--Optional:-->
    <!--ns:broId>?</ns:broId-->
    <ns:qualityRegime>IMBRO</ns:qualityRegime>
    <!--Optional:-->
    <!--ns:underPrivilege>?</ns:underPrivilege-->
    <ns1:sourceDocument>
        ...
    </ns1:sourceDocument>
</ns1:registrationRequest>

Brondocument

Een BRO-verzoek bevat een brondocument. Een brondocument is de eenheid van aanleveren. De <<GMN>> innamewebservice kent meerdere types brondocumenten. Alle brondocumenten hebben het stereotype FeatureType.

Conform de GML XML encoding rules wordt voor de brondocumenten het property type pattern toegepast. Zie ook de paragraaf Property type pattern 26407089.

Onderstaand stukje XML van een voorbeeldbericht laat zien hoe dat uitpakt. Na de opening tag sourceDocument van het brondocument volgt een regel als tag de naam van het type brondocument, bijvoorbeeld GMN_StartRegistration. Deze regel geeft aan dat in dit bericht dat type brondocument is opgenomen. Het element GMN_StartRegistration is als root element gedefinieerd in het XSD-bestand isgmn-messages.xsd van de GMN innamewebservice. Na deze regel komt het eerste XML element van het brondocument.

Property type pattern

De GMN gegevenscatalogus maakt een onderscheid tussen objecttypes en gegevensgroeptypes. Bij de opstellen van de berichtdefinities worden deze stereotypes vertaald naar FeatureType en AttributeGroupType. Beide kunnen in software omgezet worden naar classes. Beide hebben attributen (attributes), gegevensgroepen (attributeGroups) of associations (relaties) naar andere Featuretypes als onderdelen. De verschillen zijn onder meer dat een Feature identificeerbaar is en dat een AttributeGroup alleen bestaat bij de gratie van het Feature waarvan het, direct of indirect, een onderdeel is.

Conform de GML XML encoding rules leidt ieder FeatureType in een XSD-bestand tot:

• Een complex type, wat de inhoud van het FeatureType definieert en direct of indirect een specialisatie is van gml:AbstractFeatureType.
• Een root element, zodat objecten van het ComplexType geïnstantieerd kunnen worden.
• Een property type ComplexType, wat in de XSD-bestanden gebruikt wordt als het type van een element dat fungeert als realisatie van de associatie relatie naar het FeatureType.

Als gevolg van de eerste bullet krijgt in een XML-bericht ieder XML-element met zo'n complex type als datatype een XML-attribuut gml:id. 

In een XML bericht heeft dit tot gevolg dat, bij bijvoorbeeld het XML-element measuringPoint (meetpunt), na de opening tag een tweede tag volgt, in dit geval MeasuringPoint (Meetpunt) met de naam van het type van het (gerelateerde) FeatureType (Objecttype) en een XML-attribuut gml:id. Daarna volgt de reeks van XML-elementen van het (gerelateerde) FeatureType (Objecttype), afgesloten met de closing tag van het (gerelateerde) FeatureType (Objecttype) en de closing tag van, in dit voorbeeld, het XML-element measuringPoint (meetpunt). Daardoor is voor een ontvangend systeem eenduidige bekend is hoe de inhoud geparsed moet worden. Voorbeeld:

    <ns1:measuringPoint>
        <ns1:MeasuringPoint ns2:id="id_0002">
            ...
        </ns1:MeasuringPoint>
    </ns1:measuringPoint>

gml:id

Conform de GML XML encoding rules krijgt ieder ieder XML-element, waarvan het datatype een specialisatie is van gml:AbstractFeatureType, een XML-attribuut gml:id.

De waarde van deze gml:id moet uniek zijn binnen het BRO-verzoek. In de voorbeeldberichten is dit gedaan met een waarde die begint met 'id_', gevolgd door een volgnummer.

Het BRO-systeem negeert het XML-attribuut gml:id en slaat de waarde ervan niet op.

Voorbeeld:

    <GMN_StartRegistration gml:id="id_0001">

Waarde uit een codelijst

Zie Codelist (Codelijst) voor een algemene beschrijving van het gebruik van codelijsten in de BRO.

Datum en DatumTijd

De waarde van een XML-element met als type een xs:Date (Datum) wordt gecodeeerd volgens de ISO-8601 standaard: yyyy-mm-dd. Bijvoorbeeld:

De waarde van een XML-element met als type een  xs:DateTime  (Datum) wordt ook gecodeeerd volgens de ISO-8601 standaard: yyyy-mm-ddThh:mm:ss+hh:mm. Daarbij is de tijdzone (+hh:mm) verplicht. De uren en minuten na het plus teken is de tijdzone ten opzichte van UTC (aka GMT). In theorie kan dit ook een min teken zijn (tijdzones ten westen van Greenwich), maar voor Nederland is de tijdzone + 1 uur (wintertijd) of + 2 uur (zomertijd). In het voorbeeld is de lokale tijd 09:01:52, terwijl het 'in Londen' 08:01:52 is. Bijvoorbeeld:

PartialDate

In de gegevenscatalogus hebben diverse gegevens een Datum onder kwaliteitsregime IMBRO en een OnvolledigeDatum onder IMBRO/A. In de XSD-bestanden is de OnvolledigeDatum gerealiseerd door het complexType PartialDateType. Deze ondersteunt 4 mogelijkheden met afnemende nauwkeurigheid:

• date (volledige datum)
• yearMonth (datum en jaartal)
• year (jaartal)
• voidReason (de vaste waarde 'onbekend').

Bijvoorbeeld:

Bij een PartialDate (OnvolledigeDatum) geldt dat binnen hetzelfde jaar (of jaar en maand) een minder volledige datum voorafgaat aan een meer volledige datum:

• het jaartal 2015 voor de datum en jaartal juli 2015
• de datum en jaartal juli 2015  gaat voor de volledige datum 17 juli 2015.

In het algemeen kan een datum met de waarde 'onbekend' niet worden vergeleken met een andere datum. Daarom wordt bij het toepassen van een regel, waarin twee datums met elkaar worden vergeleken waarvan één (of beide) de waarde 'onbekend' heeft, de bedrijfsregel genegeerd.

Uitzondering is het sorteren van gebeurtenissen op een tijdlijn. Daarbij wordt op basis van de betekenis van de gebeurtenis een begin/inrichten/start gebeurtenis altijd vooraan in de lijst met gebeurtenissen geplaatst, ook als de datum van de gebeurtenis de waarde 'onbekend' heeft. En wordt een eind/opruimen/voltooien gebeurtenis altijd achteraan in de lijst met gebeurtenissen geplaatst, ook als de datum van de gebeurtenis de waarde 'onbekend' heeft. Opdat een lijst met gebeurtenissen eenduidig kan worden gesorteerd, mag bij andere gebeurtenissen de datum van de gebeurtenis niet de waarde 'onbekend' hebben. Dit wordt expliciet als aanvullende regel vermeld bij de betreffende brondocumenten.