Berichtencatalogus uitgiftewebservice BHR-P

Work in progress

Inleiding

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

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

Hoofdstuk 3 bevat een toelichting op enkele voorbeeldberichten.

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

Open punten

Op dit moment staan de volgende zaken een afronding van dit document in de weg:

• Kenmerken en kengegevens: Tegenstrijdigheden tussen beschrijving van de uitgiftedocumenten, technisch transactieontwerp en XSD-bestanden wegnemen.
• Figuren bijwerken: uitgecheckt logisch model blokkeert het bijwerken van relevante figuren in dit document.

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.

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-P uitgiftewebservice

Dit hoofdstuk beschrijft de algemene werking van de BHR-P uitgiftewebservice.

Paragraaf 2.1 beschrijft de operaties die de BHR-P uitgiftewebservice ondersteunt.

Paragraaf 2.2 beschrijft de BRO-berichten die een rol spelen bij die operaties.

Paragraaf 2.3 beschrijft de verschillende uitgiftedocumenten die in een BRO-bericht uitgegeven kunnen worden. 

Operaties

De BHR-P uitgiftewebservice wordt gerealiseerd als een SOAP-webservice. De BHR-P uitgiftewebservice ondersteunt twee soap operaties: dispatchCharacteristics (uitgifte van kengegevens) en dispatchData (uitgifte van objectgegevens).

De wsdl kan worden gedowload van https://schema.broservices.nl/dsbhr-p-v2.0.wsdl

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

BRO-berichten

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

DispatchCharacteristicsRequest

Het BRO-bericht DispatchCharacteristicsRequest bevat het uitgifteverzoek tot het leveren van de in het BRO-register opgenomen kengegevens van de BHR-P registratieobjecten die voldoen aan bepaalde kenmerken. Het DispatchCharacteristicsRequest (Verzoek tot uitgifte van kengegevens) van de BHR-P uitgiftewebservice is een specialisatie van AbstractDispatchCharacteristicsRequest in de package brocommon, waaraan het het attribuut criteria (kenmerken) met de BHR-P specifieke kenmerken toevoegt.

De definities van de transactiegegevens staan in onderstaande tabel:

De criteria worden gedefinieerd doorCriteriaSet van de BHR-P uitgiftewebservice, een specialisatie van CriteriaSet uit package brommon, waaraan het een aantal optionele attributen toevoegt.

De definities van de attributen van de CriteriaSet uit brocommon staan in onderstaande tabel:

De definities van de attributen die CriteriaSet van de BHR-P uitgiftewebservice toevoegt aan CriteriaSet uit brocommon staan in onderstaande tabel:

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.

Dit BRO-bericht bestaat uit twee transactiegegevens. 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 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).

Een SOAP:Fault (Systeemfout) bestaat uit twee verplichte gegevens en één optioneel gegeven. De 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 BRO-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 met 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-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).

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

Onderstaande tabel bevat de definities van de gegevens die DispatchCharacteristicsResponse toevoegt aan DispatchResponse uit brocommon:

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

Het BRO-bericht DispatchDataResponse (Antwoord) kan twee betekenissen hebben:

• 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 alleen een rol bij de uitgifte van kenmerken en dus niet bij de uitgifte van objectgegevens.

Zie de voorgaande paragraaf voor de definities van de gegevens van de DispatchResponse uit brocommon.

Onderstaande tabel bevat de definities van de gegevens die DispatchDataResponse toevoegt aan DispatchResponse uit brocommon:

Uitgiftedocumenten

Een uitgiftedocument bevat gegevens van een registratieobject, die in het BRO-systeem zijn geregistreerd. In de catalogus van het registratieobject staat de definitie van de beschikbare gegevens.

De BHR-P uitgiftewebservice kent vier types uitgiftedocumenten. Welk type voor een gegeven uitgiftedocument wordt gebruikt, hangt af van het uitgifteverzoek, het feit of de afnemer tevens bronhouder en/of dataleverancier is van het opgevraagde registratieobject en of het registratieobject uit registratie is genomen of niet.

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

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/verzameling kengegevens kan het daarbij gaan om een van de twee types uitgiftedocumenten in onderstaande tabel. Welke verschijningsvorm wordt aangenomen, hangt af van het feit of het registratieobject uit registratie is genomen of niet:

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.

BRO_DO

Het uitgiftedocument van het type BRO_DO is een specialisatie van AbstractRegistrationObject in de package brocommon. Dit uitgiftedocument bestaat uit de onderstaande gegevens. Alle gegevens zijn volledig gedefinieerd in de BHR-P catalogus.

• broId (BRO-ID).
• deregistered (uit registratie genomen).
• deregistrationTime (tijdstip uit registratie genomen).

BHR_C

