GPD Berichtencatalogus uitgiftewebservice

1. Inleiding

1.1. Voorwoord

Betrouwbare en toegankelijke informatie over de samenstelling en opbouw van de ondergrond is van groot belang voor een dichtbevolkt land als het onze. Het helpt overheden, bedrijven en burgers om op feiten gebaseerde beslissingen te nemen over het gebruik van de ondergrond, bijvoorbeeld in verband met bereikbaarheid, waterveiligheid, warmte- en koudeopslag, aardgasproductie en de winning van aardwarmte. Ook voorkomen we zo dat informatie dubbel moet worden ingewonnen omdat het niet centraal is geregistreerd.
Het verzamelen, beschikbaar stellen, en gebruiken van al deze informatie is sinds september 2015 wettelijk vastgelegd in de Basisregistratie Ondergrond (BRO). Op 1 januari 2018 is het eerste deel van de Wet BRO in werking getreden, op 1 januari 2020 het tweede deel, op 1 januari c.q. 1 juli 2021 het derde deel en op 1 januari c.q. 1 juli 2022 het vierde deel.
Omdat de BRO een onderdeel is van het Stelsel van Basisregistraties, zijn verplichtingen met betrekking tot aanlevering, gebruik, terugmelding en onderzoek in de werkprocessen van overheidsorganisaties opgenomen in de Wet BRO. De BRO-gegevens worden centraal geregistreerd in de Landelijke Voorziening BRO (LV-BRO).

1.2. Doelstelling

Het document Handreiking Afname BRO Gegevens beschrijft via welke uitgiftekanalen BRO-gegevens geraadpleegd of gedownload kunnen worden en welke functionele en technische mogelijkheden deze kanalen bieden. Onder de noemer 'BRO uitgifte API' vallen dan in het bijzonder de 'REST uitgifteservice' en de 'SOAP webservice'. Functioneel gezien lijken deze twee uitgifteservices veel op elkaar.

• De REST service is met name handig om als software ontwikkelaar 'incidenteel even snel en alleen publieke gegevens' op te halen uit de LV-BRO, zonder dat je je eerst moet aanmelden en zonder dat een PKIoverheid certificaat nodig is.

• De SOAP webservice is met name geschikt om frequent en volledig geautomatiseerd in een machine-to-machine omgeving toegang te hebben tot alle beschikbare gegevens. Hiervoor moet je je aanmelden en heb je een PKIoverheid certificaat nodig.

Blijft over de vraag: hoe zien de uitgifteverzoeken en hun antwoorden er uit om gegevens over een formatieweerstandonderzoek (FRD) op te vragen en wat is de structuur van de diverse uitgiftedocumenten?

1.3. Doelgroepen

Doelgroepen voor dit document zijn organisaties en personen die aan de afnamekant van de BRO opereren, waaronder bestuursorganen (bestuurders, beleidsmakers, BRO-coördinatoren) en bedrijven (ingenieurs, software-leveranciers).

1.4. Samenhang met andere documentatie

De informatievoorziening over de afname van BRO-gegevens vindt plaats op 3 niveaus.

1. Het startpunt met algemene informatie over de diverse uitgiftekanalen is het document Handreiking Afname BRO Gegevens. Dit document verwijst door naar het volgende niveau.

