GLD Berichtencatalogus uitgiftewebservice
Inleiding
Dit document beschrijft hoe een afnemer van de Basisregistratie Ondergrond (BRO) de gegevens over een grondwaterstandonderzoek (GLD) kan opvragen.
Het document veronderstelt dat de lezer bekend is met de GLD 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 GLD 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
Versie | Datum | Omschrijving |
---|---|---|
0.3 | 08-04-2020 | Eerste versie. |
0.4 | 01-05-2020 | Increment 3: conform catalogus 0.99 exclusief correcties. |
0.5 | 12-05-2020 | Review commentaar verwerkt. |
1.1 | 18-12-2020 | Releasedatum registratieobject en publicatie document |
1.1.1 | 23-12-2020 | Verwijzing naar (test-)voorbeeldberichten op BRO productomgeving |
1.1.2 | 16-02-2021 | URLs naar codelijsten aangepast |
1.1.3 | 29-03-2021 | Verwijzing naar pagina met generieke beschrijving van het gebruik van een codelijst. |
Open issues
Nr | Paragraaf | Omschrijving |
---|---|---|
1 | 2.4 | Resultaten discussie over correcties en geschiedenis verwerken. |
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 GLD uitgiftewebservice
Dit hoofdstuk beschrijft de algemene werking van de GLD uitgiftewebservice.
Paragraaf 2.1 bevat een inleiding tot de GLD uitgiftewebservice
Paragraaf 2.2 beschrijft de operaties die de GLD uitgiftewebservice ondersteunt.
Paragraaf 2.3 beschrijft de BRO-berichten die een rol spelen bij die operaties.
Paragraaf 2.4 beschrijft de verschillende uitgiftedocumenten die in een BRO-bericht uitgegeven kunnen worden.
Inleiding
Met de GLD uitgiftewebservice kunnen de gegevens van een bepaald object worden opgevraagd. Het kan daarbij gaan om de actuele toestand of om alle gegevens van het object inclusief zijn geschiedenis.
De uitgifte van GLD kengegevens is buiten scope, omdat de coördinaten een verplicht deel uitmaken van kengegevens, terwijl een GLD zelf geen geometrische gegevens bevat. De geometrie komt beschikbaar is als we cross-RO en/of binnen de scope van een domein in plaats van binnen de scope van een enkel registratieobjecttype gaan werken. Een besluit dienaangaande wordt later gemaakt op initiatief van de BRO keten. De scope van dit document gaat niet verder dan alleen GLD.
Een GLD kan jaren actief blijven en aangevuld worden. Wanneer de meetfrequentie hoog is, kan een GLD in de loop van de tijd zeer veel metingen bevatten. Een gebruiker is niet altijd geïnteresseerd in al die metingen en zal willen filteren op:
Alleen observaties uit een bepaalde periode.
Alleen observaties waarbij het attribuut mate beoordeling gelijk is aan 'volledigBeoodeeld'. Dit omdat er een hiërarchie van de juridische gebruiksplicht is namelijk: gebruik volledig beoordeelde gegevens en indien deze er (nog) niet zijn voorlopige gegevens.
Beide filters leiden niet tot een andere inhoud van het uitgiftedocument, dezelfde gegevens worden uitgegeven (alle entiteiten en attributen). Alleen wordt op een van de attributen eerst een filter toegepast.
Operaties
De GLD uitgiftewebservice wordt gerealiseerd als een SOAP-webservice.
De GLD uitgiftewebservice ondersteunt één soap operatie: dispatchData (uitgifte van objectgegevens).
Een soap operatie heeft een request en een response. Het DispatchDataRequest bevat het uitgifteverzoek tot het leveren van alle geregistreerde gegevens van een bepaald registratieobject. De response bevat het antwoord op het verzoek. Naast een antwoord kan de reactie op een uitgifteverzoek ook een foutmelding zijn. Er zijn dus drie mogelijke reacties:
DispatchDataResponse (Antwoord): een functioneel antwoord op een uitgifteverzoek.
SOAP:Fault (Systeemfout): als er tijdens de verwerking van het request een onverwachte fout optreedt in het BRO-systeem, dan leidt dit tot een SOAP:Fault.
ParseFault (Validatiefout): als de GLD uitgiftewebservice constateert dat een DispatchDataRequest 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 GLD uitgiftewebservice.
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.
De DispatchDataRequest (Verzoek tot uitgifte van gegevens) van de GLD uitgiftewebservice is een specialisatie van DispatchRequest in de package brocommon, waaraan het twee optionele attributen toevoegt.
Dit BRO-bericht bestaat uit vier transactiegegevens. De definities van de transactiegegevens staan in onderstaande tabel:
Naam in XML-bestand | Nederlandse naam | Type | Kardinaliteit | Definitie |
---|---|---|---|---|
requestReference | verzoekkenmerk | CharacterString | 1..1 | Een voor de afnemer unieke aanduiding van het uitgifteverzoek. |
broId | BRO-ID | RegistrationObjectCode | 1..1 | De unieke aanduiding van het registratieobject in de Basisregistratie Ondergrond. Toelichting: |
observationPeriod | periode van monitoring | DatePeriod | 0..1 | Het datuminterval waarbinnen de observatieperiode van een observatie geheel of gedeeltelijk ligt. Regels: Toelichting: |
filtered | gefilterd | IndicationYesNo | 0..1 | Aanduiding of de te leveren gegevens gefilterd moeten worden volgens de juridische gebruiksplicht of niet. Toelichting: |
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:
Naam in XML-bestand | Nederlandse naam | Type | Kardinaliteit | Definitie |
---|---|---|---|---|
faultcode | foutcode | CharacterString | 1..1 | Aanduiding waar de fout is opgetreden. Toelichting: |
faultstring | fouttekst | CharacterString | 1..1 | Summiere beschrijving van de fout. Toelichting: |
detail | details | Any | 0..1 | Aanvullende informatie over de opgetreden fout en de vermoedelijke oorzaak. Toelichting: |
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:
Naam in XML-bestand | Nederlandse naam | Type | Kardinaliteit | Definitie |
---|---|---|---|---|
faultcode | foutcode | CharacterString | 1..1 | Aanduiding waar de fout is opgetreden. Toelichting: |
faultstring | fouttekst | CharacterString | 1..1 | Summiere beschrijving van de fout. Toelichting: |
detail | details | ParseFault | 0..1 | Aanvullende informatie over de opgetreden fout en de vermoedelijke oorzaak. Regel: |
De ParseFault (Validatiefout) bestaat uit drie gegevens en een lijst met abortReasons. De definities van de gegevens van ParseFault (Validatiefout) staan in onderstaande tabel:
Naam in XML-bestand | Nederlandse naam | Type | Kardinaliteit | Definitie |
---|---|---|---|---|
requestReference | verzoekkenmerk | CharacterString | 0..1 | Een voor de dataleverancier unieke aanduiding van het uitgifteverzoek. Toelichting: |
transactionId | transactiecode | CharacterString | 0..1 | Een voor het BRO-systeem unieke aanduiding voor de verwerking van een innameverzoek of uitgifteverzoek. Toelichting: |
abortTime | moment van afbreken | DateTime | 1..1 | Tijdstip, toegekend door de webservice, waarop de verwerking van het uitgifteverzoek is afgebroken. |
abortReason | reden afbreken | AbortReason | 1..* | Lijst met redenen waarom de verwerking van het uitgifteverzoek is afgebroken. Toelichting: |
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:
Naam in XML-bestand | Nederlandse naam | Type | Kardinaliteit | Definitie |
---|---|---|---|---|
sequenceNumber | volgnummer | Integer | 1..1 | Een binnen deze lijst van abortReasons (redenen afbreken) uniek nummer. Toelichting: |
specification | foutmelding | CharacterString | 1..1 | Omschrijving van de validatie fout. |
DispatchDataResponse
Het BRO-bericht DispatchDataResponse (Antwoord) bevat het functionele antwoord op een uitgifteverzoek. De DispatchDataResponse (Antwoord) van de GLD uitgiftewebservice is een specialisatie van DispatchResponse in de package brocommon, waaraan het een dispatchDocument (uitgiftedocument) toevoegt. De DispatchResponse in brocommon definieert een aantal gegevens en een optionele lijst met criterionErrors (kenmerkfouten).
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.
Gegeven | Afwijzing | Verzending |
---|---|---|
responseType | √ | √ |
requestReference | √ | √ |
rejectionTime | √ | |
dispatchTime | √ | |
rejectionReason | √ | |
criterionError | ||
dispatchDocument | √ |
Onderstaande tabel bevat de definities van de gegevens van de DispatchResponse:
Naam in XML-bestand | Nederlandse naam | Type | Kardinaliteit | Definitie |
---|---|---|---|---|
responseType | type antwoord | ResponseType | 1..1 | Aanduiding van de betekenis van het antwoord. |
requestReference | verzoekkenmerk | CharacterString | 1..1 | Een voor de afnemer unieke aanduiding van het uitgifteverzoek. Toelichting: |
rejectionTime | tijdstip van afwijzing | DateTime | 0..1 | Tijdstip, toegekend door de webservice, waarop het uitgifteverzoek is afgewezen. Regels: |
dispatchTime | tijdstip van uitgifte | DateTime | 0..1 | Tijdstip, toegekend door de webservice, waarop de opgevraagde gegevens zijn verzonden. Regels: |
rejectionReason | reden afwijzing | CharacterString | 0..1 | De reden waarom het uitgifteverzoek is afgewezen. Regels: |
criterionError | kenmerkfout | CriterionError | 0..* | Lijst met foutmeldingen met betrekking tot een geconstateerde fout in de kenmerkenverzameling van een uitgifteverzoek, bestaande uit een volgnummer en een omschrijving. Regels: Toelichting: |
dispatchDocument | uitgiftedocument | AbstractRegistrationObject | 0..1 | Dit element bevat de gegevens van het opgevraagde registratieobject, die in het BRO-systeem geregistreerd zijn. Regels: |
Uitgiftedocumenten
Een uitgiftedocument bevat de gegevens van het opgevraagde registratieobject, die in het BRO-systeem geregistreerd zijn. De gegevens zijn volledig gedefinieerd in de GLD catalogus.
De GLD uitgiftewebservice kent drie types uitgiftedocumenten; zie onderstaande tabel. Welke type wordt uitgeleverd hangt af van de identiteit van de afnemer en van de registratiestatus van het registratieobject. Uitgiftedocument GLD_O_DP bevat alle gegevens uit de catalogus.
Uitgiftedocument | Wordt uitgeleverd als: | |
---|---|---|
Afnemer | Registratieobject | |
BRO_DO | Is niet de bronhouder en/of dataleverancier. | Uit registratie genomen. |
GLD_O | Is niet de bronhouder en/of dataleverancier. | Niet uit registratie genomen. |
GLD_O_DP | Is tevens de bronhouder en/of dataleverancier. | Ongeacht. |
Onderstaande figuur geeft de uitgiftedocumenten (blauwe achtergrond) weer inclusief de mogelijke inhoud:
Gegevens 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 opgenomen in het dispatchDocument (uitgiftedocument) GLD_O_DP.
Gegevens 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.
Gegevens met de tekst id tussen accolades achter hun naam zijn gegevens die een object (een voorkomen van het FeatureType (Objecttype)) uniek identificeren.
Onderstaande figuur geeft de structuur weer van de individuele items in de lijst met observations (groene achtergrond). Deze is volledig gebaseerd op de OpenGis standaarden WaterML (WML2), Observations & Measurements (OM), Geographic MetaData (GMD), Geographic COmmon (GCO) en de OGC standaard Geography Markup Language (GML).
Alle gegevens zijn gedefinieerd in de GLD 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).
GLD_O_DP
Het uitgiftedocument van het type GLD_O_DP is een specialisatie van GLD_O. Dit uitgiftedocument bevat alle gegevens uit de GLD catalogus.
GLD_O
Het uitgiftedocument van het type GLD_PO 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 GLD_O_DP, met uitzondering van de volgende gegevens (die ontbreken in GLD_O):
objectIdAccountableParty (object-ID bronhouder).
deliveryResponsibleParty (dataleverancier).
contact (uitvoerder), dat wil zeggen:
parameterPrincipalInvestigator (identificatie).
contactOrganisationName (organisatienaam).
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 zijn te vinden via deze link: GLD voorbeeldberichten uitgifte. De onderstaande tabel bevat een opsomming van beschikbare voorbeeldberichten, hun intentie en een summiere beschrijving van de inhoud.
Naam | Doel en inhoud |
---|---|
DO_Request.xml | Verzoek tot het leveren van alle geregistreerde gegevens van een bepaald registratieobject. |
SoapFault.xml | Systeemfout als reactie op een uitgifteverzoek met een syntactische fout. |
ParseFault.xml | Validatiefout als reactie op een uitgifteverzoek waarvan de inhoud niet voldoet aan de XML-schemadefinities. |
DO_Response_Rejection.xml | Bericht van afwijzing. |
DO_Response_BRO_DO.xml | Bericht van verzending van objectgegevens van een registratieobject dat uit registratie is genomen, terwijl de afnemer niet de bronhouder nog de dataleverancier is van het uitgegeven registratieobject. |
DO_ResponseGLD_DO.xml | Bericht van verzending van objectgegevens van een registratieobject dat niet uit registratie is genomen, terwijl de afnemer niet de bronhouder nog de dataleverancier is van het uitgegeven registratieobject. |
DO_ResponseGLD_DO_DP.xml | Bericht van verzending van objectgegevens van een registratieobject, terwijl de afnemer tevens de bronhouder en/of dataleverancier (Data Provider) is van het uitgegeven registratieobject. |
Code snippets.
Deze paragraaf bevat voor een aantal kleine, bijzondere stukken XML-code uit de voorbeeldberichten een gedetailleerde beschrijving.
De kop van een dispatchResponse
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 15 bevatten de opening tag van het dispatchResponse (antwoord) 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 uitgiftewebservice. Deze twee attributen mogen weggelaten worden.
Na de disclaimer volgen drie transactiegegevens: responseType (type antwoord), requestReference (verzoekkenmerk) en dispatchTime (tijdstip van uitgifte). Zie hoofdstuk 2 voor nadere informatie.
Na de transactiegegevens volgt de opening tag van het dispatchDocument (uitgiftedocument). Daarbinnen volgt het geleverde uitgiftedocument.
Het BRO-verzoek wordt afgesloten met de closing tags van het dispatchDocument (uitgiftedocument) en het dispatchResponse (antwoord).
<?xml version="1.0" encoding="UTF-8"?>
<dispatchDataResponse
xmlns="http://www.broservices.nl/xsd/dsgld/1.0"
xmlns:gldcom="http://www.broservices.nl/xsd/gldcommon/1.0"
xmlns:brocom="http://www.broservices.nl/xsd/brocommon/3.0"
xmlns:wml2="http://www.opengis.net/waterml/2.0"
xmlns:gmd="http://www.isotc211.org/2005/gmd"
xmlns:gco="http://www.isotc211.org/2005/gco"
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/dsgld/1.0 https://schema.broservices.nl/xsd/dsgld/1.0/dsgld-messages.xsd"
>
<!-- Disclaimer: dit voorbeeldbericht valideert tegen de XSD van de uitgifteservice.
Het is niet geleverd door de uitgifteservice en is vaktechnisch/inhoudelijk niet voorbeeldig.
-->
<brocom:responseType>dispatch</brocom:responseType>
<brocom:requestReference>103</brocom:requestReference>
<brocom:dispatchTime>2019-06-28T10:10:52+02:00</brocom:dispatchTime>
<dispatchDocument>
...
</dispatchDocument>
</dispatchDataResponse>
DispatchDocument
Zoals beschreven in paragraaf 2.4 kent de GLD uitgiftewebservice 3 types uitgiftedocumenten. De UML-diagrammen geven aan dat de uitgiftedocumenten het AbstractRegistrationObject (Abstract Registratieobject) als gemeenschappelijke generalisatie hebben. Conform de GML XML encoding rules wordt het property type pattern toegepast bij het omzetten van de UML diagrammen naar de berichtdefinities. Onderstaand stukje van een voorbeeldbericht laat zien hoe dat uitpakt in XML. Na de opening tag dispatchDocument van het brondocument volgt een regel met GLD_O. Deze regel geeft aan dat in dit bericht dit type uitgiftedocument is opgenomen. Het element GLD_O is als root element gedefinieerd in het XSD-bestand dsgld-messages.xsd van de GLD uitgiftewebservice. Na deze regel komt het eerste XML-element van het type GLD_OType, wat het XML-type is van het root XML-element GLD_O.
|
gml:id
De GLD 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. Daartoe hebben beide attributen (attributes) 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 een specialisatie is van gml:AbstractFeatureType.
Een root element, zodat objecten geïnstantieerd kunnen worden van het ComplexType.
Een propertyType ComplexType, zodat in een XML-document:
Een attribuut 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).
Als gevolg van de eerste bullet 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. Het BRO-systeem slaat de waarden van deze gml:id niet op.
Uitzondering zijn de gml:id's van de XML-elementen, die in de GLD gegevenscatalogus expliciet zijn voorzien van een 'ID' attribuut: observatie ID, observatieproces ID en tijdmeetwaardereeks ID. Deze hebben in de voorbeeldberichten een waarde die begint met een '_'. Het BRO-systeem slaat de waarden van deze gml:id's wel op. Gevolg is dat de waarden van deze gml:id's uniek moeten zijn binnen een GLD registratieobject en dat een BRO-verzoek mag verwijzen naar een gml:id die in een eerder BRO-verzoek is aangeleverd. In de voorbeeldberichten is aan deze eis voldaan door gebruik te maken van een GUID-generator. De laatste regel in onderstaande voorbeelden bevat een verwijzing naar een gml:id die niet voorkomt in hetzelfde BRO-verzoek.
|
DateStamp
Het attribuut dateStamp (datum metadata) heeft als type een gco:Date_Type. In de GLD gegevenscatalogus het dit attribuut als type een Datum onder kwaliteitsregime IMBRO en een OnvolledigeDatum onder IMBRO/A. Onderstaande voorbeelden geven mogelijke waarden met afnemende nauwkeurigheid.
|
Uitvoerder van een observatie.
Volgens de GLD gegevenscatalogus worden van de uitvoerder van een observatie twee attributen geregistreerd: organisatienaam en identificatie. Volgens een werkafspraak moet de naam leeg zijn.
De identificatie van een organisatie is een keuze tussen een KvK-nummer of een Europees handelsnummer. Stel dat de uitvoerder een Nederlandse onderneming is met 27376655 als KvK-nummer. Dan ziet de betreffende XML-code er als volgt uit:
|
Als het gaat om een buitenlandse onderneming met DEB8537.HRB66039 als Europees handelsnummer, dan ziet de betreffende XML-code er als volgt uit:
|
Observatietype
Volgens de GLD gegevenscatalogus heeft het attribuut observatietype het type Observatietype, een uitbreidbare waardelijst. Binnen het ComplexType ObservationMetadata van WaterML is hiervoor geen geschikt attribuut gedefinieerd. Daarom is het attribuut gemapt op een parameter van het type NamedValue. Het XML-element name bevat in dit geval een vaste waarde, die uniek het attribuut aanduidt. NB: let op de kleine letter o in het woord observationType. Het XML-element value heeft een waarde en 2 XML-attributen. De waarde komt uit de GLD gegevenscatalogus. De beide XML-attributen hebben een vaste waarde. NB: let op de hoofdletter O in het woord ObservationType.
|
Gerelateerd aan
In de GLD gegevenscatalogus heeft een Observatie een optionele lijst van gerelateerde observaties. Bij een observatie met een volledig beoordeelde tijdmeetwaardereeks kan, indien aanwezig, hier geregistreerd worden op welke observaties met een controlemeting en/of observaties met een voorlopige tijdmeetwaardereeks de beoordeling is gebaseerd.
Deze gerelateerde observaties zitten in hetzelfde brondocument of zijn geregistreerd met een eerder aangeboden brondocument. In beide gevallen hebben de gerelateerde observaties een gml:id als unieke identificatie. De relatie bestaat uit een xlink:href XML-attribuut met als waarde de waarde van de betreffende gerelateerde observatie. De rest van onderstaande code bestaat uit vaste tekst en vaste waarden.
|
PhenomenonTime
Het attribuut phenomenonTime (observatieperiode) bestaat uit een periode, aangegeven door een beginPosition (begindatum) en een endPosition (einddatum). Beide attributen hebben als type een gml:TimePositionType. Dit datatype ondersteunt een variabele nauwkeurigheid. Binnen de phenomenonTime (observatieperiode) gebruiken we alleen waarden die bestaan uit een volledige datum. De waarde voor beginPosition (begindatum) komt overeen met het datumdeel van de oudste waarde van het XML-element wml2:time in de MeasurementTimeseries (Tijdmeetwaardereeks) van het om:result. De waarde voor endPosition (einddatum) komt overeen met het datumdeel van de jongste waarde van het XML-element wml2:time in de MeasurementTimeseries (Tijdmeetwaardereeks) van het om:result.
|
ResultTime.
Volgens de GLD gegevenscatalogus heeft het attribuut resultTime (tijdstip resultaat) het type DatumTijd onder IMBRO en het type OnvolledigeDatum onder IMBRO/A. Daarmee bestaat de nauwkeurigheid van dit attribuut uit:
volledige datum en tijd
volledige datum
jaar en maand
jaartal
'onbekend'
Dit attribuut is gemapt op het XML-element om:resultTime uit Observations and Measurements, wat een gml:TimeInstantPropertyType als type heeft wat op zijn beurt een gml:TimePositionType is. Conform de GML specificaties moet een lokale tijd aangevuld worden met een tijdzone. Als alternatief kan een lokale tijd worden omgezet naar UTC (Universal Time Coordinated, voorheen Greenwich Mean Time) en daarna aangevuld met een hoofdletter Z (Zulu). Nederland heeft als tijdzone +1 uur tijdens wintertijd en +2 uur tijdens zomertijd. Onderstaande XML-code zijn voorbeelden voor bovenstaande nauwkeurigheden. De eerste twee voorbeelden geven dezelfde datum en tijd weer:
|
ProcessType
Het binnen WaterML verplichte attribuut processType (procestype) heeft binnen GLD een vaste waarde:
|
ProcessReference
De processReference (meetprocedure) heeft als type een codelijst. Conform de WaterML specificaties wordt dit niet gecodeerd als een gml:CodeWithAuthorityType, maar wordt de waarde opgenomen in een xlink:href XML-attribuut. De waarde van dit attribuut begint met de URN van de codelijst (urn:bro:gld:ProcessReference) gevolgd door een dubbele punt (:) en dan de gekozen waarde uit de codelijst. Zie onderstaande voorbeeld:
|
ObservationType
Voor het attribuut observationType (observatietype) definieert WaterML geen geschikt attribuut. Daarom is dit attribuut gemapt op een NamedValue parameter. Zie onderstaande voorbeeld. Het XML-element om:name geeft in het XML-attribuut xlink:href aan om welk attribuut het gaat. Het XML-element om:value bevat de waarde uit de codelijst, gecodeerd als een gml:CodeWithAuthorityType, waarbij het XML-attribuut codeSpace de URN van de codelijst bevat.
|
EvaluationProcedure
Voor het attribuut evaluationProcedure (beoordelingsprocedure) geldt hetzelfde als voor het attribuut observationType (observatietype).
AirPressureCompensationType
Voor het attribuut airPressureCompensationType (type luchtdrukcompensatie) geldt hetzelfde als voor het attribuut observationType (observatietype).
MeasurementInstrumentType
Voor het attribuut measurementInstrumentType (type meetinstrument) geldt hetzelfde als voor het attribuut observationType (observatietype).
StatusQualityControl
Voor het attribuut statusQualityControl (statusKwaliteitscontrole) definieert WaterML geen geschikt attribuut. Daarom is dit attribuut gemapt op een Category qualifier. Zie onderstaande voorbeeld. Het XML-element swe:codeSpace bevat de URN van de codelijst. Het XML-element swe:value bevat de waarde uit de codelijst.
|
CensoringLimitvalue
Voor het attribuut censoringLimitvalue (censuurlimietwaarde) definieert WaterML geen geschikt attribuut. Daarom is dit attribuut gemapt op een Q uantity qualifier. Zie onderstaande voorbeeld. Het XML-attribuut definition van het XMLelement swe:Quantity bevat de unieke identificatie van het attribuut, gecodeerd als een URN. Het XML-attribuut code van het XML-element swe:uom bevat de vaste waarde 'm' (meter) als eenheid voor de censuurlimietwaarde. Het XML-element swe:value bevat de waarde van de censuurlimietwaarde.
|
Onder IMBRO/A kan het zijn dat de limitewaarde niet bekend is. Volgens de GLD gegevenscatalogus mag dan de waarde ontbreken. In de sweQuantifier is het XML-element value niet nillable, maar wel optioneel. Daarom wordt de regel 'het attribuut heeft geen waarde' uit de GLD gegevenscatalogus in een XML-bericht als volgt omgezet (merk op dat het XML-element swe:uom wel aanwezig is):
|
InterpolationType
Het binnen WaterML verplichte attribuut interpolationType (Interpolatietype) heeft binnen GLD een vaste waarde:
|
CensoredReason
Het attribuut censoredReason (censuurreden) heeft als type een codelijst. Conform de WaterML specificaties wordt dit niet gecodeerd als een gml:CodeWithAuthorityType, maar wordt de waarde opgenomen in een XML-attribuut xlink:href. Zie onderstaande tabel voor de mapping van toegestane waarde in ge GLD gegevenscatalogus en de waarde voor het XML-attribuut xlink:href en het onderstaande XML voorbeeld:
Toegestane waarde | Waarde voor xlink:href |
---|---|
groterDanLimietwaarde | |
kleinerDanLimietwaarde | |
onbekend |
|
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 grondwaterstandonderzoek. 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.
Type | Naam | Waarde | Omschrijving |
---|---|---|---|
IndicationYesNo | IndicatieJaNee | ja | |
nee | |||
IndicationYesNoUnknown | IndicatieJaNeeOnbekend | ja | |
nee | |||
onbekend | Het is niet bekend of het gegeven een waarde ja of nee heeft. | ||
QualityRegime | Kwaliteitsregime | IMBRO | Kwaliteitsregime waarbij de innamewebservice tijdens het verwerken van een innameverzoek de normale (strikte) regels hanteert, zoals gedefinieerd in de gegevenscatalogus. |
IMBRO/A | Kwaliteitsregime waarbij de innamewebservice tijdens het verwerken van een innameverzoek andere (minder strenge) bedrijfsregels, toegestane waarden van codelijsten en/of domeinen van gegevens toepast dan onder het (normale) IMBRO kwaliteitsregime. |
Codelijsten
Binnen GLD volgen de meeste codelijsten het patroon zoals algemeen toegepast binnen de BRO en beschreven in Codelist (Codelijst). Dat zijn de codeljisten in de onderstaande tabel.
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. Zie Codelist (Codelijst). en de voorbeeldberichten voor nadere informatie.
De vierde kolom bevat een link naar de website waar de actuele lijst met de toegestane waarden is te raadplegen, die in een BRO-verzoek gebruikt mogen worden als waarde voor een XML-element.
Type | Naam | URI | Link |
---|---|---|---|
AirPressureCompensationType | TypeLuchtdrukcompensatie | urn:bro:gld:AirPressureCompensationType | https://publiek.broservices.nl/refcodes/api/get_codes?domain=urn:bro:gld:AirPressureCompensationType |
EvaluationProcedure | Beoordelingsprocedure | urn:bro:gld:EvaluationProcedure | https://publiek.broservices.nl/refcodes/api/get_codes?domain=urn:bro:gld:EvaluationProcedure |
MeasurementInstrumentType | TypeMeetinstrument | urn:bro:gld:MeasurementInstrumentType | https://publiek.broservices.nl/refcodes/api/get_codes?domain=urn:bro:gld:MeasurementInstrumentType |
StatusCode | MateBeoordeling | urn:bro:gld:StatusCode | https://publiek.broservices.nl/refcodes/api/get_codes?domain=urn:bro:gld:StatusCode |
De GLD catalogus definieert voor de codelijsten Censuurreden, Interpolatietype en Procestype Nederlandse toegestane waarden. De betreffende codelijsten in WaterML definiëren Engelse toegestane waarden. De onderstaande tabel geeft een vertaling van de Engelstalige toegestane waarde in de XSD-bestanden naar de Nederlandse toegestane waarde in de gegevenscatalogus.
Toegestane waarde in XML-verzoek | Toegestane waarde volgens gegevenscatalogus |
---|---|
CensoredReason | Censuurreden |
http://www.opengis.net/def/nil/OGC/0/AboveDetectionRange | groterDanLimietwaarde |
http://www.opengis.net/def/nil/OGC/0/BelowDetectionRange | kleinerDanLimietwaarde |
onbekend | |
InterpolationType | Interpolatietype |
http://www.opengis.net/def/waterml/2.0/interpolationType/Discontinuous | discontinu |
ProcessType | Procestype |
http://www.opengis.net/def/waterml/2.0/processType/Algorithm | algoritme |
Binnen GLD worden 6 codelijsten uit de internationale standaard voor WaterML gebruikt, die niet het bovenstaande patroon volgen. Deze staan in de onderstaande tabel. De derde kolom verwijst naar de paragraaf in dit document met nadere informatie.
Type | Naam | Paragraaf | Link |
---|---|---|---|
CensoredReason | Censuurreden | 3.2.19 CensoredReason | |
InterpolationType | Interpolatietype | 3.2.18 InterpolationType | |
ObservationType | Observatietype | 3.2.12 ObservationType | https://publiek.broservices.nl/refcodes/api/get_codes?domain=urn:bro:gld:ObservationType |
ProcessReference | Meetprocedure | 3.2.11 ProcessReference | https://publiek.broservices.nl/refcodes/api/get_codes?domain=urn:bro:gld:ProcessReference |
ProcessType | Procestype | 3.2.10 ProcessType | |
StatusQualityControl | StatusKwaliteitscontrole | 3.2.15 StatusQualityControl | https://publiek.broservices.nl/refcodes/api/get_codes?domain=urn:bro:gld:StatusQualityControl |
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.
Complextype (stereotype) | Naam entiteit |
---|---|
AbstractRegistrationObject (FeatureType) | Abstract Registratieobject |
broId | BRO-ID |
ChamberOfCommerceNumber (PrimitiveDatatype) | KvK-nummer |
Date (PrimitiveDatatype) | Datum |
DispatchDataRequest (FeatureType) | Verzoek tot uitgifte van objectgegevens |
DispatchDataResponse (FeatureType) | Bericht van verzending gegevens |
dispatchDocument | uitgiftedocument |
GLD_O (FeatureType) | Grondwaterstandonderzoek |
registrationHistory | registratiegeschiedenis |
researchFirstDate | datum eerste meting |
researchLastDate | datum recentste meting |
GLD_O_DP (FeatureType) | Grondwaterstandonderzoek |
GroundwaterMonitoringNet (FeatureType) | Grondwatermonitoringnet |
broId | BRO-ID |
GroundwaterMonitoringTube (FeatureType) | GMW-monitoringbuis |
broId | BRO-ID |
tubeNumber | buisnummer |
MeasurementTimeseries (FeatureType) | Tijdmeetwaardereeks |
gmlAtrributeId | tijdmeetwaardereeks ID |
point | tijdmeetwaardepaar |
MeasurementTimeseriesTVPObservation (FeatureType) | Observatie |
gmlAtrributeId | observatie ID |
metaData | metadata observatie |
phenomenonTime | observatieperiode |
resultTime | tijdstip resultaat |
MeasurementTVP (AttributeGroupType) | Tijdmeetwaardepaar |
metadata | metadata tijdmeetwaardepaar |
time | tijdstip meting |
value | waterstand |
Number4 (PrimitiveDatatype) | Aantal4 |
ObservationMetadata (AttributeGroupType) | Metadata observatie |
contact | uitvoerder |
dateStamp | datum metadata |
parameterObservationType | observatietype |
status | mate beoordeling |
ObservationProcess (FeatureType) | Observatieproces |
gmlAtrributeId | observatieproces ID |
parameterAirPressureCompensationType | type luchtdrukcompensatie |
parameterEvaluationProcedure | beoordelingsprocedure |
parameterMeasurementInstrumentType | type meetinstrument |
processReference | meetprocedure |
processType | procestype |
Organization (Union) | Organisatie |
chamberOfCommerceNumber | KvK-nummer |
europeanCompanyRegistrationNumber | Europees handelsnummer |
PartialDate (Union) | OnvolledigeDatum |
jaar en maand | yearMonth |
jaartal | year |
onbekend | voidReason |
volledige datum | date |
RegistrationHistory (AttributeGroupType) | Registratiegeschiedenis |
corrected | gecorrigeerd |
deregistered | uit registratie genomen |
deregistrationTime | tijdstip uit registratie genomen |
latestAdditionTime | tijdstip laatste aanvulling |
latestCorrectionTime | tijdstip laatste correctie |
objectRegistrationTime | tijdstip registratie object |
registrationCompletionTime | tijdstip voltooiing registratie |
registrationStatus | registratiestatus |
reregistered | weer in registratie genomen |
reregistrationTime | tijdstip weer in registratie genomen |
underReview | in onderzoek |
underReviewTime | in onderzoek sinds |
RegistrationObject (FeatureType) | Registratieobject |
deliveryAccountableParty | bronhouder |
deliveryResponsibleParty | dataleverancier |
objectIdAccountableParty | object-ID bronhouder |
qualityRegime | kwaliteitsregime |
RegistrationObjectCode (PrimitiveDatatype) | Registratieobjectcode |
ResponsibleParty (AttributeGroupType) | Organisatiegegevens |
contactOrganisationName | organisatienaam |
parameterPrincipalInvestigator | identificatie |
Text40 (PrimitiveDatatype) | Tekst40 |
Text7 (PrimitiveDatatype) | Tekst7 |
TVPMeasurementMetadata (AttributeGroupType) | Metadata tijdmeetwaardepaar |
censoredReason | censuurreden |
interpolationType | interpolatietype |
qualifierCategory | status kwaliteitscontrole |
qualifierQuantity | censuurlimietwaarde |