Het uitgiftedocument van het type BHR_C is een specialisatie van AbstractCharacteristics in de package brocommon, wat op zijn beurt een specialisatie is van AbstractRegistrationObject in de package brocommon. Dit uitgiftedocument bestaat uit de onderstaande gegevens. Alle gegevens zijn volledig gedefinieerd in de BHR-P catalogus.

• broId (BRO-ID).
• deregistered (uit registratie genomen).
• deliveryAccountableParty (bronhouder)
• qualityRegime (kwaliteitsregime)
• objectRegistrationTime (tijdstip registratie object)
• latestCorrectionTime (tijdstip laatste correctie)
• underReview (in onderzoek)
• standardizedLocation (gestandaardiseerde locatie)
• deliveredLocation (aangeleverde locatie)
• localVerticalReferencePoint (lokaal verticaal referentiepunt)
• offset (verschuiving)
• verticalDatum (verticaal referentievlak)
• researchReportDate (rapportagedatum onderzoek)
• boringStartDate (startdatum boring)
• boringEndDate (einddatum boring)
• beginDepth (begindiepte boring)
• endDepth (einddiepte boring)
• surveyPurpose (kader inwinning)
• boreholeSamplesDescribed (boormonsters beschreven)
• boreholeSamplesAnalyzed (boormonsters geanalyseerd)
• boreholeSamplesPhotographed (boormonsters gefotografeerd)
• fractionDistributionDetermined (fracteverdeling bepaald)
• discipline (vakgebied)
• boringToolTypeOverview (overzicht boortypes)

Het BoringToolTypeOverview (Overzicht boortypes) bestaat uit een lijst van boortypes:

• boringToolType (boortype)

Objectgegevens

De BHR-P uitgiftewebservice kent drie types uitgiftedocumenten die kunnen worden opgenomen in een DispatchDataResponse (Bericht van verzending van objectgegevens). Zie onderstaande tabel. Welke verschijningsvorm wordt aangenomen, hangt af van de identiteit van de afnemer en het feit of het registratieobject uit registratie is genomen of niet.

Onderstaande figuur geeft de uitgiftedocumenten weer inclusief de mogelijke inhoud. Alle gegevens zijn volledig gedefinieerd in de BHR-P catalogus.

Attributen met een minteken voor hun naam (in plaats van een plusteken) worden alleen uitgeleverd als de afnemer tevens bronhouder en/of dataleverancier is van het opgevraagde registratieobject. Met andere woorden, deze gegevens worden alleen opgenomen in het dispatchDocument (uitgiftedocument) BHR_O_DP.

Attributen met een deelteken voor hun naam worden niet aangeboden in een brondocument bij de innamewebservice. In plaats daarvan wordt een waarde voor deze gegevens afgeleid door het BRO-systeem.

Attributen met de tekst 'id' tussen accolades achter de naam zijn gegevens die een object (een voorkomen van een FeatureType (Objecttype)) uniek identificeren.

BRO_DO

Het BRO_DO uitgiftedocument heeft als type BRO_DOType zoals gedefiieerd in de package brocommon, wat een specialisatie is van AbstractRegistrationObject in de package brocommon. Dit uitgiftedocument bestaat uit de volgende gegevens:

• broId (BRO-ID).
• deregistered (uit registratie genomen).
• deregistrationTime (tijdstip uit registratie genomen)

BHR_O_DP

Het BHR_O_DP uitgiftedocument heeft als type BoreholeResearchType zoals gedefinieerd in de package dsbhr-messages, wat een specialisatie is van RegistrationObject in de package brocommon, wat op zijn beurt een specialisatie is van AbstractRegistrationObject in de package brocommon. Dit uitgiftedocument bevat alle gegevens uit de BHR-P catalogus, inclusief de afgeleide gegevens in RegistrationHistory (Registratiegeschiedenis), ReportHistory (Rapportagegeschiedenis), IntermediateEvent (Tussentijdse gebeurtenis) en StandardizedLocation (Gestandaardiseerde locatie).

BHR_O

Het BHR_O uitgiftedocument heeft als type BoreholeResearchType zoals gedefinieerd in de package dsbhr-messages, wat een specialisatie is van RegistrationObject in de package brocommon, wat op zijn beurt een specialisatie is van AbstractRegistrationObject in de package brocommon. Dit uitgiftedocument bevat alle gegevens uit de BHR-P catalogus, inclusief de afgeleide gegevens in RegistrationHistory (Registratiegeschiedenis), ReportHistory (Rapportagegeschiedenis), IntermediateEvent (Tussentijdse gebeurtenis) en StandardizedLocation (Gestandaardiseerde locatie), met uitzondering van de volgende gegevens:

