GPD Berichtencatalogus innamewebservice

Dit document beschrijft het aanleveren van gegevens van een grondwatergebruikdossier (GPD).

Per 7 juli 2022 wordt een MVP beschikbaar gesteld voor gebruikers. In dit MVP zijn alleen de registratie-operaties beschikbaar. De overige operaties zijn ontworpen en zullen na 7 juli 2022 worden gebouwd in een volgende iteratie van GPD.

In onderstaande berichtencatalogus zijn alle ontworpen operaties beschreven, incl. de nog niet beschikbare operaties.

Inleiding

Voorwoord

Betrouwbare en toegankelijke informatie over de samenstelling en opbouw van de ondergrond is van groot belang voor een dichtbevolkt land als Nederland. 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. Centrale registratie van gegevens voorkomt dat informatie dubbel moet worden ingewonnen.

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 en op 1 januari c.q. 1 juli 2021 het derde deel op 1 januari 2022 deel 4a en op 1 juli 2022 deel 4b (waar dit registratieobject toe behoord).

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

In het document Handreiking Afname BRO Gegevens wordt beschreven via welke uitgiftekanalen BRO-gegevens geraadpleegd of gedownload kunnen worden en welke functionele en technische mogelijkheden deze kanalen bieden.

In het document Handreiking aanleveren BRO-gegevens heeft men algemene informatie kunnen inwinnen over:

• Hoe kun je een BRO-verzoek als een XML-bestand opstellen?
• Hoe ziet zo'n XML-bestand er uit?
• Hoe moet je te werk gaan als de gegevens in één keer beschikbaar komen dan wel beetje bij beetje in de loop der tijd?
• Hoe kunnen verandering van waarden in de loop der tijd gemeld kunnen worden?
• Hoe kun je een fout in de geregistreerde gegevens corrigeren?

Blijft over de vraag: met welke brondocumenten kunnen gegevens over een Grondwaterproductiedossier (GPD) aangeleverd of gecorrigeerd worden en welke andere GPD-specifieke informatie is er beschikbaar naast de algemene informatie in de Handreiking aanleveren BRO-gegevens?

Doelstelling

Dit document bevat GPD-specifieke informatie voor het aanleveren en corrigeren van gegevens van een grondwaterproductiedossier. Hierbij gaat het met name over:

• Welke GPD-specifieke brondocumenten zijn er als eenheid voor het aanleveren of corrigeren van gegevens?
• Welke combinaties van brondocument en type correctieverzoek zijn toegestaan?
• Welke GPD-specifieke aanvullende regels zijn er, naast de bedrijfsregels in de GPD-gegevenscatalogus en de algemene aanvullende regels in de Handreiking aanleveren BRO-gegevens?
• Welke GPD-specifieke codelijsten zijn er en waar kunnen hun toegestane waarden geraadpleegd worden?
• Is er een tabel waarmee een Engelstalige naam in de XML-bestanden kan worden omgezet naar de Nederlandstalige naam in de gegevenscatalogus?

Doelgroep

Doelgroep voor dit document zijn organisaties en personen, waaronder bestuursorganen en bedrijven, die opereren als bronhouder,  gegevensleverancier of softwareleverancier en die betrokken zijn bij het opstellen van BRO-verzoeken. En die gegevens over een Grondwaterproductiedossier (GPD) moeten aanleveren of hierover geregistreerde gegevens moeten corrigeren.

Samenhang met andere documentatie

De informatievoorziening over het aanleveren aan de BRO vindt plaats op 3 niveaus. Zie onderstaande figuur.

