Berichtencatalogus uitgiftewebservice SFR

Inleiding

Dit document beschrijft hoe een afnemer van de Basisregistratie Ondergrond (BRO) de gegevens over een wandonderzoek (SFR) kan opvragen.

Het document veronderstelt dat de lezer bekend is met de SFR 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 SFR 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

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

Dit hoofdstuk beschrijft de algemene werking van de SFR uitgiftewebservice.

Paragraaf 2.1 beschrijft de operaties die de SFR 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 SFR uitgiftewebservice wordt gerealiseerd als een SOAP-webservice. De SFR uitgiftewebservice ondersteunt twee soap operaties: dispatchCharacteristics (uitgifte van kengegevens) en dispatchData (uitgifte van objectgegevens).

Een soap operatie heeft een request en een response:

• Het  DispatchCharacteristicsRequest  (verzoek tot uitgifte van kengegevens) en de DispatchCharacteristics Response  (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 SFR 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 SFR uitgiftewebservice.

DispatchCharacteristicsRequest

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

De criteria worden gedefinieerd door SFR_CriteriaSet, een specialisatie van CriteriaSet uit package brommon, waaraan het een aantal optionele attributen toevoegt .

De definities van de  transactiegegevens  staan in onderstaande tabel:

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

De definities van de attributen die  SFR_CriteriaSet 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 dssfr-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 SFR 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 DispatchCharacteristics Response   (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 gegevens:

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

SFR_C

Het  uitgiftedocument van het type  SFR_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 gegevens:

• 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)
• surveyPurpose (kader inwinning)
• discipline (vakgebied)
• researchReportDate (rapportagedatum onderzoek)
• fieldworkDate (veldwerkdatum)
• litterLayerInvestigated (strooisellaag onderzocht)
• fractionDistributionDetermined (fracteverdeling bepaald)
• localVerticalReferencePoint (lokaal verticaal referentiepunt)
• offset (verschuiving)
• verticalDatum (verticaal referentievlak)
• outcropType (type ontsluiting)
• endDepthSoilFace (einddiepte wand)
• stopCriterion (stopcriterium)
• descriptionReportDate (rapportagedatum beschrijving)
• descriptionProcedure (beschrijfprocedure)
• descriptionQuality (beschrijfkwaliteit)
• sequenceDisturbed (opbouw verstoord)
• analysisReportDate (rapportagedatum analyse)
• analysisType (soort analyse)
• characteristicsModelled (karakteristiek gemodelleerd)

Objectgegevens

De SFR 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:

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) SFR_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 het FeatureType (Objecttype)) uniek identificeren.

Alle gegevens zijn volledig gedefinieerd in de SFR catalogus.

BRO_DO

Het uitgiftedocument van het type  BRO_DO  is een specialisatie van AbstractRegistrationObject in de package brocommon. Dit uitgiftedocument bestaat uit de gegevens:

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

SFR_O_DP

Het  uitgiftedocument van het type  SFR_O_DP is een specialisatie van SFR_O. Dit uitgiftedocument bevat alle gegevens uit de SFR catalogus.

SFR_O

Het uitgiftedocument van het type  SFR_O  is een specialisatie van RegistrationObject, wat op zijn beurt een specialisatie is van AbstractRegistrationObject in de package brocommon.  Dit uitgiftedocument bevat  dezelfde gegevens als uitgiftedocument SFR_O_DP, met uitzondering van de volgende gegevens (die ontbreken in SFR_O):

• objectIdAccountableParty  (object-ID bronhouder) in RegistrationObject (Wandonderzoek)
• deliveryResponsibleParty  (dataleverancier) in RegistrationObject (Wandonderzoek)
• researchOperator (uitvoerder onderzoek) in SFR_O (Wandonderzoek)
• horizontalPositioningOperator (uitvoerder locatiebepaling) in DeliveredLocation (Aangeleverde locatie)
• verticalPositioningOperator (uitvoerder verticale positiebepaling) in DeliveredVerticalPosition (Aangeleverde verticale positie)
• descriptionOperator (uitvoerder beschrijving) in SoilFaceDescription (Wandbeschrijving)
• analysisOperator (uitvoerder analyse) in SoilFaceSampleAnalysis (Wandmonsteranalyse)

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/SFR/blob/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.

