Berichtencatalogus Innamewebservice SFR

Inleiding

Dit document beschrijft hoe een bronhouder en/of dataleverancier de gegevens over een bodemkundig wandonderzoek (SFR) kan opnemen in een verzoek voor de Basisregistratie Ondergrond (BRO).

Het document veronderstelt dat de lezer bekend is met de SFR catalogus en het Bronhouderportaal. 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. Vervolgstappen, zoals het valideren (testen), aanbieden en verwerken van een BRO-verzoek, staan beschreven in het Bronhouderportaal (zie www.basisregistratieondergrond.nl).

Leeswijzer

Hoofdstuk 2 beschrijft de algemene opbouw van een BRO-verzoek.

Hoofdstuk 3 bevat een toelichting op enkele voorbeeldberichten.

Hoofdstuk 4 bevat de toegestane waarden van de gebruikte enumeraties (niet-beheerde waardenlijsten).

Hoofdstuk 5 bevat verwijzingen (URL's) naar de websites met toegestane waarden van de codelijsten (beheerde waardenlijsten).

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

BRO-Verzoek

Dit hoofdstuk beschrijft de algemene opbouw van een BRO-verzoek. Een BRO-verzoek bestaat uit een brondocument verpakt in een 'request'. Paragraaf 2.1 beschrijft de verschillende requests van de SFR inname webservice. Paragraaf 2.2 beschrijft het verband tussen de deelonderzoeken, waaruit een bodemkundig wandonderzoek kan bestaan, en de wijze van aanleveren. Paragraaf 2.3 beschrijft de verschillende brondocumenten die in een request opgenomen kunnen worden. 

Requests

Om gegevens te registreren in de Landelijke Voorziening BRO (LV BRO) moet u deze aanleveren bij het Bronhouderportaal in de vorm van een BRO-verzoek (zie  basisregistratieondergrond.nl).

Vervolgens is het BRO-verzoek het bestand in IMBRO/XML-formaat dat het BRO-brondocument bevat en als verzoek wordt aangeboden in het Bronhouderportaal.

De SFR innamewebservice ondersteunt twee BRO-verzoeken. Zie onderstaande tabel.

Paragraaf 2.1.1 beschrijft in detail de opbouw van een  registrationRequest . Paragraaf 2.1.2 beschrijft op dezelfde manier een  correctionRequest .

RegistrationRequest

Met een registrationRequest (innameverzoek) wordt een nieuw registratieobject toegevoegd aan de BRO .

Een registrationRequest (innameverzoek) bestaat uit enkele transactiegegevens en een brondocument. De definities van de transactiegegevens staan in onderstaande tabel:

correctionRequest

Met een correctionRequest (correctieverzoek) kan de dataleverancier een registratieobject in één keer corrigeren. Het is niet mogelijk de waarde van een individueel attribuut te corrigeren; correcties kunnen alleen uitgevoerd worden door één van de gedefinieerde brondocumenten aan te bieden.

Een correctionRequest (correctieverzoek) bestaat uit enkele transactiegegevens en vooral een brondocument. De definities van de transactiegegevens staan in onderstaande tabel :

Het attribuut  correctionReason (correctiereden) geeft aan waarom (een deel van) het registratieobject wordt vervangen/gecorrigeerd. Zie onderstaande tabel voor de lijst met toegestane waarden en hun betekenis:

Deelonderzoeken

SFR bestaat uit drie deelonderzoeken:

• Wandbeschrijving.

• Wandmonsteranalyse.

• Wandfotografie.

De resultaten van een bodemkundig wandonderzoek worden in delen of in hun geheel gerapporteerd. Wanneer de resultaten in delen worden gerapporteerd worden deze per deelonderzoek geregistreerd en dat betekent in transactietermen dat een SFR registratieobject aangevuld moet kunnen worden en dat het daarmee een materiële geschiedenis opbouwt. Voor objecten met geschiedenis is het registreren een proces met een zekere duur. Het proces heeft een begin en een eind en daartussen kan zich de noodzaak voordoen nieuwe gegevens over te dragen.

SFR wordt gefaseerd gerealiseerd en daarmee ontstaat een tijdelijke situatie waarin SFR nog niet volledig is gedefinieerd en slechts een deel van de gegevens aangeboden kan worden. De huidige brondocumenten (zie paragraaf 2.3) beschrijven een deel van SFR en dat is de wandbeschrijving. In de volgende fase worden de wandmonsteranalyse toegevoegd en ontstaan nieuwe brondocumenten die de huidige brondocumenten vervangen. Later worden wandmonsterfotografie toegevoegd (termijn nog onbekend). Pas dan is SFR volledig gedefinieerd. Raadpleeg voor meer informatie de planning op  www.basisregistratieondergrond.nl.

Brondocumenten

Een brondocument bevat de gegevens die geregistreerd worden in de LV BRO. Voor elk registratieobject staat in de bijbehorende catalogus waaraan die gegevens moeten voldoen.

Een brondocument is de eenheid waarin een verzameling gegevens worden geregistreerd, aangevuld of gecorrigeerd.  De gegevens in het brondocument zijn gedefinieerd in de catalogus. De catalogus definieert ook  gegevens die door het BRO-systeem worden gegenereerd of afgeleid; deze gegevens hoeven niet worden opgenomen in een brondocument.

Een brondocument wordt verpakt in een 'request'.  Vervolgens wordt het geheel als een bestand in IMBRO/XML-formaat in de vorm van een BRO-verzoek aangeboden in het Bronhouderportaal.

Het feit, dat de resultaten van een bodemkundig wandonderzoek per deelonderzoek geregistreerd moeten kunnen worden en dat het bodemkundig wandonderzoek gefaseerd gerealiseerd wordt, leidt ertoe dat momenteel de volgende twee brondocumenten zijn gedefinieerd:

Onderstaande tabel geeft per brondocument de belangrijkste onderdelen weer.

De betekenis van de tekens in de laatste 5 kolommen is als volgt:

• Een √ geeft aan dat het onderdeel  aanwezig moet zijn  in het brondocument.

• Een + geeft aan dat het onderdeel  aanwezig mag zijn in het brondocument.

• Een leeg veld geeft aan dat het onderdeel  niet aanwezig mag zijn in het brondocument.

SFR_CompleteReport_V1

Onderstaande tabel definieert dit brondocument, inclusief de inhoud als deelverzameling van de gegevensdefinitie in de catalogus en de regels aanvullend op de bedrijfsregels in de catalogus.

SFR_StartReport_V1

Onderstaande tabel definieert dit brondocument, inclusief de inhoud als deelverzameling van de gegevensdefinitie in de catalogus en de regels aanvullend op de bedrijfsregels in de catalogus.

Voorbeeldberichten

Dit hoofdstuk bevat enkele voorbeeldberichten met regel voor regel een toelichting.  De integrale voorbeeldberichten zijn te vinden op de GitHub website (github.com/BROprogramma/SFR/tree/gh-pages/Berichtencatalogus/innameservice).

Wandbeschrijving en rapage direct afronden

Dit voorbeeldbericht is van toepassing als alle gegevens van een bodemkundig wandonderzoek in één keer worden aangeleverd. Het uitgevoerde deelonderzoek is alleen een wandbeschrijving. Met dit BRO-verzoek worden de gegevens over het veldwerk en de wandbeschrijving gerapeerd en wordt aangegeven dat de registratie van het bodemkundig wandonderzoek meteen voltooid is.

Randvoorwaarden

In het voorbeeldbericht zijn de volgende keuzes gemaakt:

• Het bodemkundig wandonderzoek bestaat uit alleen het veldwerk en een wandbeschrijving. Er 

  zijn geen wandmonsteranalyses uitgevoerd of wandfoto's gemaakt,

• De dataleverancier is niet tevens bronhouder.

• De bronhouder heeft aangegeven dat alle uitvoerende partijen vermeld moeten worden.

• De wandbeschrijving is opgesteld conform de nieuwe standaard AlterraTD19A, versie 2020, en wordt in het kader van een publieke taak onder het kwaliteitsregime IMBRO aangeboden.

• Het graven van de wandkuil is uitgevoerd op 1 januari 2018. Op dezelfde dag is de wandbeschrijving opgesteld en heeft de uitvoerder van het wandonderzoek alle gegevens van het bodemkundig wandonderzoek aangeboden bij het Bronhouderportaal en daarmee de rapportage afgerond.

• De wandbeschrijving bestaat uit:Een wandprofiel, bestaande uit.Eén strooisellaag.Twee bodemlagen:De eerste bestaat uit drie laagcomponenten met horinzontcodes Ah, AB en Bt, inclusief grondsamenstelling, fractieverdeling en Munsell-kleur.De tweede is homogeen met oer als bijzonder materiaal.Eén verstoord interval.Een verdicht interval.Bodemclassificatie.

Toelichting

Dit voorbeeldbericht bestaat in hoofdlijnen uit de beschrijving van het veldwerk (objectIdAccountableParty .. litterLayerInvestigated, deliveredLocation, deliveredVerticalPosition, soilUncovering en siteCharacteristic), de wandbeschrijving (soilFaceDescription) en een rapportagedatum (researchReportDate).

De eerste regel 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 het registrationRequest  (innameverzoek) als root XML-element en de namespaces van de gebruikte XML-schemadefinities (XSD's).

Regel 13 t/m 16 bevatten de transactiegegevens van het BRO-verzoek, waaronder in regel 16 de waarde IMBRO voor het qualityRegime  (kwaliteitsregime).

Regel 17 bevat de opening tag van het   sourceDocument  (brondocument) .

Regel 18 geeft aan welk type brondocument wordt aangeboden . Het XML-attribuut gml:id bevat een waarde die uniek is binnen dit bericht.

Regel 19 is het eerste gegeven binnen dit brondocument, de objectIdAccountableParty (object-ID bronhouder).

Regel 23 t/m 32 bevatten de fieldworkDate (veldwerkdatum). In dit voorbeeldbericht is de waarde een volledige datum (jaar-maand-dag, oftewel brocom:date). Uitgecommentarieerd staan de alternatieven voor een onvolledige datum: jaar en maand, alleen een jaartal of 'onbekend'.

Regel 34 t/m 41 geven aan dat de researchOperator (uitvoerder van het wandonderzoek) wordt geïdentificeerd met een  chamberOfCommerceNumber  (KvK-nummer). Het moet dus gaan om een Nederlandse onderneming of maatschappelijke activiteit van een rechtspersoon. Deze regels bevatten ook een alternatief voorbeeld voor het geval de uitvoerder een equivalent daarvan is in een handelsregister van een andere lidstaat van de Europese Unie dan Nederland, waarbij de uitvoerder dan geïdentificeerd wordt door zijn  europeanCompanyRegistrationNumber  (Europees handelsnummer).

Daarna volgen 2 blokken met XML-elementen van AttributeGroups (gegevensgroepen). Na de opening tag volgt meteen de reeks van XML-elementen van de AttributeGroup (gegevensgroep). Zie de catalogus voor nadere details;

• Regel 43 t/m 63: deliveredLocation (Aangeleverde locatie), oftewel de plaats van het wandonderzoek op het aardoppervlak.

• Regel 64 t/m 88: deliveredVerticalPosition (Aangeleverde verticale positie).

De deliveredLocation (Aangeleverde locatie) kan aangeleverd worden in het Rijks Driehoekstelsel (EPSG 28992; eerst de X-coördinaat daarna de Y-coördinaat, gescheiden door een spatie en met een punt tussen de meters en de decimalen daarvan) of in het European Terrestrial Reference System 1989 (EPSG 4258; eerst de latitude daarna de longitude, gescheiden door een spatie en met een punt tussen de graden en de decimalen daarvan).

Daarna volgen 3 blokken met gegevens van FeatureTypes (Objecttypes). De XML-codering van een FeatureType (Objecttype) volgt het 'property type' patroon: na de opening tag volgt een tweede tag met de naam van het type van het FeatureType (Objecttype) en een XML-attribuut gml:id. Daarna volgt de reeks van XML-elementen van het FeatureType (Objecttype), afgesloten met de closing tag van het type en de closing tag van het blok met XML-elementen. Zie de catalogus voor nadere details;

• Regel 89 t/m 99: soilUncovering (wandontsluiting).

• Regel 100 t/m 120: siteCharacteristic (terreintoestand).

• Regel 121 t/m 622: soilFaceDescription (wandbeschrijving).

Regels 148 t/m 165 bevatten de algemene gegevens van een soilProfile (wandprofiel).

Vanaf regel 167 volgt de beschrijving van de litterLayers (strooisellagen). De strooisellagen zijn optioneel en dit voorbeeldbericht bevat één strooisellaag. Dit is ook een FeatureType (Objecttype) en de inhoud volgt dus ook het het 'property type' patroon.

Vanaf regel 180 volgen de beschrijvingen van de soilLayers (bodemlagen). Een soilProfile (wandprofiel) bevat minstens één soilLayer (bodemlaag). Dit voorbeeldbericht heeft twee bodemlagen. De bodemlaag is ook een FeatureType (Objecttype) en de inhoud volgt dus ook het het 'property type' patroon.

Regel 181 t/m 517 bevat de eerste soilLayer (bodemlaag). Deze bestaat uit drie layerComponents (laagcomponenten) met horizonCodes (horizontcodes) Ah, AB en Bt. De drie laagcomponenten hebben een soil (grond) als beschrijving van de grondsamenstelling, inclusief fractionDistribution (fractieverdeling) en munsellColour (Munsell-kleur).

Regel 518 t/m 563 bevat de tweede soilLayer (bodemlaag). Deze is homogeen met oer als bijzonder materiaal.

Als laatste volgen twee optionele onderdelen van het wandprofiel, de reeks van disturbedIntervals (verstoorde intervallen; regel 564 t/m 573) en het compactedInterval (verdicht interval; regel 574 t/m 582).

De wandbeschrijving wordt afgesloten met de soilClassification (bodemclassificatie; regel 583 t/m 620) met daarin, in dit voorbeeld, twee keer een specialFeatureBottom (bijzonderheid onderin). De twee soilClassifications (bodemclassificaties) zijn ook FeatureTypes (Objecttypes) en volgen dus het property-type patroon.

Als laatste volgt in regel 623 t/m 632 de researchReportDate (rapportagedatum). De aanwezigheid van dit element geeft aan dat met het verwerken van dit bericht de registratie van het bodemkundig wandonderzoek is voltooid. Voor de waarde van de rapportagedatum is een volledige datum gebruikt (jaar-maand-dag, oftewel brocom:date). Uitgecommentarieerd staan de alternatieven voor een onvolledige datum: jaar en maand, alleen een jaartal of 'onbekend'.

Wandbeschrijving maar rapportage nog niet afronden

Dit voorbeeldbericht is van toepassing als een bodemkundig wandonderzoek bestaat uit 2 of meer deelonderzoeken, waarbij met dit BRO-verzoek de gegevens over het veldwerk en de wandbeschrijving worden gerapporteerd. Op een later tijdstip zullen de andere deelonderzoeken gerapporteerd worden.

Randvoorwaarden

In het voorbeeldbericht zijn de volgende keuzes gemaakt:

• Het bodemkundig wandonderzoek bestaat uit ten minste twee deelonderzoeken:

  • Met dit BRO-verzoek zullen de gegevens over de wandkuil en het overige veldwerk alsmede de wandbeschrijving worden aangeboden.

  • Op een later tijdstip, als versie V2 van de brondocumenten beschikbaar is, zal het wandonderzoek worden aangevuld en gelijktijdig of later worden afgerond.

• De dataleverancier is niet tevens bronhouder.

• De bronhouder heeft aangegeven dat alle uitvoerende partijen vermeld moeten worden.

• De wandbeschrijving is opgesteld conform AlterraTD19A, versie 1995 en wordt in het kader van archiefoverdracht onder het kwaliteitsregime IMBRO/A aangeboden.

• Het werk is uitgevoerd en de rapportage opgesteld in het jaar 2018. Nadere duiding van de datum is niet bekend.

• De wandbeschrijving bestaat uit:Een wandprofiel, bestaande uit:Eén strooisellaag.Eén homogene bodemlaag met oer als bijzonder materiaal.Geen verstoord interval.Geen verdicht interval.Bodemclassificatie.

Toelichting

Dit voorbeeldbericht bestaat in hoofdlijnen uit één deelonderzoek (soilFaceDescription) en de beschrijving van het veldwerk (objectIdAccountableParty .. litterLayerInvestigated, deliveredLocation, deliveredVerticalPosition, soilUncovering en siteCharacteristic). In vergelijking met het voorbeeldbericht 'Wandbeschrijving en rapportage direct afronden' ontbreekt de researchReportDate (rapportagedatum).

Regel 18 geeft aan welk type brondocument wordt aangeboden: SFR_StartReport_V1. Het XML-attribuut gml:id bevat een waarde die uniek is binnen dit bericht.

Vanaf regel 186 volgen de beschrijvingen van de soilLayers (bodemlagen). Een soilProfile (wandprofiel) bevat minstens één soilLayer (bodemlaag). Dit voorbeeldbericht heeft één bodemlaag, bestaande uit één homogeneousMaterial (homogeen materiaal) met oer als specialMaterial (bijzonder materiaal). Het datatype van de soilProfile (wandprofiel) is een FeatureType (ObjectType). De XML-codering van een FeatureType (Objecttype) volgt het 'property type' patroon: na de opening tag volgt een tweede tag met de naam van het type van het FeatureType (Objecttype) en een XML-attribuut gml:id. Daarna volgt de reeks van XML-elementen van het FeatureType (Objecttype), afgesloten met de closing tag van het type en de closing tag van de soilProfile (wandprofiel).

De laatste twee onderdelen van het wandprofiel, de disturbedInterval (verstoorde intervallen) en het compactedInterval (verdichte interval), zijn optioneel en komen in dit voorbeeldbericht niet voor.

De wandbeschrijving wordt afgesloten met de soilClassification (bodemclassificatie; regel 243 t/m 280) met daarin in dit voorbeeld twee keer een specialFeatureBottom (bijzonderheid onderin). De twee soilClassifications (bodemclassificaties) zijn ook FeatureTypes (Objecttypes) en volgen dus het 'property type' patroon.

Regel 283 bevat de closing tag SFR_StartReport_V1 als type van het sourceDocument (brondocument). Merk op dat de researchReportDate (rapportagedatum) ontbreekt. Daarmee wordt aangegeven dat met dit bericht de registratie van het bodemkundig wandonderzoek nog niet is voltooid en dat er nog aanvullingen zullen volgen, met bijvoorbeeld wandmonsteranalyses of wandfotografie. Deze aanvullingen zijn nog niet mogelijk in de huidige versie van de SFR innamewebservice.

Regel 284 bevat de closing tag van het sourceDocument (brondocument).

Regel 285 bevat de closing tag van het registrationRequest (innameverzoek).

Correctieverzoek

Met dit voorbeeldbericht kan het registratieobject, zoals geregistreerd met het voobeeldbericht 'Wandbeschrijving maar rapportage nog niet afronden', gecorrigeerd worden. De inhoud is bijna gelijk; de verschillen zijn:

• Regel 2: de opening tag van het XML-root element is nu correctionRequest (correctieVerzoek).

• Regel 16: de broId (BRO-ID) van het te corrigeren registratieobject is toegevoegd.

• Regel 18: de correctionReason (correctiereden) is toegevoegd.

• Regel 116: binnen siteCharacteristic (terreintoestand) is het attribuut meanHighestGroundwaterTable (gemiddeld hoogste grondwaterspiegel) toegevoegd met de waarde 1,85 meter.

• Regel 118: binnen siteCharacteristic (terreintoestand) is het attribuut meanLowestGroundwaterTable (gemiddeld laagste grondwaterspiegel) toegevoegd met de waarde 2,15 meter.

• Regel 162: binnen soilProfile (wandprofiel) is de waarde van het attribuut meanHighestGroundwaterLevelReached (gemiddeld hoogste grondwaterstand bereikt) gewijzigd van 'onbekend' in 'nee'.

• Regel 287: de closing tag van het XML-root element is nu correctionRequest (correctieVerzoek).

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 catalogus 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 catalogus, 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 het maken van een BRO-verzoek over een bodemkundig wandonderzoek. 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 catalogus. De derde kolom bevat de toegestane waarden, die gebruikt mogen worden in een BRO-verzoek.

Codelijsten

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

In de BRO wordt een onderscheid gemaakt tussen beheerde waardenlijsten en niet-beheerde waardenlijsten. In de catalogus en de XSD-bestanden noemen we een beheerde waardenlijst een codelijst. 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 catalogus bevat per codelijst de toegestane waarden, zoals gedefinieerd op het moment dat de catalogus werd vastgesteld.

De onderstaande tabel geeft een overzicht van de codelijsten die van belang zijn bij het maken van een BRO-verzoek over een bodemkundig wandonderzoek. 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 catalogus. De derde kolom bevat de URN, die  in  een BRO-verzoek gebruikt moet worden als waarde voor het XML-attribuut  codeSpace. De vierde kolom bevat een link naar de website waar de actuele lijst is te raadplegen met toegestane waarden die in een BRO-verzoek gebruikt mogen worden als waarde voor een XML-element.

Vertaaltabel

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

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.