BHR-G Berichtencatalogus uitgiftewebservice

Inleiding

Dit document beschrijft hoe een afnemer van de Basisregistratie Ondergrond (BRO) de gegevens over een geologisch booronderzoek (BHR-G) kan opvragen.

Het document veronderstelt dat de lezer bekend is met de BHR-G catalogus. 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.

Leeswijzer

Hoofdstuk 2 beschrijft de algemene werking van de BHR-G uitgiftewebservice.

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.basisre gistratieondergrond.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.

Als u toegang heeft tot de BRO Selfservicedesk (alleen via desktop of laptop), kunt u daar inloggen en uw vraag stellen voor een extra snelle afhandeling.

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

Algemene werking van de BHR-G uitgiftewebservice

Operaties

De BHR-G uitgiftewebservice wordt gerealiseerd als een SOAP-webservice. De BHR-G uitgiftewebservice ondersteunt twee soap operaties:

1. dispatchCharacteristics (uitgifte van kengegevens).
2. dispatchData (uitgifte van objectgegevens).

Een soap operatie heeft een request en een response:

• Het DispatchCharacteristicsRequest (verzoek tot uitgifte van kengegevens) en de DispatchCharacteristicsResponse (bericht van verzending van kengegevens).
• Het DispatchDataRequest (verzoek tot uitgifte van objectgegevens) en de DispatchDataResponse (bericht van verzending van objectgegevens).

Naast een bericht van verzending kan ieder 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 BHR-G uitgiftewebservice constateert dat een uitgifteverzoek niet een welgevormd XML-bericht is of dat het niet voldoet aan de schema validatie, dan leidt dit tot een ParseFault.

Bovenstaande leidt tot het volgende interface ontwerp:

BRO-berichten

Deze paragraaf beschrijft de zes verschillende BRO-berichten die een rol spelen in de BHR-G uitgiftewebservice.

DispatchCharacteristicsRequest

Met een DispatchCharacteristicsRequest (verzoek tot uitgifte van kengegevens) kunnen de kengegevens van één of meer registratieobjecten worden opgevraagd, voor zover deze voldoen aan de kenmerken in het uitgifteverzoek. Het uitgifteverzoek is gedefinieerd in het XSD-bestand dsbhrg-messages.xsd. Het is een specialisatie van AbstractDispatchCharacteristicsRequest zoals gedefinieerd in brocommon.xsd. Het voegt de AttributeGroup (gegevensgroep) criteria (ke nmerkenverzameling) toe aan het AttributeType (attribuutsoort) requestReference (verzoekkenmerk) uit brocommon.

Toelichting

In deze versie omvat het booronderzoek het algemene deel (veldwerk) en 2 deelonderzoeken en dat is de boormonsterbeschrijving en de boormonsteranalyse.

Het datatype BHR_G_CriteriaSet, (Kenmerkenverzameling) is een specialisatie van CritriaSet (Kenmerkenverzameling) uit brocommon.xsd, waaraan het een lijst met BHR-G specifieke attributen toevoegt. Alle attributen binnen BHR_G_CriteriaSet zijn optioneel. De meeste attributen hebben een scalair datatype, met uitzondering van de Attributegrouptypes DatePeriod (Datum interval) zoals gedefinieerd in brocommon.xsd en VerticalPositionRange (Diepte interval) zoals gedefinieerd in dsbhrg-messages.xsd.

Alle attributen van Criteriaset uit brocommon.xsd zijn optioneel, met uitzondering van het attribuut area (gebied). Ook hier hebben de meeste attributen een scalair datatype, met uitzondering van het Attributegrouptype DatePeriod (Datum interval) en de Union Area (gebied), beiden gedefinieerd in brocommon.xsd.

Het datatype Area geeft de begrenzing aan van een geografisch gebied aan het aardoppervlak, waarbinnen de registratieobjecten moeten liggen. Het datatype heeft een stereotype Union, wat aangeeft dat óf een enclosingCircle (omvattende cirkel) óf een boundingBox (omvattende rechthoek) moet worden opgenomen in het BRO-verzoek. In beide gevallen worden de coördinaten uitgedrukt in een referentiestelsel. Onderstaande tabel geeft de toegestane waarden binnen de BHR-G uitgiftewebservice.

Een enclosingCircle (omvattende cirkel) wordt gedefinieerd door het middelpunt (met als datatype gml:GM_Point) en de straal (met als datatype gml:Measure) uitgedrukt in kilometers. Voorbeeld van een cirkel met een middelpunt uitgedrukt in ETRS89 (European Terrestrial Reference System 1989) en een straal van 10 km:

<brocom:enclosingCircle srsName="urn:ogc:def:crs:EPSG::4258">
    <brocom:center>52.287820209 5.090415499</brocom:center>
    <brocom:radius uom="km">10</brocom:radius>
</brocom:enclosingCircle>