De kop van een registrationRequest

De eerste regel van een BRO-bericht bevat de XML-proloog. Merk op dat de tekens volgens UTF-8 zijn gecodeerd. Eén teken kan daardoor uit meerdere bytes bestaan. Dit is met name van belang voor speciale tekens, zoals à, á, ï.

Regel 2 t/m 12 bevatten de opening tag van het dispatchDataResponse (bericht van verzending van objectgegevens) 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-bericht te valideren tegen de XSD-bestanden van de SFR uitgiftewebservice. Deze twee attributen mogen weggelaten worden. In het voorbeeldbericht heeft de URL van de schemalocation van de dssfr namespace de waarde ../../XSD/dssfr-messages.xsd. Dit is een relatief pad naar een lokaal bestand, met een mappenstructuur alsof de GitHub SFR repo is gecloned naar een lokale repo. Deze waarde is met name bedoeld in de projectfase voordat de SFR uitgiftewebservice 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 volgen drie transactiegegevens: responseType (type antwoord), requestReference  (verzoekkenmerk) en dispatchTime (tijdstip van uitgifte ). Andere typen antwoorden kunnen andere transactiegegevens bevatten. Zie hoofdstuk 2 voor nadere informatie.

Na de transactiegegevens volgt de opening tag van het  dispatchDocument  (uitgiftedocument). Daarbinnen volgen de gegevens van het opgevraagde registratieobject. 

Het antwoord wordt afgesloten met de closing tags van het dispatchDocument (uitgiftedocument) en het dispatchDataResponse (bericht van verzending van objectgegevens ).

<dispatchDataResponse
    xmlns="http://www.broservices.nl/xsd/dssfr/2.0"
    xmlns:sfrcom="http://www.broservices.nl/xsd/sfrcommon/2.0"
    xmlns:srcom="http://www.broservices.nl/xsd/srcommon/1.0"
    xmlns:brocom="http://www.broservices.nl/xsd/brocommon/3.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/dssfr/2.0 ../../XSD/dssfr-messages.xsd"
  >
  <!-- Disclaimer: dit voorbeeldbericht valideert tegen de XSD van de uitgifteservice.
       Het is niet gevalideert door de uitgifteservice en is vaktechnisch/inhoudelijk niet voorbeeldig.
    xsi:schemaLocation="http://www.broservices.nl/xsd/dssfr/2.0 https://schema.broservices.nl/xsd/dssfr/2.0/dssfr-messages.xsd"
  -->
  <brocom:responseType>dispatch</brocom:responseType>
  <brocom:requestReference>uitgifte-38</brocom:requestReference>
  <brocom:dispatchTime>2019-04-16T09:01:52+01:00</brocom:dispatchTime>
  <dispatchDocument>
    ...
  </dispatchDocument>
</dispatchDataResponse>

Uitgiftedocument

Een bericht van verzending van objectgegevens kan een uitgiftedocument bevatten (zie paragraaf 2.2). Zoals beschreven in paragraaf 2.3 kent de SFR uitgiftewebservice 4 types uitgiftedocumenten. De UML-diagrammen geven aan dat alle uitgiftedocumenten direct of indirect een specialisatie zijn van AbstractRegistrationObject en daarmee een FeatureType zijn. 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   dispatchDocument  van het uitgiftedocument volgt een regel met  SFR_O_DP . Deze regel geeft aan dat in dit bericht dit element optreedt als uitgiftedocument. Het element  SFR_O_DP   is als root element gedefinieerd in het XSD-bestand   dssfr-messages.xsd   van de SFR uitgiftewebservice. Na deze regel komt het eerste XML-element van het type  SFR_O_DPType , namelijk broID.

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

gml:id

De SFR gegevensdefinitie maakt een onderscheid tussen objecttypes en gegevensgroeptypes. Bij de opstellen van de berichtdefinities worden deze stereotypes vertaald naar  FeatureType  en  AttributeGroupType. Beide kunnen in software omgezet worden naar classes. De verschillen zijn onder meer 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. Beide hebben gegevens (attributes) en/of gegevensgroepen (attributeGroups).