2. Het tweede niveau bevat algemene informatie per uitgiftekanaal (zie https://basisregistratieondergrond.nl/inhoud-bro/aanleveren-opvragen/gegevens-opvragen/):

   1. De handleiding van de REST uitgifteservice is te vinden op https://www.bro-productomgeving.nl/bpo/latest/informatie-voor-softwareleveranciers/url-s-publieke-rest-services

   2. Algemene informatie over de SOAP webservice is te vinden op https://basisregistratieondergrond.nl/inhoud-bro/aanleveren-opvragen/instructies/gegevens-opvragen-via-soap-webservices/De handleiding voor het inrichten van SoapUI in het bijzonder is te vinden op https://basisregistratieondergrond.nl/inhoud-bro/aanleveren-opvragen/instructies/gegevens-opvragen-via-soap-webservices/aansluiten-demo-omgeving-soapui/

3. Het derde niveau is de BRO Productomgeving. Hier vindt u specifieke informatie per domein/registratieobjecttype zoals scopedocument, gegevenscatalogus en werkafspraken, storymap, berichtencatalogi voor inname en uitgifte, voorbeeldberichten voor inname en uitgifte.

Het verdient aanbeveling dat u zich eerst bekend maakt met de aangeven informatie uit de eerste 2 niveau's.
Daarna kunt u zich verdiepen in de GPD-specifieke informatie in de BRO productomgeving, waaronder de GPD gegevenscatalogus en eventuele werkafspraken en in het bijzonder dit document, de GPD berichtencatalogus uitgiftewebservice.

1.5. Leeswijzer

Hoofdstuk 2 beschrijft de algemene werking van de GPD uitgiftewebservice.
Hoofdstuk 3 beschrijft de structuur van de diverse uitgiftedocumenten.
Hoofdstuk 4 bevat een toelichting op enkele voorbeeldberichten.
Hoofdstuk 5 bevat de toegestane waarden van de enumeraties (niet-beheerde lijsten met toegestane waarden).
Hoofdstuk 6 bevat verwijzingen (URN's en URL's) naar de codelijsten (beheerde lijsten met toegestane waarden).
Hoofdstuk 7 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.

1.5.1. Versiehistorie

1.5.2. Contactinformatie

Algemene informatie en documentatie over de BRO kunt u vinden op https://basisregistratieondergrond.nl/.
Heeft u een vraag over de BRO? Wij staan voor u klaar om u te helpen. Voor vragen, suggesties of opmerkingen kunt contact opnemen met de BRO Servicedesk via een mail naar  support@broservicedesk.nl .
Of bel ons op telefoonnummer 088 - 8664 999. Wij zijn bereikbaar op werkdagen van 8.00 tot 17.00 uur.

2. Algemene werking van de GPD uitgiftewebservice

Dit hoofdstuk beschrijft de algemene werking van de GPD uitgiftewebservice.
Paragraaf 2.1 beschrijft de operaties die de GPD uitgiftewebservice ondersteunt.
Paragraaf 2.2 beschrijft de BRO-berichten (request en response) die een rol spelen bij die operaties.

2.1. Operaties

De GPD uitgiftewebservice wordt gerealiseerd als een SOAP-webservice. De onderstaande figuur beschrijft de operaties van de webservice, hun requests en hun responses.

• dispatchData (uitgifte van objectgegevens).

De soap operatie heeft een request en een response:

• Het DispatchDataRequest (Verzoek tot uitgifte van objectgegevens) en de DispatchDataResponse (Bericht van verzending van objectgegevens).

Naast een functioneel antwoord (een bericht van verzending) kan een verzoek ook leiden tot een foutmelding:

• SOAP:Fault (Systeemfout): als er tijdens de verwerking van het uitgifteverzoek een onverwachte fout optreedt in het BRO-systeem, dan leidt dit tot een SOAP:Fault.

• ParseFault (Validatiefout): als de uitgiftewebservice constateert dat een uitgifteverzoek niet een welgevormd XML-bericht is of dat het niet voldoet aan de XSD-schemavalidatie, dan leidt dit tot een ParseFault.

2.2. BRO-berichten

Deze paragraaf beschrijft de verschillende BRO-berichten (request, response en foutmeldingen) die een rol spelen in de GPD uitgiftewebservice.

2.2.1. DispatchDataRequest

Het BRO-bericht DispatchDataRequest bevat het uitgifteverzoek tot het leveren van de in het BRO-register opgenomen gegevens van een bepaald registratieobject. Daarbij wordt het registratieobject geïdentificeerd door zijn BRO-ID. Het DispatchDataRequest (Verzoek tot uitgifte van objectgegevens) van de GPD uitgiftewebservice wordt gedefinieerd in de package brocom (XSD-bestand brocommon.xsd).

2.2.2. SOAP:Fault

Tijdens de uitvoering van een operatie kan er een onverwachte fout optreden in het BRO-systeem. Hiervoor kunnen verschillende oorzaken zijn, zoals het falen van bepaalde software of hardware. Deze onverwachte fouten worden beschouwd als een technische fout veroorzaakt door het BRO-systeem. De BRO stuurt dan een bericht in de vorm van een generieke SOAP:Fault (Systeemfout).

2.2.3. ParseFault

Als er fouten in het uitgifteverzoek worden gevonden tijdens de technische controle van een uitgifteverzoek, bijvoorbeeld het uitgifteverzoek is niet een welgevormd XML-bericht of het uitgifteverzoek voldoet niet aan de schemavalidatie, dan worden deze beschouwd als een softwarefout in het systeem van de data-afnemer. Het BRO-systeem stuurt dan een bericht in de vorm van een ParseFault (Validatiefout).
Het BRO-bericht ParseFault (Validatiefout) is in feite een gemodelleerde vorm van de algemene SOAP:Fault (Systeemfout), waarbij op de plek van het detail de gegevens van de ParseFault (Validatiefout) worden opgenomen. In de ParseFault (Validatiefout) zit een lijst met abortReasons (Redenen afbreken).

De ParseFault (Validatiefout) bestaat uit drie gegevens en een lijst met abortReasons. De definities van de gegevens van ParseFault (Validatiefout) staan in onderstaande tabel:

Iedere AbortReason (Reden afbreken) bestaat uit twee gegevens. De definities staan in onderstaande tabel:

2.2.4. DispatchDataResponse

Onder normale omstandigheden bestaat het antwoord op een dispatchDataRequest (verzoek tot uitgifte van objectgegevens) uit een dispatchDataResponse (bericht van verzending van objectgegevens). Het antwoord  DispatchDataResponse is gedefinieerd in het XSD-bestand dsgpd-messages.xsd. Het is een specialisatie van DispatchResponse zoals gedefinieerd in brocommon.xsd. Het voegt daaraan toe één optioneel dispatchDocument.

• Een bericht van afwijzing.

• Een bericht van verzending van objectgegevens.

Onderstaande tabel geeft weer welke gegevens onder welke omstandigheden in het BRO-bericht opgenomen zullen worden. De lijst met criterionErrors (kenmerkfouten) speelt geen rol bij de uitgifte van objectgegevens.

Onderstaande tabel bevat de definities van de gegevens van de  DispatchResponse :

Onderstaande tabel bevat de definities van de gegevens die DispatchDataResponse uit dsfrd-messages.xsd toevoegt aan DispatchResponse uit brocommon:

3. Uitgiftedocumenten

Een uitgiftedocument bevat de gegevens van het opgevraagde registratieobject, die in het BRO-systeem geregistreerd zijn. De beschikbare gegevens zijn gedefinieerd in de catalogus.
De GPD uitgiftewebservice kent drie types uitgiftedocumenten; zie onderstaande tabel. Welke type wordt uitgeleverd hangt af van de identiteit van de afnemer en de registratiestatus van het registratieobject.

Onderstaande figuur geeft de uitgiftedocumenten weer (blauwe achtergrond) inclusief de mogelijke inhoud:

Alle attributen zijn volledig gedefinieerd in de  GPD gegevenscatalogus .
De attributen/gegevensgroepen met een schuine streep voor hun naam worden afgeleid door de GPD innamewebservice; deze gegevens worden niet aangeleverd via een brondocument.
De attributen met een min-teken voor hun naam worden alleen uitgeleverd in het GPD_O_DP uitgiftedocument.

3.1. Verschillen tussen gegevenscatalogus enerzijds en brondocumenten en uitgiftedocumenten anderzijds

In verband met een efficiënte aanlevering van nieuwe gegevens en een eenvoudig mechanisme voor het corrigeren van geregistreerde gegevens zijn er twee verschillen aangebracht tussen de gegevensstructuur zoals beschreven in de gegevenscatalogus en de gegevensstructuur zoals gebruikt in de brondocumenten en uitgiftedocumenten.

3.2. Inhoud GPD_O_DP

De gegevens zijn volledig gedefinieerd in de GPD gegevenscatalogus. Uitgiftedocument GPD-O-DP bevat alle gegevens uit de catalogus:

Ten aanzien van het aan elke rapportage gekoppelde  GerealiseerdeInstallatieOfGrondwatergebruiksysteem  wordt bij elke rapportage uitgegeven:

• BRO-ID van het gronwatergebruiksysteem (GUF) [1]

• gerealiseerde installatie ID [0..1]

3.3. Inhoud GPD_O

Uitgiftedocument GPD-O bevat dezelfde gegevens als uitgiftedocument GPD-O-DP, met uitzondering van de volgende gegevens (die ontbreken in GPD-O):

• de lijst met Report (Rapportage) gegevens in het RegistrationObject (Registratieobject) als het attribuut publiclyAvailable (openbaar raadpleegbaar) aanwezig is en de waarde ervan gelijk is aan nee.

• objectIdAccountableParty (object-ID bronhouder) in het RegistrationObject (Registratieobject).

• deliveryResponsibleParty  (dataleverancier) in het RegistrationObject (Registratieobject).

• measurementOperator  (uitvoerder meting) in de ElectromagneticMeasurement  (Elektromagnetische meetmethode).

• measurementOperator  (uitvoerder meting) in de GeoElectricMeasurement  (Geo-ohmkabelmeetmethode).

• calculationOperator  (uitvoerder berekening) in de CalculatedApparentFormationResistance (Berekende schijnbare formatieweerstand).

4. Voorbeeldberichten

Zie de pagina met voorbeeldberichten  GPD voorbeeldberichten uitgifte

5. Enumeraties

In de BRO wordt een onderscheid gemaakt tussen beheerde waardenlijsten en niet-beheerde waardenlijsten.
In de gegevenscatalogus 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 gegevenscatalogus, de berichtdefinities (XSD-bestanden) en de software (voor het maken of verwerken van een bericht).
De onderstaande tabel geeft een overzicht van de GPD-specifieke enumeraties.

• 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 gegevenscatalogus.

• De derde kolom bevat de toegestane waarden, die gebruikt mogen worden in een BRO-verzoek.

De vierde kolom bevat een omschrijving van de toegestane waarde.

6. Codelijsten

In de BRO wordt een onderscheid gemaakt tussen beheerde waardenlijsten en niet-beheerde waardenlijsten.

In de gegevenscatalogus en de XSD-bestanden noemen we een beheerde waardenlijst een codelijst. Het domein van een  codelijst  is een uitbreidbare opsomming van toegestane waarden.

De onderstaande tabel geeft een overzicht van de FRD-specifieke codelijsten.

• 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 gegevenscatalogus.

• De derde kolom bevat de URN, die in een BRO-verzoek gebruikt moet worden bij het XML-attribuut codeSpace. Zie  Codelist (Codelijst)  en de voorbeeldberichten voor nadere informatie.

• De vierde kolom bevat een link naar de REST-service, waarmee u de inhoud van een bepaalde codelijst kunt opvragen.  Als resultaat ontvangt u dan een JSON-bericht met daarin alle waarden van de codelijst met de beschrijvingen.

7. Vertaaltabel

Dit hoofdstuk bevat een vertaaltabel, aan de hand waarvan, gegeven de Engelstalige naam van een complexType of element of een attribuut in de XSD-bestanden, de Nederlandse naam in de gegevenscatalogus kan worden opgezocht.
De onderstaande tabel is gesorteerd op alfabetische volgorde van de Engelstalige naam van het complexType/element. Tussen haakjes staat het type modelelement van de entiteit. Binnen een entiteit zijn de attributen gesorteerd op Engelstalige naam