Een boundingBox (omvattende rechthoek) wordt gedefinieerd door het attribuut lowerCorner (onderhoek), met als coördinaten de minimale waarden voor de twee dimensies binnen de rechthoek, en het attribuut upperCorner (bovenhoek), met als coördinaten de maximale waarden voor de twee dimensies binnen de rechthoek. Voorbeeld van een vierkant van 10 * 10 km, als boundingBox (omvattende rechthoek), waarvan de coördinaten zijn uitgedrukt in RD (Rijks Driehoeksmeting – Amersfoort RD New):

<brocom:boundingBox gml:id="BRO_0001" srsName="urn:ogc:def:crs:EPSG::28992">
    <gml:lowerCorner>136000.0 472000.0</gml:lowerCorner>
    <gml:upperCorner>146000.0 482000.0</gml:upperCorner>
</brocom:boundingBox>

DispatchDataRequest

Met een DispatchDataRequest (verzoek tot uitgifte van objectgegevens) kunnen op basis van de broId (BRO-ID) alle geregistreerde gegevens van één registratieobject worden opgevraagd. Het uitgifteverzoek is volledig gedefinieerd in het XSD-bestand brocommon.xsd.

De definities van de transactiegegevens staan in onderstaande tabel:

SOAP:Fault

Tijdens de uitvoering van een operatie kan er een onverwachte fout optreden in het BROsysteem. 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).

Een SOAP:Fault (Systeemfout) bestaat uit twee verplichte gegevens en één optioneel gegeven. D e definities van deze gegevens staan in onderstaande tabel:

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

Dit bericht begint met een SOAP:Fault (Systeemfout), bestaande uit drie gegevens. De definities van deze gegevens staan in onderstaande tabel: 

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

De lijst abortReasons (redenen afbreken) bestaat uit minimaal 1 en maximaal 99 voorkomens van een AbortReason (Reden afbreken). Iedere AbortReason (Reden afbreken) bestaat uit twee gegevens. De definities staan in onderstaande tabel:

DispatchCharacteristicsResponse

Onder normale omstandigheden bestaat het antwoord op een DispatchCharacteristicsRequest (verzoek tot uitgifte van kengegevens) uit een DispatchCharacteriscticsResponse (bericht van verzending van kengegevens). Het antwoord dispatchCharacteristicsResponse is gedefinieerd in het XSD-bestand dsbhr-g-messages.xsd. Het is een specialisatie van DispatchResponse zoals gedefinieerd in brocommon.xsd. Het voegt daaraan toe het attribuut numberOfDocuments (aantal documenten) en een lijst met dispatchDocuments (uitgiftedocumenten).

Als het BRO-systeem een semantische fout heeft geconstateerd in één of meer waarden van de attributen van de criteria (kenmerkenverzameling) in het uitgifteverzoek, dan:

• Heeft het attribuut responseType de waarde rejection.
• Is de waarde van het attribuut requestReference gelijk aan de waarde van het gelijkluidende attribuut in het uitgifteverzoek.
• Geeft de waarde van het attribuut rejectionTime aan op welk moment het antwoord beschikbaar is gekomen.
• Is het attribuut dispatchTime niet aanwezig.
• Heeft het attribuut rejectionReason de vaste waarde "Er zijn 1 of meer fouten geconstateerd in de kenmerkenverzameling".
• Bevat de lijst met criterionErrors maximaal 99 voorkomens van de AttributeGroup CriterionError.
• Is het attribuut numberOfDocuments niet aanwezig.
• Is er geen dispatchDocument aanwezig.

Als het uitgifteverzoek succesvol is verwerkt, dan:

• Heeft het attribuut responseType de waarde dispatch.,
• Is de waarde van het attribuut requestReference gelijk aan de waarde van het gelijkluidende attribuut in het uitgifteverzoek
• Is het attribuut rejectionTime niet aanwezig.
• Geeft de waarde van het attribuut dispatchTime aan op welk moment het antwoord beschikbaar is gekomen.
• Is het attribuut rejectionReason niet aanwezig.
• Is de lijst met criterionErrors niet aanwezig.
• Geeft de waarde van het attribuut numberOfDocuments aan hoeveel registratieobjecten er zijn gevonden die voldoen aan de criteria.
• Bevat de lijst met dispatchDocuments een reeks van uitgiftedocumenten zoals beschreven in de volgende paragraaf. Het type van het element dispatchDocument is gedefinieerd als AbstractRegistrationObject, zoals gedefinieerd in brocommon.xsd, omdat dit de eerste gemeenschappelijke vader is van de toegestane uitgiftedocumenten.

Als er geen registratieobjecten zijn gevonden die voldoen aan de criteria, dan heeft het attribuut numberOfDocuments de waarde 0 en is de lijst met dispatchDocuments leeg.

Als er meer dan 2000 registratieobjecten zijn gevonden die voldoen aan de criteria, dan heeft het attribuut numberOfDocuments de waarde 2000 en is de lijst met dispatchDocuments beperkt tot dat aantal.

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 dsbhr-g-messages.xsd. Het is een specialisatie van DispatchResponse zoals gedefinieerd in brocommon.xsd. Het voegt daaraan toe één optioneel dispatchDocument.

Als er geen registratieobject is gevonden met de in het uitgifteverzoek opgegeven broId (BRO-ID), dan:

