GAR Berichtencatalogus innamewebservice

Inleiding

Dit document beschrijft hoe een bronhouder en/of dataleverancier de gegevens over een grondwatersamenstellingsonderzoek (GAR) kan opnemen in een verzoek voor de Basisregistratie Ondergrond (BRO).

Het document veronderstelt dat de lezer bekend is met de GAR catalogus en het Bronhouderportaal. Nadere informatie is te vinden op www.basisregistratieondergrond.nl.

Het document veronderstelt dat de lezer beschikt over de kennis en vaardigheid om een XML-bestand te lezen en te schrijven.

De focus van het document ligt op het beschrijven van de structuur van de mogelijke berichten aan de hand van enkele voorbeelden. Andere zaken zoals definitie, kardinaliteit, domein en bedrijfsregels met betrekking tot de gegevensinhoud van de berichten staan in de catalogus. Vervolgstappen, zoals het valideren (testen), aanbieden en verwerken van een BRO-verzoek, staan beschreven in het Bronhouderportaal (zie www.basisregistratieondergrond.nl).

Leeswijzer

Hoofdstuk 2 beschrijft de algemene opbouw van een BRO-verzoek.

Hoofdstuk 3 bevat enkele voorbeeldberichten met regel voor regel een toelichting.

Hoofdstuk 4 bevat de toegestane waarden van de enumeraties (niet-beheerde lijsten met toegestane waarden).

Hoofdstuk 5 bevat verwijzingen (URN's en URL's) naar de codelijsten (beheerde lijsten met toegestane waarden).

Hoofdstuk 6 bevat een vertaaltabel, aan de hand waarvan, gegeven de Engelstalige naam van een entiteit of een attribuut, de Nederlandse naam in de catalogus kan worden opgezocht.

Versiehistorie

Contactinformatie

Algemene informatie, documentatie en voorbeeld XML-berichten kunt u vinden op www.basisregistratieondergrond.nl.

Heeft u een vraag over de BRO? Wij staan voor u klaar om u te helpen.

Of bel ons op telefoonnummer 088 - 8664 999. Wij zijn op werkdagen van 8.00 tot 17.00 uur bereikbaar.

BRO-verzoek

Dit hoofdstuk beschrijft de algemene opbouw van een BRO-verzoek. Een BRO-verzoek bestaat uit een brondocument verpakt in een 'request'. Paragraaf 2.1 beschrijft de verschillende requests van de GAR innamewebservice. Paragraaf 2.2 beschrijft de verschillende brondocumenten die in een GAR requests opgenomen kunnen worden. 

Requests

Om gegevens te registreren in de Landelijke Voorziening BRO (LV BRO) moet u deze aanleveren bij het Bronhouderportaal in de vorm van een BRO-verzoek (zie basisregistratieondergrond.nl).

Vervolgens is het BRO-verzoek het bestand in IMBRO/XML-formaat dat het BRO-brondocument bevat en als verzoek wordt aangeboden in het Bronhouderportaal.

De GAR innamewebservice ondersteunt twee soorten requests.  Zie onderstaande tabel.

Paragraaf 2.1.1 beschrijft in detail de opbouw van een registrationRequest. Paragraaf 2.1.2 beschrijft op dezelfde manier een correctionRequest.

RegistrationRequest

Met een  registrationRequest (registratieverzoek) wordt een nieuw registratieobject toegevoegd aan de BRO. Het grondwatersamenstellingsonderzoek is een registratieobject zonder geschiedenis en het registreren is een eenmalige gebeurtenis.

Een registrationRequest (registratieverzoek) bestaat uit enkele transactiegegevens en een brondocument.  De definities van de transactiegegevens staan in onderstaande tabel:

Een registrationRequest (registratieverzoek) bestaat uit enkele transactiegegevens en een brondocument. De definities van de transactiegegevens staan in onderstaande tabel:

CorrectionRequest

Met een correctionRequest (correctieverzoek) kan de dataleverancier een registratieobject in één keer corrigeren. Het is niet mogelijk een deel van een GAR registratieobject te corrigeren.

Een correctionRequest (correctieverzoek) bestaat uit enkele transactiegegevens en vooral een brondocument. De definities van de transactiegegevens staan in onderstaande tabel :

Een correctionRequest (correctieverzoek) bestaat uit enkele transactiegegevens en vooral een brondocument. De definities van de transactiegegevens staan in onderstaande tabel :

Brondocumenten

Een brondocument bevat de gegevens die geregistreerd worden in de LV BRO. Voor elk registratieobject staat in de bijbehorende catalogus waar die gegevens aan moeten voldoen.

Een brondocument wordt verpakt in een 'request'.  Vervolgens wordt het geheel als een bestand in IMBRO/XML-formaat in de vorm van een BRO-verzoek aangeboden in het Bronhouderportaal.