• objectIdAccountableParty (object-ID bronhouder) in RegistrationObject (Booronderzoek)
• deliveryResponsibleParty (dataleverancier) in RegistrationObject (Booronderzoek)
• researchOperator (uitvoerder onderzoek) in BoreholeResearch (Booronderzoek)
• horizontalPositioningOperator (uitvoerder locatiebepaling) in DeliveredLocation (Aangeleverde locatie)
• verticalPositioningOperator (uitvoerder verticale positiebepaling) in DeliveredVerticalPosition (Aangeleverde verticale positie)
• boringOperator (uitvoerder boring) in Boring (Boring)
• descriptionOperator (uitvoerder beschrijving) in BoreholeSampleDescription (Boormonsterbeschrijving)
• analysisOperator (uitvoerder analyse) in BoreholeSampleAnalysis (Boormonsteranalyse)

Voorbeeldberichten

Dit hoofdstuk geeft een toelichting bij enkele voorbeeldberichten.

Paragraaf 3.1 bevat een opsomming van beschikbare voorbeeldberichten, hun intentie en een summiere beschrijving van de inhoud.

Paragraaf 3.2 bevat een gedetailleerde beschrijving van kleine, bijzondere stukken uit de voorbeeldberichten.

Integrale voorbeeldberichten

De integrale voorbeeldberichten kunnen gedownload worden van de GitHub website (https://github.com/BROprogramma/BHR-P/tree/gh-pages/Berichtencatalogus/uitgifteservice). De onderstaande tabel bevat een opsomming van de 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.

Kop van een BRO-bericht 

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

Regel 2 bevat de opening tag van het type BRO-bericht als root XML-element. Dat kan zijn:

• Een dispatchDataRequest (verzoek tot uitgifte van objectgegevens).
• Een dispatchCharacteristicsRequest (verzoek tot uitgifte van kengegevens).
• Een  dispatchDataResponse (bericht van verzending van objectgegevens).
• Of een DispatchCharacteriscticsResponse (bericht van verzending van kengegevens).

Regel 3 t/m 10 bevatten de namespaces van de gebruikte XML-schemadefinities (XSD's) als XML-attributen van het root XML_element. Het aantal namespaces is afhankelijk van de inhoud van het BRO-bericht.

De laatste twee XML-attributen op regel 11 en 12 (xmlns:xsi en xsi:schemaLocation) maken het mogelijk om het BRO-bericht te valideren tegen de XSD-bestanden van de uitgiftewebservice. Deze twee attributen mogen weggelaten worden. In het onderstaande voorbeeld heeft de URL van de xsi:schemalocation de waarde ../../XSD/dsbhr-messages.xsd. Dit is een relatief pad naar een lokaal bestand, met een mappenstructuur alsof de GitHub repo is gecloned naar een lokale repo. Deze waarde is met name bedoeld tijdens de projectfase voordat de uitgiftewebservice beschikbaar is. De laatste regel van de disclaimer bevat de waarde voor de xsi:schemalocation zoals die in de productiefase opgenomen zal worden. Vanaf dat moment kunnen de XSD-bestanden vanaf die URL gedownload worden.

Regel 14 t/m 17 bevatten een disclaimer.

Na de disclaimer volgen gegevens van het BRO-bericht. Die zijn uiteraard afhankelijk van het type BRO-bericht. Zie hoofdstuk 2 en de gegevenscatalogus voor nadere informatie.

Het BRO-bericht wordt afgesloten met een closing tag van het type BRO-bericht.

<?xml version="1.0" encoding="UTF-8"?>
<dispatchDataResponse
        xmlns="http://www.broservices.nl/xsd/dsbhr/2.0"
        xmlns:bhrcom="http://www.broservices.nl/xsd/bhrcommon/2.0"
        xmlns:srcom="http://www.broservices.nl/xsd/srcommon/1.0"
        xmlns:brocom="http://www.broservices.nl/xsd/brocommon/3.0"
        xmlns:om="http://www.opengis.net/om/2.0"
        xmlns:swe="http://www.opengis.net/swe/2.0"
        xmlns:gml="http://www.opengis.net/gml/3.2"
        xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.broservices.nl/xsd/dsbhr/2.0 ../../XSD/dsbhr-messages.xsd"
>
    <!-- Disclaimer: dit voorbeeldbericht valideert tegen de XSD van de uitgiftewebservice.
         Het is niet gevalideerd door de uitgiftewebservice en is vaktechnisch/inhoudelijk niet voorbeeldig.
        xsi:schemaLocation="http://www.broservices.nl/xsd/dsbhr/2.0 https://schema.broservices.nl/xsd/dsbhr/2.0/dsbhr-messages.xsd"
    -->
    ...
</dispatchDataResponse>

Area 

Een area (gebied) is een verplicht onderdeel van de criteria (kenmerken) van een dispatchCharacteristicsRequest (verzoek tot uitgifte van kengegevens). Een area (gebied) geeft de begrenzing aan van een geografisch gebied aan het aardoppervlak, in de vorm van een cirkel of een rechthoek.

Een cirkel wordt gedefinieerd door het middelpunt en de straal. Het middelpunt is een coördinatenpaar uitgedrukt in een referentiestelsel. De straal is een meetwaarde, waarbij het XML-attribuut uom (eenheid) aangeeeft dat de straal wordt uitgedrukt in kilometers.

De rechthoek wordt aangeduid door twee coördinatenparen, de onderhoek en de bovenhoek, beiden uitgedrukt in een referentiestelsel.

Voor alle coördinatenparen van een area (gebied) geldt dat het XML-attribuut srsName (referentiestelsel) de waarde urn:ogc:def:crs:EPSG::4258 (ETRS89) moet hebben. Dan bestaat een coördinatenpaar uit twee hoeken, de latitude en de longitude in die volgorde, geschieden door een spatie en met een punt als decimaal scheidingsteken. Zie onderstaande voorbeelden. Het XML-attribuut srsDimension (aantal dimensies) geeft aan uit hoeveel ordinaten een coördinaat is opgebouwd. Dit XML-attribuut is optioneel en moet indien aanwezig de waarde 2 hebben (een coördinaat bestaat uit een coördinatenpaar).

...
<brocom:area>
    <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>
</brocom:area>
...
<brocom:area>
    <brocom:boundingBox srsName="urn:ogc:def:crs:EPSG::4258" srsDimension="2">
        <gml:lowerCorner>52.1 5.0</gml:lowerCorner>
        <gml:upperCorner>52.3 5.2</gml:upperCorner>
    </brocom:boundingBox>
</brocom:area>
...

Date en DateTime

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

<brocom:date>2020-11-10</brocom:date>

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. Bijvoorbeeld:

<brocom:dispatchTime>2020-11-10T09:09:43+01:00</brocom:dispatchTime>

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

dispatchDocument

Een dispatchResponse (bericht van verzending) bevat 0, 1 of meerdere uitgiftedocumenten; zie de paragrafen 2.2.5 en 2.2.6. Zoals beschreven in paragraaf 2.3 kent de BHR-P uitgiftewebservice 5 types uitgiftedocumenten. De UML-diagrammen geven aan dat alle uitgiftedocumenten direct of indirect een specialisatie zijn van AbstractRegistrationObject en daarmee een FeatureType zijn. Welke types uitgiftedocumenten uitgegeven kunnen worden hangt af van het type dispatchResponse:

• dispatchCharacteristicsResponse (bericht van verzending van kengegevens)
  • brocom:BRO_DO: gegevens van een registratieobject dat uit registratie is genomen.
  • dsbhr:BHR_C: kengegevens van een registratieobject dat niet uit registratie is genomen.
• dispatchDataResponse (bericht van verzending van objectgegevens)
  • brocom:BRO_DO: gegevens van een registratieobject dat uit registratie is genomen.
  • dsbhr:BHR_O: objectgegevens van een bodemkundig booronderzoek dat niet uit registratie is genomen, opgevraagd door een afnemer die niet bronhouder noch dataleverancier is van het opgevraagde registratieobject.
  • dsbhr:BHR_O_DP: objectgegevens van een bodemkundig booronderzoek dat niet uit registratie is genomen, opgevraagd door een afnemer die tevens bronhouder en/of dataleverancier is van het opgevraagde registratieobject.

Conform de GML XML encoding rules wordt het property type pattern toegepast bij het omzetten van de gegevensdefinitie in UML naar de berichtdefinities in XML. Onderstaande voorbeeld van een stukje XML laat zien hoe dat uitpakt. Na de opening tag dispatchDocument (uitgiftedocument) volgt een regel met, bijvoorbeeld, brocom:BRO_DO. Deze regel geeft aan dat het uitgiftedocument van dit type is. Het element BRO_DO is als root element gedefinieerd in het XSD-bestand brocommon.xsd. De andere types uitgiftedocumenten zijn gedefinieerd in het XSD-bestand dsbhr-messages.xsd van de BHR-P uitgiftewebservice. Na deze regel komt het eerste XML-element van het betreffende type uitgiftedocument, in het voorbeeld brocom:broID.

...
<dispatchDocument>
    <brocom:BRO_DO gml:id="id_0001">
        <brocom:broId>...</brocom:broId>
        ...
    </brocom:BRO_DO>
</dispatchDocument>
...

Dit property type pattern is niet alleen toegepast bij het XML-element dispatchDocument (uitgiftedocument). Andere voorbeelden zijn:

• phenomenonTime (datum voltooiing beschrijving) van het type om:TimeObjectPropertyType.
• boreholeSampleAnalysis (boormonsteranalyse) van het type bhrcom:BoreholeSampleAnalysisPropertyType.
• investigatedInterval (onderzocht interval) van het type bhrcom:InvestigatedIntervalPropertyType.
• pHDetermination (bepaling zuurgraad) van het type srcom:PHDeterminationPropertyType.

gml:id

De BHR-P gegevensdefinitie maakt een onderscheid tussen objecttypes en gegevensgroeptypes. Bij het opstellen van de berichtdefinities worden deze stereotypes vertaald naar FeatureType en AttributeGroupType. Twee van de verschillen zijn dat een FeatureType identificeerbaar is en dat een AttributeGroupType alleen bestaat bij de gratie van een FeatureType waarvan het, direct of indirect, een onderdeel is.

Conform de GML XML encoding rules leidt ieder FeatureType in de XSD-bestanden 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 de realisatie is van een associatie relatie in de gegevenscatalogus naar het FeatureType.

Als gevolg van de eerste bullet krijgt in een XML-bericht ieder betreffend XML-element een XML-attribuut gml:id. De waarde van deze gml:id moet uniek zijn binnen het BRO-bericht. De waarde van een gml:id mag maar hoeft niet uniek te zijn over meerdere BRO-berichten, over meerdere registratieobjecten of over meerdere registratieobjecttypes. In de voorbeeldberichten is dit gedaan met een waarde die begint met 'id_', gevolgd door een volgnummer. De innamewebservice van het BRO-systeem slaat de waarde van een gml:id in een innameverzoek niet op. De uitgiftewebservice van het BRO-systeem genereert per dispatchResponse (bericht van verzending) unieke waarden voor de aanwezige gml:id XML-attributen.

Enkele voorbeelden:

...
<BHR_O_DP gml:id="id_0001">
...
<brocom:location srsName="urn:ogc:def:crs:EPSG::4258" gml:id="id_0002">
...
<boreholeSampleDescription gml:id="id_0004">
...
<gml:TimeInstant gml:id="id_0005">
...
<bhrcom:BoreholeSampleAnalysis gml:id="id_0007">
...
<bhrcom:InvestigatedInterval gml:id="id_0008">
...

Codelist

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. Bij een codelijst is de lijst met toegestane waarden niet opgenomen in de XSD-bestanden.

Voor codelijsten volgt de BRO de GML XML encoding rules voor een CodeType. Dit is een algemeen patroon. Het voegt een XML-attribuut codeSpace toe aan een XML-element, waarvan de waarde verwijst naar een catalogus, thesaurus, classificatie schema of autoriteit voor de codelijst. Als conventie bestaat de waarde van het XML-attribuut uit een URN, bv.: urn:bro:bhr:DeliveryContext. Hoofdstuk 5 bevat een overzicht van de codelijsten en hun URN waarde. De gegevenscatalogus bevat per codelijst de toegestane waarden, zoals gedefinieerd op het moment dat de gegevenscatalogus werd vastgesteld.

Onderstaand een voorbeeld van een XML-element, waarvan de waarde publiekeTaak  een waarde uit de codelijst is:

<deliveryContext codeSpace="urn:bro:bhr:DeliveryContext">publiekeTaak</deliveryContext>

PartialDate

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

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

Onderstaande voorbeelden geven mogelijk waarden met afnemende nauwkeurigheid.

Het gegeven researchReportDate (datum rapportage) heeft als type een brocom:PartialDateType. In de BHR-P gegevenscatalogus het dit gegeven als type een Datum onder kwaliteitsregime IMBRO en een OnvolledigeDatum onder IMBRO/A.

<researchReportDate>
	<!--You have a CHOICE of the next 4 items at this level
		<brocom:date>2020-08-31</brocom:date>
		<brocom:yearMonth>2020-08</brocom:yearMonth>
		<brocom:year>2020</brocom:year>
		<brocom:voidReason>onbekend</brocom:voidReason> 
    -->
	<brocom:date>2020-08-31</brocom:date>
</researchReportDate>

Organization.

De BHR-P gegevenscatalogus definieert een aantal uitvoerders. Deze hebben een Organisatie als gegevenstype. Bijvoorbeeld:

• researchOperator (uitvoerder onderzoek)
• horizontalPositioningOperator (uitvoerder locatiebepaling)
• verticalPositioningOperator (uitvoerder verticale positiebepaling)
• boringOperator (uitvoerder boring)
• descriptionOperator (uitvoerder beschrijving)
• analysisOperator (uitvoerder analyse)

Het complexType Organization (Organisatie) biedt de keuze tussen een chamberOfCommerceNumber (kamer van koophandelnummer) of een europeanCompanyRegistrationNumber (Europees handelsnummer). Hieronder twee voorbeelden:

...
<researchOperator>
  <brocom:chamberOfCommerceNumber>27376655</brocom:chamberOfCommerceNumber>
</researchOperator>
...
<analysisOperator>
  <brocom:europeanCompanyRegistrationNumber>DER2507_R2</brocom:europeanCompanyRegistrationNumber>
</analysisOperator>
...

gml:Point

De BHR-P gegevenscatalogus definieert voor de StandardizedLocation (Gestandaardiseerde locatie) en de DeliveredLocation (Aangeleverde locatie) onder andere de volgende twee attributen:

• Coördinaten: De coördinaten die zijn aangeleverd.
• Referentiestelsel: Het referentiestelsel van de aangeleverde coördinaten.

Conform de GML XML encoding van NEN3610 worden deze twee attributen uitgewisseld met een gml:Point, bestaande uit:

• XML-element gml:pos - het coördinatenpaar
• XML-attribuut srsName - een verwijzing naar het referentiestelsel waarin het coördinatenpaar is uitgedrukt.
• XML-attribuut gml:id - een unieke identificatie van het object

Het bereik en de betekenis van het coördinatenpaar is afhankelijk van het gebruikte referentiestelsel. Onderstaande tabel geeft per referentiestelsel de waarde voor het XML-attribuut srsName en de betekenis, de eenheid en volgorde van de ordinaten in het coördinatenpaar.

Voorbeeld van de XML-encoding voor dezelfde locatie in RD en in ETRS89:

...
<location gml:id="BRO_0001" srsName="urn:ogc:def:crs:EPSG::28992">
  <gml:pos>139794.52 455443.35</gml:pos>
</location>
...
<location gml:id="BRO_0001" srsName="urn:ogc:def:crs:EPSG::4258">
  <gml:pos>52.0870447 5.1653503</gml:pos>
</location>
...

gml:Measure

De BHR-P 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, maar wordt het XML attribuut uom (eenheid) wel opgenomen. Zie onderstaande voorbeelden voor een offset (verschuiving) met en zonder een waarde.

...
<bhrcom:offset uom="m">-1.38</bhrcom:offset>
...
<bhrcom:offset uom="m" xsi:nil="true"/>
...

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

BoreholeSampleDescription

De BHR-P gegevenscatalogus definieert de Boormonsterbeschrijving als een entiteit met 6 attributen en twee gegevensgroepen voor de Bodemclassificatie en het Boorprofiel:

Bij het logisch model en dientengevolge de XSD-bestanden is de O&M (Observations and measurements) standaard van het OGC (Open Geospatial Consortium) toegepast. De BoreholeSampleDescription (Boormonsterbeschrijving) is een specialisatie van BHRObservation, wat op zijn beurt een specialisatie is van OM_Observation uit de package om-profile. Daarbij vervangt BHRObservation het result van het type Any van OM_Observation uit de package om-profile door een result van het type DescriptiveBoreholeLog (Boorprofiel).

De attributen phenomenonTime en resultTime van de entiteit OM_Observation worden gevuld met de waarde van het attribuut descriptionCompletionDate (datum voltooiing beschrijving) van de entiteit BoreholeSampleDescription (Boormonsterbeschrijving) uit de gegevenscatalogus. Voor de relaties featureOfInterest, procedure en observedProperty is geen geschikt gegeven beschikbaar; deze verplichte relaties zijn wel nillable/voidable (mag geen waarde hebben), dus worden deze XML-elementen opgenomen met een lege waarde. De optionele relatie relatedObservation wordt niet gebruikt en blijft achterwege.

Het type BoreholeSampleDescription (Boormonsterbeschrijving ) voegt de overige 5 attributen van de entiteit Boormonsterbeschrijving toe en de gegevensgroep SoilClassification (Bodemclassificatie).

Onderstaand volgt een voorbeeld van een BoreholeSampleDescription (Boormonsterbeschrijving).

<boreholeSampleDescription gml:id="id_0004">
    <om:phenomenonTime>
        <gml:TimeInstant gml:id="id_0005">
            <gml:timePosition indeterminatePosition="unknown"/>
        </gml:TimeInstant>
    </om:phenomenonTime>
    <om:resultTime>
        <gml:TimeInstant gml:id="id_0006">
            <gml:timePosition indeterminatePosition="unknown"/>
        </gml:TimeInstant>
    </om:resultTime>
    <om:procedure xsi:nil="true"/>
    <om:observedProperty xsi:nil="true"/>
    <om:featureOfInterest xsi:nil="true"/>
    <bhrcom:result xsi:type="bhrcom:DescriptiveBoreholeLogType">
        <bhrcom:sampleQuality codeSpace="urn:bro:bhr:SampleQuality">ongeroerd</bhrcom:sampleQuality>
        <bhrcom:rootPenetrableDepthReached>ja</bhrcom:rootPenetrableDepthReached>
        <bhrcom:rootPenetrableDepth uom="m">1.00</bhrcom:rootPenetrableDepth>
        ...
    </bhrcom:result>
    <bhrcom:descriptionMethod codeSpace="urn:bro:bhr:DescriptionMethod">AlterraTD19A</bhrcom:descriptionMethod>
    <bhrcom:descriptionLocation codeSpace="urn:bro:bhr:DescriptionLocation">veld</bhrcom:descriptionLocation>
    <bhrcom:descriptionOperator>
        <brocom:chamberOfCommerceNumber>27376655</brocom:chamberOfCommerceNumber>
    </bhrcom:descriptionOperator>
    <bhrcom:fractionDistributionDetermined>nee</bhrcom:fractionDistributionDetermined>
    <bhrcom:lowerBoundarySandFraction codeSpace="urn:bro:bhr:LowerBoundarySandFraction">50</bhrcom:lowerBoundarySandFraction>
    <bhrcom:soilClassification>
        ...
    </bhrcom:soilClassification>
</boreholeSampleDescription>

Het complexType BoreholeSampleDescription (Boormonsterbeschrijving) is een specialisatie van OM_Observation en daarmee een <<FeatureType>>. Daardoor heeft het een XML-attribuut gml:id met een waarde die uniek is binnen het BRO-bericht.

De XML-elementen phenomenonTime en resultTime zijn beiden van het type om:TimeObjectPropertyType uit het O&M profiel. Zoals de naam gml:TimeObjectPropertyType aangeeft wordt het GML XML property type pattern toegepast. Het kind XML-element gml:TimeInstant geeft aan dat de waarde in het feitelijke BRO-bericht van dit type is. Het type om:TimeObjectPropertyType is indirect een specialisatie van AbstractGML, zodat het gml:TimeInstant XML-element een XML-attribuut gml:id krijgt met een waarde die uniek is binnen het BRO-bericht.

Het XML-element gml:TimeInstant heeft als type gml:timePosition. De BHR-P gegevenscatalogus definieert voor het attribuut 'datum voltooiing beschrijving' een type Datum onder kwaliteitsregime IMBRO en een type OnvolledigeDatum onder kwaliteitsregime IMBRO/A. Onderstaande tabel geeft een aantal voorbeelden van mogelijke waarden. Het type gml:timePosition ondersteunt ook een dateTime (datum en tijd) als waarde met als opbouw: JJJJ-MM-DDThh:mm:ss+hh:mm, maar die keuzemogelijkheid biedt de BHR-P gegevenscatalogus niet voor het attribuut 'datum voltooiing beschrijving'.

De codering voor het XML-element bhrcom:result volgt niet het GML XML property type pattern. In plaats daarvan geeft het XML-attribuut xsi:type aan wat het complexType van het resultaat is.

Na het XML-element bhrcom:result volgen de XML-elementen bhrcom:descriptionMethod (beschrijfmethode) t/m bhrcom:lowerBoundarySandFraction (ondergrens zandfractie) en daarna de gegevensgroep bhrcom:soilClassification (bodemclassificatie).

Resultaten van bepalingen

De BHR-P gegevenscatalogus definieert voor een aantal bepalingen een meetreeks. Daarbij wordt op gezette tijden (of bij bepaalde waarden van een andere onafhanelijke grootheid) steeds een aantal parameters gemeten. Hetzelfde patroon komt voor bij een tweetal karakteristieken, waar de punten op een curve worden gedefinieerd.

Omdat het in deze situaties potentieel om een groot aantal waarden kan gaan, worden deze parameterwaarden niet uitgeleverd als XML-elementen, maar wordt er gebruikt gemaakt van een compacte codering volgens de SWE (Sensor Web Enablement) standaard van het OGC (Open Geospatial Consortium). De meetreeks (of de karakteristiek) is daarbij gemodelleerd als een swe:DataArray. De gemeten parameterwaarden worden gemodelleerd als een swe:DataRecord.

Een swe:DataArray bestaat uit vier XML-elementen:

• elementCount: het aantal verzamelingen van parametermeetwaarden in de reeks.
• elementType: beschrijving van de meetwaarden in een dataRecord.
• encoding: aanduiding voor de codering van:
  • Een decimalSeparator (decimaalscheidingsteken) voor de parameterwaarden in een DataRecord.
  • Een tokenSeparator (tokenscheidingsteken) om de parameterwaarden binnen een DataRecord te scheiden.
  • Een blockSeparator (recordscheidingsteken) om de DataRecords binnen de reeks te scheiden.
• values: de 'CSV'-gecodeerde reeks van dataRecords met de parameterwaarden.

Het DataRecord met de beschrijving van de parameterwaarden kan in-line worden opgenomen of externe gedefinieerd worden. Bij de BRO is ervoor gekozen om de definitie van de swe:DataRecords niet in-line op te nemen, maar om deze centraal vast te leggen. In een DataArray wordt dan een verwijzing (xlink:href) opgnomen naar het bestand met daarin een DataRecord. De bestanden met de DataRecords kunnen gedownload worden vanaf dezelfde locatie als de XSD-bestanden (zie paragraaf 3.2.1).

Voor iedere parameterwaarde moet een waarde opgenomen worden in het XML-element values (waarden) van een DataArray. Het DataRecord geeft aan hoe het ontbreken van een waarde moet worden weergegeven door middel van een nilValue.

Onderstaande tabel geeft een samenvatting van de meetreeksen en karakteristieken in de BHR-P gegevenscatalogus waar dit swe patroon is toegepast, de XML-elementen die dientengevolge het datatype swe:DataArray hebben gekregen en de bijbehorende XML-bestanden waarin de definities van de swe:DataRecords zijn opgenomen.

Hieronder een voorbeeld van een meetreeks voor de krimptoestand bestaande uit 4 dataRecords:

...
<srcom:shrinkage>
    <swe:DataArray id="id_0017">
        <swe:elementCount>
            <swe:Count>
                <swe:value>14</swe:value>
            </swe:Count>
        </swe:elementCount>
        <swe:elementType name="krimptoestand" xlink:href="https://schema.broservices.nl/xsd/srcommon/1.0/meetreeksen/ShrinkageState.xml"/>
        <swe:encoding>
            <swe:TextEncoding collapseWhiteSpaces="true" decimalSeparator="." tokenSeparator="," blockSeparator=";"/>
        </swe:encoding>
        <swe:values>66.4,39.4,NaN,NaN;65.5,38.8,NaN,NaN;64.8,38.4,NaN,NaN;60.8,35.4,NaN,NaN</swe:values>
    </swe:DataArray>
</srcom:shrinkage>
...

De inhoud van het beschrijvende XMl bestand is dan

<?xml version="1.0" encoding="UTF-8"?>
<swe:DataRecord
        id="ShrinkageStateType"
        xmlns:swe="http://www.opengis.net/swe/2.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.opengis.net/swe/2.0 swe-profile.xsd">
	<swe:label>ShrinkageState resultaat record</swe:label>
	<swe:description>Beschrijving/formaat van de parameters van een ShrinkageState</swe:description>
	<swe:field name="mass">
	<swe:Quantity>
		<swe:uom code="gr"></swe:uom>
	</swe:Quantity>
	</swe:field>
	<swe:field name="volume">
	<swe:Quantity>
		<swe:uom code="cm3"></swe:uom>
	</swe:Quantity>
	</swe:field>
	<swe:field name="height">
		<swe:Quantity>
			<swe:nilValues>
				<swe:NilValues>
					<swe:nilValue reason="urn:ogc:def:nil:OGC:unknown">NaN</swe:nilValue>
				</swe:NilValues>
			</swe:nilValues>
			<swe:uom code="cm"></swe:uom>
		</swe:Quantity>
	</swe:field>
	<swe:field name="diameter">
		<swe:Quantity>
			<swe:nilValues>
				<swe:NilValues>
					<swe:nilValue reason="urn:ogc:def:nil:OGC:unknown">NaN</swe:nilValue>
				</swe:NilValues>
			</swe:nilValues>
			<swe:uom code="cm"></swe:uom>
		</swe:Quantity>		
	</swe:field>
</swe:DataRecord>

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 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 enumeraties die van belang zijn bij een BRO-bericht. 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-bericht.

Codelijsten

Dit hoofdstuk bevat verwijzingen (URN's en URL's) van de codelijsten. In de gegevenscatalogus worden deze beheerde waardenlijsten genoemd.

Bij een codelijst kan de lijst met toegestane waarden worden aangepast zonder dat aanpassingen nodig zijn in de berichtdefinities (XSD-bestanden) en/of de software (voor het maken of verwerken van een bericht). De gegevenscatalogus bevat per codelijst de toegestane waarden, zoals gedefinieerd op het moment dat de gegevenscatalogus werd vastgesteld.

De onderstaande tabel geeft een overzicht van de codelijsten die van belang zijn bij het maken van een BRO-bericht over een bodemkundig booronderzoek.

• 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 URI (URN or URL), die in een BRO-bericht gebruikt moet worden bij het XML-attribuut codeSpace. Zie de voorbeeldberichten voor nadere informatie.
• De vierde kolom bevat een link naar de website waar de actuele lijst met toegestane waarden is te raadplegen.

Overzicht met BHR-P codelijsten:

Vertaallijst

Dit hoofdstuk bevat een vertaaltabel aan de hand waarvan, gegeven de Engelstalige naam van een complexType/element in de XSD-bestanden, de Nederlandse naam van de entiteit en het attribuut 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.