Conform de GML XML encoding rules leidt ieder FeatureType in de XSD-bestanden tot:

• Een ComplexType, 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 propertyType ComplexType, zodat in een XML-document:
  • Een gegeven met dit  FeatureType  als type ofwel de inhoud van het FeatureType  kan bevatten (in-line) ofwel een verwijzing naar een feature (object) van dit type (by-reference).
  • Het type van het element kan worden vervangen door een specialisatie van het FeatureType, waarvan het bijbehorende root-element in het XSD-bestand een  substitutionGroup  heeft die direct of indirect herleidt naar het root element van dit FeatureType (polymorfisme).

Een AttributeGroupType  leidt tot alleen een ComplexType , wat de inhoud van het AttributeGroupType  definieert .

Omdat een FeatureType direct of indirect een specialisatie is van gml:AbstractFeatureType krijgt 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.

...
<SFR_StartRegistration gml:id="id_0001">
...
<sfrcom:GroundwaterMonitoringNet gml:id="id_0002">
...
<sfrcom:GroundwaterMonitoringTube gml:id="id_0004">
...
<gml:TimePeriod gml:id="id_0005">
...

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:sfr: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 bouwwerk  een waarde uit een codelijst is:

<surveyPurpose codeSpace="urn:bro:sfr:SurveyPurpose">bouwwerk</surveyPurpose>

Datum en DatumTijd

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>2019-03-18</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>2019-04-16T09:01:52+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).

PartialDate

In de SFR 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) of voidReason (de vaste waarde 'onbekend').

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

Organisatie

De SFR 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)
• analysisOperator  (uitvoerder analyse)

Het gegevenstype  Organization  (Organisatie) biedt de keuze tussen een kamer van koophandel nummer of een Europees handelsnummer. Hieronder twee voorbeelden:

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

Locatie

De SFR gegevenscatalogus definieert voor de  DeliveredLocation  (Aangeleverde locatie) en StandardizedLocation  (Gestandaardiseerde 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="id_0002" srsName="urn:ogc:def:crs:EPSG::28992">
  <gml:pos>134750.000 477800.000</gml:pos>
</location>
...
<location gml:id="id_0002" srsName="urn:ogc:def:crs:EPSG::4258">
  <gml:pos>52.28782, 5.09042</gml:pos>
</location>
...

Meetwaarde

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

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

...
<sfrcom: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-verzoek.

Resultaten van bepalingen

De SFR 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:D ataArray. 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 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 SFR 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>4</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>
...

Het XML-attribuut collapseWhiteSpaces="true", geeft aan dat alle whitespace voor en na iedere tokenseparator en blockseparator moeten worden genegeerd. Onderstaande voorbeeld, met een betere human-readability, is dus ook mogelijk:

...
<srcom:shrinkage>
  <swe:DataArray id="id_0017">
    <swe:elementCount>
      <swe:Count>
        <swe:value>4</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>
...

Als blockseparator kan ook een " " (spatie) of "
" (regelovergang) worden opgegeven. Dan vervalt de ; tussen de dataRecords binnen de values.

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 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 gegevenscatalogus. 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 gegevenscatalogus 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 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-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 gegevenscatalogus.
• De derde kolom bevat de URI, die  in  een BRO-verzoek gebruikt moet worden bij het XML-attribuut  codeSpace of het XML-attribuut  href. Bij een XML-attribuut  codeSpace wordt de gekozen waarde uit de codelijst opgenomen als waarde van het XML-element. Bij een  XML-attribuut  href wordt de gekozen waarde uit de codelijst samen met de URI geplaatst in het XML-attribuut. Zie de voorbeeldberichten voor nadere informatie.
• 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.

Vertaallijst

Dit hoofdstuk bevat een vertaaltabel, aan de hand waarvan, gegeven de Engelstalige naam van een complexType of element of een attribuut in de XSD-bestanden, de Nederlandse naam  in de gegevenscatalogus  kan worden opgezocht.

De onderstaande tabel is gesorteerd op alfabetische volgorde van de Engelstalige naam van het complexType/element. Tussen haakjes staat het type modelelement van de entiteit. Binnen een entiteit zijn de attributen gesorteerd op Engelstalige naam.