BHR-G voorbeeldberichten innameservices

Disclaimer - De voorbeeldberichten zijn bedoeld voor ontwikkeling van eigen software om aan te sluiten op de BRO. Onderstaande berichten zijn getest op de BRO-services waarbij attribuutvelden waarden hebben meegekregen. Deze berichten zijn niet bedoeld als template om uiteindelijke brondocumenten te genereren.

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

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

3.1. Integrale voorbeeldberichten

De onderstaande tabel bevat een opsomming van de beschikbare voorbeeldberichten, hun intentie en een summiere beschrijving van de inhoud.

3.2. Code snippets.

Deze paragraaf bevat voor een aantal kleine, bijzondere stukken XML-code uit de voorbeeldberichten een gedetailleerde beschrijving.

3.2.1. De kop van een registrationRequest

De eerste regel van het voorbeeldbericht 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 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 BHR-G innameservice. Deze twee attributen mogen weggelaten worden. In het voorbeeldbericht heeft de URL van de schemalocation de waarde ../../XSD/isbhr-g-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 in de projectfase voordat de BHR-G innameservice beschikbaar is. De laatste regel van de disclaimer bevat de waarde voor de schemalocation zoals die in de productiefase opgenomen zal worden. Vanaf dat moment kunnen de XSD-bestanden vanaf die URL gedownload worden.

Na de disclaimer in regel 9 t/m 12 volgen vier transactiegegevens: requestReference (verzoekkenmerk), deliveryAccountableParty (bronhouder) en qualityRegime (kwaliteitsregime). Het element broId (BRO-ID) wordt niet opgenomen als het sourceDocument een BHR_G_CompleteReport is, Zie hoofdstuk 2 voor nadere informatie.

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

<?xml version="1.0" encoding="UTF-8"?>
<registrationRequest
    xmlns="http://www.broservices.nl/xsd/isbhrg/3.1"
    xmlns:bhrgcommon="http://www.broservices.nl/xsd/bhrgcommon3.1"
    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/isbhrg/3.1 ../../XSD/isbhr-g-messages.xsd">
  <!--Disclaimer: dit voorbeeldbericht valideert tegen de XSD van de innameservice.
      Het is niet gevalideert door de innameservice en is vaktechnisch/inhoudelijk niet voorbeeldig.
    xsi:schemaLocation="http://www.broservices.nl/xsd/isbhrg/3.1 https://schema.broservices.nl/xsd/isbhrg/3.1/isbhr-g-messages.xsd">
  -->
  <brocom:requestReference>BRO-BHR-G-1596</brocom:requestReference>
  <!-- Optional: -->
  <brocom:deliveryAccountableParty>27376655</brocom:deliveryAccountableParty>
  <!--Optional: not allowed in combination with sourceDocument BHR_G_CompleteReport.
  <brocom:broId>?</brocom:broId>
  -->
  <brocom:qualityRegime>IMBRO</brocom:qualityRegime>
  <sourceDocument>
    ...
  </sourceDocument>
</registrationRequest>

3.2.2. Brondocument

Een BRO-verzoek bevat een brondocument, wat de eenheid van aanleveren is. Zoals beschreven in paragraaf 2.3 kent versie 1.0 van de BHR-G innamewebservice 1 type brondocument. De UML-diagrammen geven aan dat het stereotype  van het brondocument FeatureType is. 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. Onderstaand stukje XML van een voorbeeldbericht laat zien hoe dat uitpakt. Na de opening tag sourceDocument van het brondocument volgt een regel met BHR_G_CompleteReport. Deze regel geeft aan dat in dit bericht dit type brondocument wordt aangeleverd. Na deze regel komt het eerste XML element van het BHR_G_CompleteReport brondocument.

...
<sourceDocument>
  <BHR_G_CompleteReport gml:id="id_0001">
    <objectIdAccountableParty>myIdForThisBoreholeResearch</objectIdAccountableParty>
    ...
  </GLD_StartRegistration>
</sourceDocument>
...

3.2.3. gml:id

De BHR-G 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 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 betreffend XML-element een XML-attribuut gml:id. 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 slaat de waarden van deze gml:id niet op.

Enkele voorbeelden:

...
<BHR_G_CompleteReport gml:id="id_0001">
...
<gml:Point gml:id="id_0002" srsName="urn:ogc:def:crs:EPSG::28992">
...
<bhrgcommon:BoreholeSampleDescription gml:id="id_0003">
...
<bhrgcommon:DescriptiveBoreholeLog gml:id="id_0004">
...

3.2.4. Waarde uit een codelijst

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:bhrg:SurveyPurpose. 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 gebiedsmodelOrdeningOndergrond een waarde uit een codelijst is:

<surveyPurpose codeSpace="urn:bro:bhrg:SurveyPurpose">gebiedsmodelOrdeningOndergrond</surveyPurpose>

3.2.5. Datum

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

<researchReportDate>2020-08-01</researchReportDate>

3.2.6. Organisatie

De BHR-G gegevenscatalogus definieert een aantal uitvoerders. Deze hebben een Organization (Organisatie) als gegevenstype. Bijvoorbeeld:

• researchOperator (uitvoerder onderzoek)

• horizontalPositioningOperator (uitvoerder locatiebepaling)

• verticalPositioningOperator (uitvoerder verticale positiebepaling)

• descriptionOperator (uitvoerder beschrijving)

• boringOperator (uitvoerder boring)

Het gegevenstype Organization (Organisatie) biedt de keuze tussen een kamer van koophandelnummer of een Europees handelsnummer. Hieonder twee voorbeelden van beide gevallen:

...
<researchOperator>
  <brocom:chamberOfCommerceNumber>52754834</brocom:chamberOfCommerceNumber>
</researchOperator>
...
<bhrgcommon:boringOperator>
  <brocom:europeanCompanyRegistrationNumber>DEB8537.HRB66039</brocom:europeanCompanyRegistrationNumber>
</bhrgcommon:boringOperator>
...

3.2.7. Locatie

De BHR-G gegevenscatalogus definieert voor 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 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, 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>
...

3.2.8. Meetwaarde

De BHR-G 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). Bijvoorbeeld een offset (verschuiving) van 1,38 meter onder NAP voor de deliveredVerticalPosition (Aangeleverde verticale positie) wordt:

...
<bhrgcommon:offset uom="m">-1.38</bhrgcommon:offset>
...

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. Deze afkorting van de eenheid staat genoemd in de XSD.