De GAR innamewebservice kent één type brondocument; zie onderstaande tabel. Met dit brondocument wordt het GAR registratieobject in één keer in zijn geheel vastgelegd of gecorrigeerd. De gegevens in het brondocument zijn gedefinieerd in de catalogus. De catalogus definieert ook gegevens die door het BRO-systeem worden gegenereerd of afgeleid; deze gegevens hoeven niet worden opgenomen in een brondocument.

De gegevens in het GAR brondocument zijn volledig gedefinieerd in de gegevenscatalogus. Het GAR brondocument bevat alle gegevens uit de gegevenscatalogus met uitzondering van de volgende gegevens:

• Attribuut  broId  (BRO-ID). Deze wordt niet opgenomen in het brondocument maar in het BRO-verzoek, behalve bij het registrationRequest  (registratieverzoek) want dan genereert de BRO een waarde voor dit gegeven.
• Attribuut  deliveryAccountableParty  (bronhouder). Deze wordt niet opgenomen in het brondocument maar in het BRO-verzoek.
• Attribuut deliveryResponsibleParty  (dataleverancier). Deze wordt niet opgenomen in het brondocument maar in de SOAP header van het bericht.
• Attribuut  qualityRegime  (kwaliteitsregime). Deze wordt niet opgenomen in het brondocument maar in het BRO-verzoek.
• Entiteit  RegistrationHistory  (Registratiegeschiedenis), wordt afgeleid door de BRO.

De structuur van een GAR brondocument wordt weergegeven in onderstaande figuur. Het begint met twee attributen objectIdAccountableParty (object-ID bronhouder) en qualityControlMethod (beoordelingsprocedure), een optionele lijst met relaties naar een GroundwaterMonitoringNet (Grondwatermonitoringnet) en één relatie naar een GroundwaterMonitoringTube (GMW-monitoringbuis; een buis in een GroundwaterMonitoringWell (GMW; grondwatermonitoringput)). Daarna volgen twee bomen met gegevens voor het  fieldResearch (veldonderzoek) en het  laboratoryAnalysis (laboratoriumonderzoek).

N.B. In de gegevenscatalogus is de relatie vanuit GAR naar GMN verplicht. In een werkafspraak is besloten dat in eerste instantie, tijdens het registreren van de gegevens over een grondwatersamenstellingsonderzoek met een registrationRequest (registratieverzoek), de koppeling met het GMN achterwege gelaten mag worden (de kardinaliteit is 0..*) en dat deze op een later moment door middel van een correctionRequest (correctieverzoek) alsnog gemaakt wordt.

N.B. De attributen  samplingoperator (uitvoerder veldonderzoek) en responsibleLaboratory (uitvoerder laboratoriumonderzoek) zijn verplicht in het GAR brondocument. Deze attributen hebben een kardinaliteit 0..1 omdat het FieldResearch (Veldonderzoek) en  LaboratoryAnalysis (Laboratoriumonderzoek) gemeenschappelijk gebruikt worden door de innamewebservice en de uitgiftewebservice. In de uitgiftewebservice worden deze attributen niet uitgeleverd als de aanvrager niet de bronhouder en/of dataleverancier is van het uitgegeven registratieobject.

Voorbeeldberichten

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

Integrale voorbeeldberichten

De integrale voorbeeldberichten zijn te vinden op <<GMN voorbeeldberichten>>.  De onderstaande tabel bevat een opsomming van beschikbare voorbeeldberichten, hun intentie en een summiere beschrijving van de inhoud.

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 8 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<<correctionRequest (correctieverzoek)>>zijn.

Na de disclaimer volgen vier transactiegegevens: requestReference (verzoekkenmerk), deliveryAccountableParty (bronhouder),  broId  (BRO-ID) en qualityRegime (kwaliteitsregime). Zie hoofdstuk 2 voor nadere informatie. Het attribut  broID  (BRO-ID) is bij een  registrationRequest  (registratieverzoek) van de GAR innamewebservice niet toegestaan . Bij   een correctionRequest (correctieverzoek) 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<<correctionRequest(correctieverzoek)>>.

<?xml version="1.0" encoding="UTF-8"?>
<registrationRequest 
        xmlns="http://www.broservices.nl/xsd/isgar/1.0" 
        xmlns:garcom="http://www.broservices.nl/xsd/garcommon/1.0" 
        xmlns:brocom="http://www.broservices.nl/xsd/brocommon/3.0" 
        xmlns:gml="http://www.opengis.net/gml/3.2" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.broservices.nl/xsd/isgar/1.0 https://schema.broservices.nl/xsd/isgar/1.0/isgar-messages.xsd">
	<brocom:requestReference>TestCase1</brocom:requestReference>
    <!--Optional:-->
    <brocom:deliveryAccountableParty>27376655</brocom:deliveryAccountableParty>
    <!--Optional:-->
    <brocom:broId>BHR000000342106</brocom:broId>
	<brocom:qualityRegime>IMBRO/A</brocom:qualityRegime>
	<sourceDocument>
        ...
	</sourceDocument>
</registrationRequest>

Brondocument

