Het Basisregistratie Grootschalige Topografie (BGT XML)-mutatieformaat dat door PDOK wordt geleverd, heeft als doel externe partijen te laten “meemuteren” met de actuele stand van de Basisregistratie Grootschalige Topografie voor alle features. Het formaat is een implementatie van het generieke formaat beschreven op https://github.com/PDOK/schemas-mutatielevering wat ook voor andere datamodellen gebruikt kan worden. Dit document is een algemene toelichting bij de mutatie XSD’s te vinden op https://zakelijk.kadaster.nl/schemas. Actuele informatie over het gebruik van de interface is te vinden via de OpenAPI interface, waarvan de URL wordt gepubliceerd bij livegang, van het actieve endpoint. Vragen over deze interface kunnen gesteld worden op https://geoforum.nl/.
Alle features kunnen in de loop van de tijd wijzigen in de basisregistratie. De periode tussen twee wijzigingen noemen we hier een versie. Van elke feature houdt de basisregistratie wijzigingshistorie bij. De wijzigingshistorie bestaat uit op elkaar aansluitende versies met elk een begin-en een eindtijdstip. Het productmodel BGT geeft aan hoe deze geldigheid van features is gemodelleerd. Het mutatie formaat kent een generiek mechanisme dat los staat van het mutatie model in het BGT productmodel. Het mutatie formaat modelleert de wijzingen in features op basis van de leveringen met updates uit de Basisregistratie die aan PDOK zijn aangeleverd. Hierdoor kan een afnemer exact de zelfde wijzingen in zijn dataset doorvoeren als PDOK. Door dit “meemuteren” kan een afnemer zijn eigen dataset actueel houden voor zijn interessegebied. Het mutatieformaat bestaat hiërarchisch uit de volgende elementen: Mutatiebericht met metadata over de geleverde mutaties en de verzameling van alle BGT mutaties voor deze levering. Mutatiegroep voor de BGT is een mutatie die in volgorde verwerkt moet worden.
De mutatiegroep definieert de veranderde situatie. Een mutatie is een toevoeging, wijzing of verwijdering.
Mutaties uit de basisregistratie kunnen nadat ze zijn verwerkt in PDOK via de PDOK API worden afgenomen als mutatiebericht van een specifiek interessegebied. Er kunnen twee varianten afgenomen worden.
1. Initiële levering, dit is de meest actuele stand waarmee een afnemer zijn datasets kan opbouwen om te beginnen met “meemuteren”. Het bevat alle actuele features. 2. Delta levering. Dit is een set met alleen mutaties uit een aanlevering uit de landelijke registratie om de eigen dataset bij te werken.
De actualiteit van beide varianten wordt aangeduid met een unieke id (UUID). Dit unieke id is te vinden in de leveringen (“mutatieBericht/leveringId”).
De initiële levering is alleen voor de meest actuele dataset beschikbaar. De API heeft een endpoint (“Delta”) waarmee een overzicht te krijgen is waarin staat welke deltaleveringen beschikbaar zijn. De initiële levering van een dataset wordt aangeboden in het zelfde formaat als bij een wijziging waarbij alle objecten worden aangeboden. Wijzigingen (deltaleveringen) worden 31 dagen vastgehouden. Een afnemer kan dus op elke dag beginnen met een initiële levering en vervolgens een dataset bijwerken. Mutatieleveringen blijven 31 dagen beschikbaar. De initiële download is alleen voor de actuele datum beschikbaar. In uitzonderlijke situaties kan de landelijke voorziening beslissen om opnieuw alle data te leveren. In deze situatie worden alle delta mutaties verwijderd met mogelijk foutieve mutaties. In dit geval moeten alle afnemers ook opnieuw beginnen met het opbouwen vaneen nieuwe actuele dataset. Het XML formaat van beide varianten is identiek.
De mutaties zijn gemodelleerd met een “was-wordt” objectmodel. Een mutatie is een toevoeging, wijzing of verwijdering.
In een toevoeging wordt het nieuwe BGT feature geleverd. Dit “wordt” feature wordt geleverd, inclusief een “id” en “type” waarmee deze feature uniek te identificeren is. Deze unieke identificatie is nodig om latere mutaties op dit feature te kunnen doorvoeren, zonder velden uit het productmodel BGT te hoeven vergelijken. De ontwerpkeuze voor een “was-wordt” model met deze extra velden is beschreven op https://github.com/PDOK/schemas-mutatielevering.
In een wijziging wordt zowel het “was” feature als het “wordt” feature geleverd. Een afnemer kan het “was” feature identificeren met het “id” en “type” en vervangen door het nieuwe “wordt” feature met een nieuw “id”.
Bij een verwijdering van een BGT-feature wordt alleen het “was” feature aangeleverd, de afnemer kan dan dit feature verwijderen uit zijn registratie inclusief historie. Let op dit is een voorbereiding op herstel acties. De landelijke voorziening BGT levert nu nog geen herstel-leveringen. Het verdwijnen van een BGT-object is voor het mutatieformaat een was-wordt wijzing waarbij de eindtijd-registratie wordt gevuld.
Een interessegebied is de mogelijkheid om mutaties af te nemen van een door de afnemer specifiek gebied. Het interessegebied is gemodelleerd als polygoon. Deze polygoon zit zowel in het XML formaat als de API. Als het interessegebied niet aangegeven wordt dan wordt heel Nederland als interessegebied verondersteld. Er wordt geen speciaal kenmerk toegevoegd als enkel de “was”-of de “wordt”zich binnen het deelgebied bevindt. Afnemers herkennen deze situatie zelf en handelen deze op de juiste wijze af. Toelichting: Een “intredend feature” waarvan enkel de “wordt” in het interessegebied ligt, zal de afnemer als nieuw feature gaan bijhouden. Een “uittredend feature” waarvan enkel de “was”in het interessegebied ligt, zal de afnemer als feature niet meer willen bijhouden. Het gevolg is dat afnemers bij een “herintredend feature” de mutatiehistorie missen van de periode waarin het feature zich buiten hun interessegebied bevond. De API bevat een endpoint “Custom” waarmee het interessegebied als geofilter meegegeven wordt. De waarde van dit interessegebied (geofilter) wordt gespecificeerd in het Well-known text (WKT)formaat. Alleen Polygon en MultiPolygon objecten zijn hierbij toegestaan waarbij innerrings niet worden ondersteund. De coördinaten worden geïnterpreteerd volgens EPSG:28992. Dit geofilter limiteert het interessegebied waarvoor objecten in de download worden opgenomen. Een download kan geografisch het geofilter overschrijden. De download bevat minimaal de objecten die binnen het interessegebied vallen. De eenheden van levering zijn vierkanten waardoor in de levering meer objecten zitten in het interessegebied.
De leveringen worden in een zip bestand opgehaald vanuit PDOK. In de zip file zitten xml files met de geselecteerde features voor het interessegebied. Per levering van een aantal duizend mutaties (“wordt”, “was-wordt”of “was”) ontstaat een XML-bestand. Als een feature meermaals binnen één bestand gemuteerd wordt, dan staan deze mutaties in de juiste volgorde in het bestand. Met andere woorden: als het bestand van boven naar beneden verwerkt wordt, kan “id” en “type” nooit zo zijn dat een “was” verwijst naar een toestand die pas verderop in het bestand ontstaat d.m.v. een “wordt”. Sorteren in de verwerkende applicatie is dus niet nodig. Het totaal van XML-bestanden van de opgevraagde mutatie wordt gezipt, waarbij zowel de alfabetische volgorde van de bestandsnamen als de fysieke volgorde van de bestanden in de zip overeenkomt met de volgorde waarin de bestanden verwerkt moeten worden. Dit maakt het mogelijk de zip op “streaming” wijze te verwerken, oftewel met de verwerking te starten terwijl de zip nog gedownload en gedecomprimeerd wordt.
In een XML file staat het "gebied" en de "objectTypen". Deze gelden voor de totale levering en niet voor de specifieke file. Normaal gesproken zijn de feature types of "objectTypen" verdeeld per XML file, maar dat is geen gegeven. Per mutatie groep moet gekeken worden om welk object type het gaat.
Voor het verwerken van de levering is een referentie implementatie opgezet. Deze implementatie kan gevonden worden op de GitHub van PDOK https://github.com/PDOK/delta-download-ref-impl. Daarnaast is er een OpenAPI specificatie, waarvan de URL wordt gepubliceerd bij livegang, waarbij de API in meer detail wordt toegelicht.