1. Het startpunt met algemene informatie over de BRO is de website www.basisregistratieondergrond.nl. Een stappenplan voor het verkrijgen van toegang tot het Bronhouderportaal is te vinden op https://basisregistratieondergrond.nl/inhoud-bro/aanleveren-opvragen/tools-tips/bronhouderportaal.
2. Het tweede niveau is het Bronhouderportaal (https://www.bronhouderportaal-bro.nl/login), met rechtsonderaan een link naar de gebruikshandleiding (zie Handleiding bronhouderportaal).
3. Het derde niveau is de BRO Productomgeving. Hier vindt u onder meer algemene informatie over het aanlever- en afnameproces, wijzigings- en versiebeheer en Q&A voor softwareleveranciers, maar ook specifieke informatie van de beschikbare types registrieobjecten 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 en het document Handreiking aanleveren BRO-gegevens in de BRO productomgeving.

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

Leeswijzer

Hoofdstuk 2 bevat een beschrijving van de Brondocumenten, inclusief een overzicht met welke combinaties van brondocument en type correctieverzoek zijn toegestaan en de bijbehorende aanvullende regels.

Hoofdstuk 3 bevat enkele Scenario's  voor het aanleveren van registratieverzoeken en correctieverzoeken.

Hoofdstuk 4 beschrijft enkele integrale Voorbeeldberichten (XML-bestanden).

Hoofdstuk 5 bevat een overzicht van de GPD-specifieke Codelijsten  (beheerde waardelijsten) met een link naar de webpagina waar de lijst met toegestane waarden geraadpleegd kan worden.

Hoofdstuk 6 bevat een Vertaaltabel, waarmee de GPD-specifieke Engelstalige namen van onderdelen in de XSD en XML-bestanden kunnen worden omgezet in Nederlandstalige namen in de gegevenscatalogus.

Versiehistorie

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.

Brondocumenten

Dit hoofdstuk definieert de brondocumenten voor het starten, aanvullen en beëindigen van de registratie van een GPD. Dezelfde brondocumenten kunnen ook gebruikt worden om geregistreerde gegevens te corrigeren.

De entiteiten en attributen in dit document worden aangeduid met de Engelstalige namen, zoals die voorkomen in de XSD-bestanden (de formele berichtdefinities) en de XML-bestanden (met de BRO-verzoeken). Met behulp van de Vertaaltabel kunnen deze worden omgezet in de Nederlandstalige namen in de GPD-gegevenscatalogus.

Levensloop, materiële geschiedenis en tijdlijn.

Het grondwaterproductiedossier is een registratieobject met levensduur maar zonder tijdlijn of materiële geschiedenis, met alleen een start van de registratie, aanvullingen zonder temporele betekenis, en een beëindiging van de registratie.

Gebeurtenissen

Naar aanleiding van een in de werkelijkheid opgetreden gebeurtenis worden de relevante gegevens aangeboden aan de BRO in de vorm van een brondocument. Deze berichtencatalogus definieert de verzameling brondocumenten en beschrijft hun inhoud. De gegevens in de brondocumenten worden gedefinieerd in de gegevenscatalogus.

Bij het verwerken van een brondocument voegt de LV-BRO nieuwe gegevens toe aan de registratie. Daarbij moeten gegevens in chronologische volgorde worden aangeboden. Alhoewel nieuwe gegevens ontstaan naar aanleiding van een gebeurtenis in de werkelijkheid, bouwt de LV-BRO bij een GPD registratieobject geen  ObjectHistory  (Objectgeschiedenis) op met daarin een lijst van  Events  (Gebeurtenissen).

De gebeurtenisdatum wordt niet gedefinieerd in de gegevenscatalogus. De waarde ervan wordt afgeleid van een attribuut in het brondocument, bijvoorbeeld de begintijd van de levensduur van een object of de beginGeldigheid van de geldigheidsduur van een object als er materiële geschiedenis wordt opgebouwd.

De  naam van de gebeurtenis wordt niet gedefinieerd in de gegevenscatalogus. De waarde ervan wordt afgeleid van het type brondocument. De lijst met toegestane waarden voor de naam van een gebeurtenis is opgenomen in een codelijst (zie hoofdstuk Codelijsten).

Correcties

Door middel van correcties is het mogelijk geregistreerde gegevens te vervangen, te verplaatsen op de tijdlijn of te verwijderen. Ook is het mogelijk vergeten gegevens in te voegen op de tijdlijn. Zie voor nadere details over de correctieverzoeken hoofdstuk 4 van de Handreiking aanleveren BRO-gegevens.

De eenheid van corrigeren is een brondocument; het is niet mogelijk individuele gegevens te corrigeren.

De te corrigeren gegevens worden geïdentificeerd door het  broID  (BRO-ID) van het registratieobject, eventueel in combinatie met de identificatie van het feature (object) binnen het registratieobject. 

Overzicht

Voor het aanbieden van (nieuwe of gecorrigeerde) gegevens kent de GPD-innamewebservice de volgende brondocumenten:

Onderstaande tabel geeft per type brondocument weer wat de naam in een XML-bestand is en tot welke registratie status de verwerking ervan leidt. 

Operaties

Onderstaande tabel geeft per brondocument weer in welke registratie en correctie operaties het aangeboden kan worden.

Inhoud brondocumenten

GPD_StartRegistration

Dit brondocument wordt aangeboden wanneer de initiële gegevens over een grondwaterproductiedossier worden vastgelegd in de basisregistratie ondergrond. De registratie van het GPD in de BRO is met dit document gestart. 

Het starten van de registratie is een noodzakelijke eerste gebeurtenis, die per registratieobject maar één keer kan en moet plaatsvinden. Daarom zijn de BRO-verzoeken  insertRequest  (invoegen) en  deleteRequest  (verwijderen) niet van toepassing. Het verwijderen van een registratie kan alleen door het registratieobject uit registratie te nemen. Neem hiervoor contact op met de BRO Servicedesk via een mail naar  support@broservicedesk.nl .

Inhoud

Onderstaande figuur geeft een overzicht van de inhoud van het brondocument.

De volgende gegevens staan  niet  in het brondocument en worden helemaal niet aangeleverd:

• Het broid (BRO-ID). Bij een eerste aanlevering van dit brondocument genereert de BRO een waarde voor dit gegeven. Bij de aanlevering van dit brondocument in het kader van een correctie staat het BRO-ID niet in het brondocument maar wordt het aangeleverd in het bericht.
• Rapportage met volumereeksen, deze worden aangeleverd met het brondocument GPD_AddReport
• endTime (eindtijd) van lifespan ( levensduur). 

Omdat van lifespan alleen de startTime in het brondocument wordt aangeleverd is deze verplaatst van de lifespan naar GPD_StartRegistration. (De endTime kan alleen worden aangeleverd in het brondocument GPD-Beeindiging .)

De volgende gegevens worden niet aangeleverd met het brondocument maar worden wel aangeleverd in het bericht:

• De deliveryAccountableParty  (bronhouder) als de bronhouder een andere organisatie is dan de dataleverancier.
• De deliveryResponsibleParty  (dataleverancier).
• Het qualityRegime  (kwaliteitsregime).

Aanvullende regels

• Het attribuut publiclyAvailable (openbaar raadpleegbaar) moet aanwezig zijn wanneer het attribuut primaryUsageType (primair gebruiksdoel) van de entiteit UsageTypeFacility (Gebruiksdoel systeem) van het Grondwatergebruiksysteem waarop dit Grondwaterproductiedossier betrekking heeft gelijk is aan 'openbareDrinkwatervoorziening'. Het attribuut mag niet aanwezig zijn in alle andere gevallen. 

GPD_AddReport

Inhoud

Onderstaande figuur geeft een overzicht van de inhoud van het brondocument.

De volgende gegevens  staan  niet  in het brondocument maar worden wel aangeleverd in het bericht:

• Het broId (BRO-ID) van het registratieobject waar dit brondocument moet worden aangevuld of gecorrigeerd.
• De deliveryAccountableParty (bronhouder) als de bronhouder een andere organisatie is dan de dataleverancier.
• De deliveryResponsibleParty (dataleverancier).
• Het qualityRegime (kwaliteitsregime).

Af te leiden gegevens

• Geen

Aanvullende regels

• Geen

GPD_EndRegistration

Het brondocument wordt aangeboden wanneer het grondwaterproductiedossier wordt beëindigd omdat er geen rapportages meer worden verwacht. De registratie is met dit brondocument voltooid en het registratieobject  kan niet meer worden aangevuld.

Inhoud

Onderstaande figuur geeft een overzicht van de inhoud van het brondocument.

De volgende gegevens  staan  niet  in het brondocument maar worden wel aangeleverd in het bericht:

• Het broId (RO-ID) van het registratieobject waar dit brondocument moet worden aangevuld of gecorrigeerd.
• De deliveryAccountableParty (bronhouder) als de bronhouder een andere organisatie is dan de dataleverancier.
• De deliveryResponsibleParty (dataleverancier).
• Het qualityRegime (kwaliteitsregime).

Aanvullende regels

• De endTime  (eindtijd) in het brondocument moet liggen na de geregistreerde waarde van het attribuut startTime  (begintijd)van de entiteit Lifespan (TijdvakLevensduur). 

Af te leiden gegevens

Voorbeeldberichten

Integrale XML-voorbeeldberichten

Integrale voorbeeldberichten zijn te vinden op de pagina https://www.bro-productomgeving.nl/bpo/latest/grondwatergebruik/grondwaterproductiedossier-gpd/gpd-voorbeeldberichten-inname

XML-code snippets

Voorbeelden van een aantal algemene stukken XML-code (code snippets) zijn te vinden in de  Handreiking Afname BRO Gegevens.

De volgende paragrafen bevatten enkele stukken XML-code die specifiek zijn voor GPD

$body

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

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.