Een BRO-verzoek bevat een brondocument. Een brondocument is de eenheid van aanleveren. De<<GAR>>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.

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 GAR. Deze regel geeft aan dat in dit bericht dat type brondocument is opgenomen. Het element GAR is als root element gedefinieerd in het XSD-bestand isgar-messages.xsd van de GAR innamewebservice. Na deze regel komt het eerste XML element van het brondocument.

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 xs:Date  (Datum) wordt gecodeeerd volgens de ISO-8601 standaard: yyyy-mm-dd. Bijvoorbeeld:

De waarde van een XML-element met als type xs:DateTime  (DatumTijd) 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:

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. Zie ook de paragraaf Property type pattern.

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.

Meetwaarde

De gegevenscatalogus definieert een aantal gegevens als een meetwaarde. Deze bestaan uit een getalswaarde en een eenheid.

In de XSD-bestanden hebben de betreffende XML-element een type  gml:Measure. Conform de  GML XML encoding rules  wordt de eenheid opgeslagen in het XML-attribuut  uom  (unit of measure; eenheid). Als een gegeven van het type meetwaarde geen waarde heeft, dan wordt er een XML-attribuut  xsi:Nil="true" opgenomen en heeft het XML-element geen waarde. Ook het XML attribuut  uom  (eenheid) wordt dan niet opgenomen. Hierin verschilt GAR van andere registratieobjecten in de BRO. Zie onderstaande voorbeelden voor een meetwaarde met en zonder een waarde.

Merk op dat in de gegevenscatalogus (in de meeste gevallen) naast de afkorting ook tussen haakjes de voluitgeschreven naam van de eenheid is opgenomen, bijvoorbeeld: Eenheid: m (meter) . Alleen de afkorting volgens de UCUM lijst moet worden opgenomen in het BRO-verzoek.

Organisatie

De gegevenscatalogus definieert een aantal uitvoerders. Deze hebben een  Organization  (Organisatie) als gegevenstype.

Het gegevenstype  Organization  (Organisatie) biedt de keuze tussen een kamer van koophandel   nummer of een Europees handelsnummer als identificatie van een organisatie. Hieronder twee voorbeelden:

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 gaat 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.

Property type pattern

De GAR 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 monitoringPoint (meetpunt) na de opening tag een tweede tag volgt, in dit geval GroundwaterMonitoringTube (GMW-monitoringbuis) 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 monitoringPoint (meetpunt). Daardoor is voor een ontvangend systeem eenduidige bekend is hoe de inhoud geparsed moet worden. Voorbeeld:

<monitoringPoint>
    <garcom:GroundwaterMonitoringTube gml:id="GMW123456789012_0003">
        ...
    </garcom:GroundwaterMonitoringTube>
</monitoringPoint>

Enumeraties

Dit hoofdstuk bevat de toegestane waarden van de enumeraties (niet-beheerde waardenlijsten).

In de BRO wordt een onderscheid gemaakt tussen beheerde waardenlijsten en niet-beheerde waardenlijsten. In de catalogus en de XSD-bestanden noemen we een niet-beheerde waardenlijst een enumeratie. Bij een enumeratie staat de lijst met toegestane waarden vast en kan de lijst met toegestane waarden niet veranderd worden zonder aanpassingen in de catalogus, de berichtdefinities (XSD-bestanden) en de software (voor het maken of verwerken van een bericht).

De onderstaande tabel geeft een overzicht van de enumeraties die van belang zijn bij het maken van een BRO-verzoek over een grondwatersamenstellingsonderzoek. De eerste kolom bevat de Engelstalige naam van de enumeratie, zoals deze voorkomt in de XSD-bestanden. De tweede kolom bevat de Nederlandstalige naam, zoals die voorkomt in de catalogus. De derde kolom bevat de toegestane waarden, die gebruikt mogen worden in een BRO-verzoek.

Codelijsten

Dit hoofdstuk bevat verwijzingen (URN's en URL's) naar de codelijsten (beheerde waardenlijsten). Zie  Codelist (Codelijst)  voor een algemene beschrijving van het gebruik van codelijsten in de BRO.

De onderstaande tabel geeft een overzicht van de codelijsten die van belang zijn bij het maken van een BRO-verzoek over een grondwatersamenstellingsonderzoek. De eerste kolom bevat de Engelstalige naam van de codelijst, zoals deze voorkomt in de XSD-bestanden. De tweede kolom bevat de Nederlandstalige naam, zoals die voorkomt in de catalogus. De derde kolom bevat de URN, die gebruikt moet worden in een BRO-verzoek. De vierde kolom bevat een link naar de website waar de actuele lijst met toegestane waarden is te raadplegen.

Vertaaltabel

Dit hoofdstuk bevat een vertaaltabel, aan de hand waarvan, gegeven de Engelstalige naam van een entiteit of een attribuut, de Nederlandse naam in de catalogus kan worden opgezocht.

De onderstaande tabel is gesorteerd op alfabetische volgorde van de Engelstalige naam van de entiteit. Tussen haakjes staat het type modelelement van de entiteit. Binnen een entiteit zijn de attributen gesorteerd op Engelstalige naam.