• Heeft het attribuut responseType de waarde rejection.
• Is de waarde van het attribuut requestReference gelijk aan de waarde van het gelijkluidende attribuut in het uitgifteverzoek.
• Geeft de waarde van het attribuut rejectionTime aan op welk moment het antwoord beschikbaar is gekomen.
• Is het attribuut dispatchTime niet aanwezig.
• Heeft het attribuut rejectionReason de vaste waarde "Dit registratieobject bestaat niet".
• Is de lijst met criterionErrors niet aanwezig.
• Is er geen dispatchDocument aanwezig.

Als het uitgifteverzoek succesvol is verwerkt, dan:

• Heeft het attribuut responseType de waarde dispatch.
• Is de waarde van het attribuut requestReference gelijk aan de waarde van het gelijkluidende attribuut in het uitgifteverzoek.
• Is het attribuut rejectionTime niet aanwezig.
• Geeft de waarde van het attribuut dispatchTime aan op welk moment het antwoord beschikbaar is gekomen.
• Is het attribuut rejectionReason niet aanwezig.
• Is de lijst met criterionErrors niet aanwezig.
• Bevat het dispatchDocument één van de uitgiftedocumenten zoals beschreven in de volgende paragraaf. Het type van het element dispatchDocument is gedefinieerd als AbstractRegistrationObject, zoals gedefinieerd in brocommon.xsd, omdat dit de eerste gemeenschappelijke vader is van de toegestane uitgiftedocumenten.

Uitgiftedocumenten

Een uitgiftedocument bevat de gegevens van een opgevraagd registratieobject, die in het BRO-systeem geregistreerd zijn. Voor elk registratieobject staat in de bijbehorende catalogus de definitie van de beschikbare gegevens. De BHR-G uitgiftewebservice kent vier types uitgiftedocumenten. Welke verschijningsvormen wordt aangenomen voor een gegeven registratieobject, hangt primair af van het bericht van verzending waarin het uitgiftedocument is opgenomen.

Paragraaf 2.3.1 beschrijft de uitgiftedocumenten die kunnen worden opgenomen in een DispatchCharacteristicsResponse (Bericht van verzending van kengegevens).

Paragraaf 2.3.2 beschrijft de uitgiftedocumenten die kunnen worden opgenomen in een DispatchDataResponse (Bericht van verzending van objectgegevens).

Kengegevens

De BHR-G uitgiftewebservice kent twee types uitgiftedocumenten die kunnen worden opgenomen in een dispatchCharacteristicsResponse (Bericht van verzending van kengegevens). Zie onderstaande tabel. Het bericht dispatchCharacteristicsResponse (Bericht van verzending van kengegevens) bevat een lijst met uitgiftedocumenten, met daarin de kengegevens van de registratieobjecten die voldoen aan de criteria in het uitgifteverzoek. Per registratieobject kan het daarbij gaan om de volgende uitgiftedocumenten:

Zoals in onderstaande figuur wordt aangegeven, zijn beide uitgiftedocumenten een specialisatie van AbstractRegistrationObject, wat gedefinieerd is in brocommon.xsd. Omdat dit de eerste gemeenschappelijke vader is van die twee uitgiftedocumenten, treedt dit FeatureType op als datatype van de reeks dispatchDocuments in het antwoord DispatchCharacteristicsResponse.

In het geval van een BRO_DO uitgiftedocument bestaat het uitgiftedocument uit de volgende attributen (allen verplicht):

• broId
• deregistered
• deregistrationTime

In het geval van een BHR_G_C uitgiftedocument bestaat het uitgiftedocument uit de volgende attributen (zie bovenstaande figuur voor de kardinaliteiten):

• broId
• deregistered
• deliveryAccountableParty
• qualityRegime
• objectRegistrationTime
• latestCorrectionTime
• underReview
• standardizedLocation
• deliveredLocation
• surveyPurpose
• discipline
• researchReportDate
• localVerticalReferencePoint
• offset
• verticalDatum
• boringStartDate
• boringEndDate
• rockReached
• finalDepthBoring
• descriptionReportDate
• descriptionProcedure
• descriptionQuality
• analysisReportDate
• samplingQualityOverview
  
  • samplingQuality
• determinedPropertiesOverview
  • determinedProperties

Objectgegevens

De BHR-G uitgiftewebservice kent drie types uitgiftedocumenten die kunnen worden opgenomen in een DispatchDataResponse (Bericht van verzending van objectgegevens). Zie onderstaande tabel. Welke verschijningsvormen wordt aangenomen, hangt af van de identiteit van de afnemer en de registratiestatus van het registratieobject.

Onderstaande figuur geeft de uitgiftedocumenten (blauwe achtergrond) weer:

Voorbeeldberichten

Codelijsten

Dit hoofdstuk bevat verwijzingen (URN's en URL's) naar de codelijsten (beheerde waardenlijsten).

Vertaallijst

Dit hoofdstuk bevat een vertaaltabel, aan de hand waarvan, gegeven de Engelstalige naam van een entiteit of een attribuut, de Nederlandse naam in de gegevenscatalogus 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.