Leveringenstaat

Betekenis en doel

De leveringenstaat is de volledige verzameling van projecties die op basis van het gevolgenjournaal afleidbaar zijn, en waaruit concrete leveringen aan afnemers worden gegenereerd. De naam is ontleend aan gebruik van het woord staat in samenstellingen als 'staat van dienst' of 'urenstaat', waarbinnen het zoiets betekent als "geformaliseerd, geordend overzicht".

Waar het gevolgenjournaal nauwkeurig documenteert wat er is gebeurd, beantwoordt de leveringenstaat primair vragen als "leeft persoon p1 nog?", "wat is zijn burgerlijke staat?", en "heeft hij gezag over p3?" Zulke vragen veronderstellen een stand (ook wel toestand of state), ofwel een beeld van de wereld dat gedurende een bepaalde periode geldig is.

Niet alle projecties beschrijven een stand. Een notificatiebericht is daarvan een voorbeeld: het informeert een afnemer over een verandering die door registratie van een gevolg is veroorzaakt. Net als het onderliggende gevolg is zo'n bericht temporeel atomair - het beschrijft wat er is gebeurd, niet welke toestand na die gebeurtenis geldig werd.

Iedere concrete levering is een op de informatiebehoefte van een specifieke afnemer of doelgroep toegesneden uitsnede uit de leveringenstaat. Daarbij kan niet alleen de actuele state worden geleverd, maar op basis van selecties over meerdere tijdsassen eventueel ook historische toestanden.

Hoe de leveringenstaat technisch wordt bijgehouden is een implementatiekeuze: daarbinnen beschikbare projecties kunnen vooraf worden berekend en opgeslagen, of op het moment van bevraging worden gegenereerd op basis van de gevraagde parameters.

De herhaalbare vraag

Zoals eerder in dit document genoemd is het een belangrijke eis van een betrouwbaar register om, zoveel als mogelijk, de herhaalbare vraag te kunnen beantwoorden. Een afnemer moet, nadat deze op tijdstip T1 een gegeven heeft opgevraagd, op tijdstip T2 nog steeds de vraag kunnen stellen wat dit gegeven op tijdstip T1 was. Een betrouwbaar register dient dit te kunnen nadat:

1. Er nieuwe gevolgen zijn toegevoegd aan de registratie.
2. Een gegeven hersteld is doordat het geldigheidstijdvak is veranderd vanwege een foutieve registratie.
3. Een softwarebug in de opvraging is hersteld waardoor de initiële opvraging fout was.

Criterium 1 en 2 introduceren bitemporaliteit in de registratie. Criterium 3 vereist dat er mechanismen zijn die het mogelijk maken softwareaanpassingen te doen met behoud van de eerdere gegevensrepresentatie.

Inherente beperkingen aan de herhaalbare vraag

Elke registratie loopt tegen inherente beperkingen aan. Zowel geldigheids- als gevolgtijdstippen hebben te maken met eventual consistency: er zit altijd tijd tussen het begin van een registratie en het einde daarvan, en er zit altijd tijd tussen een opvraging en de zichtbaarheid van deze gegevens voor de afnemer. Dit betekent dat een afnemer altijd in potentie naar verouderde informatie kijkt.

Daarnaast heeft een registratie meestal niet de volledige controle over de aflevering van informatie. Entiteiten verlaten op een bepaald moment de registratie om elders te worden gepresenteerd — in een browser, een API-response, of een ander systeem dat de registratie niet kent.

Herhaalbaarheid van opvraging is dus hoogstens te behalen tot op het niveau van de gegevensrepresentatie net voordat deze het systeem verlaat.

De tijdsassen van een projectie

• Geldigheidstijdstip — (zie geldigheid)
• Gevolgtijdstip — wanneer het gevolg in de registratie is vastgelegd
• Projectietijdstip — wanneer het snapshot zichtbaar is geworden in de projectie

Door deze drie assen te combineren in een query is tijdreizen mogelijk: "hoe zag dit gegeven eruit op tijdstip X, zoals vastgelegd op tijdstip Y, zichtbaar in de projectie op tijdstip Z?"

Aandachtsgebieden in de leveringenstaat

Terugmelden

Terugmeldingen hebben altijd betrekking op een projectie - een concrete uitsnede uit de leveringenstaat zoals die aan een afnemer is geleverd. De afnemer meldt dat hij twijfelt aan de juistheid van (een deel van) die projectie.

Omdat projecties over uiteenlopende samenstellingen van gegevens kunnen gaan en de aard van geconstateerde onjuistheden sterk kan verschillen, kan een terugmelding vele vormen aannemen. Daarbij past geen beperkend 'terugmeldformulier', maar (vorm)vrijheid en veel ruimte voor toelichting in vrije tekst.

Als een bronhouder regelmatig terugmeldingen van dezelfde strekking ontvangt, kan hij overwegen daarvoor een specifieke, meer gestructureerde interface aan te bieden. Dit verlaagt de drempel voor de terugmelder en maakt de verwerking aan de kant van de bronhouder efficiënter.

Een terugmelding bevat in ieder geval:

• Verwijzing naar de betreffende gegevens. De terugmelder geeft aan op welke projectie of welk onderdeel daarvan de melding betrekking heeft. Hoe die verwijzing er precies uitziet, is afhankelijk van hoe projecties identificeerbaar zijn gemaakt - bijvoorbeeld via een uniek kenmerk van de levering of een combinatie van subject en tijdstip
• Toelichting. De terugmelder beschrijft in vrije tekst wat hij als onjuist beschouwt en waarom. Dit biedt de bronhouder de context die nodig is om het onderzoek gericht te kunnen starten.
• Contactgegevens van de terugmelder. Zodat de bronhouder, indien het onderzoek daarom vraagt, contact kan opnemen voor nadere toelichting of terugkoppeling.

Open vragen

• Terugmelden is binnen het stelsel voor basisregistraties een voorwaarde voor afwijken van gegevens in de bron. Zouden terugmeldende afnemers dan voor eigen gebruik en hangende een onderzoek hun eigen, vermoedelijk juistere 'alternatieve' gegevens in het register moeten kunnen zetten?
• Hoe wijzen we gegevens waarover we terugmelden voor de bronhouder (historisch) onderscheidbaar aan?

Onderzoeken

Onderzoek naar aanleiding van een terugmelding vindt plaats buiten het register en leidt niet tot nieuwe projecties in de leveringenstaat. Wel kan uit onderzoek blijken dat bij vermoedelijk onjuiste projecties indicaties van verminderde zekerheid over de juistheid moeten worden aangebracht.

Corrigeren

In de meeste gevallen is een levering foutief omdat 1 of meerdere gevolgen die de basis vormen van deze projectie foutief waren. Het corrigeren van een dergelijke levering begint dan met correctiegevolgen in het gevolgenjournaal. Een correctiegevolg bevat de gevolgen 'hoe ze hadden moeten zijn', en op basis van deze subgevolgen kan een projectie hersteld worden. Er wordt bepaald vanaf welk moment een bestaande projectie niet langer geldig is. Die projectie krijgt daarna een vervallen op-indicatie, waarmee de levering voor actief gebruik wordt afgesloten. En daarnaast worden nieuwe projecties gemaakt, die met terugwerkende kracht de foutieve projecties bovenschrijven.

Het is ook mogelijk dat uit onderzoek blijkt dat de oorspronkelijk vastgelegde gevolgen correct waren, en dat de fout hem in de afleiding van de projectie zit. Een dergelijke softwarefout zal hersteld moeten worden, waarna een volledige of selectieve replay gedaan moet worden: Ook in dit scenario moet bepaald worden vanaf welk moment een bestaande foutieve snapshot niet langer geldig is, en dat deze moet vervallen. Foutieve snapshots worden geïdentificeerd en opnieuw opgebouwd, waarna ze toegevoegd worden aan de leveringenstaat en de oude snapshot bovenschrijven.

Verwerkingsverantwoording

Omdat projecties direct worden afgeleid uit gevolgen in het gevolgenjournaal, is verwerkingsverantwoording aan de kant van de leveringenstaat beperkter van omvang dan aan de journaalkant. De voornaamste verantwoording ligt immers al besloten in de gevolgen waarop een projectie is gebaseerd.

Aanleiding

De aanleiding verwijst naar het gevolg of de gevolgen die als basis dienden voor de productie van de projectie. Daarmee is de herkomst van een projectie altijd herleidbaar naar het gevolgenjournaal.

Legitimering

Voor zover van toepassing wordt een verwijzing vastgelegd naar het wettelijk of beleidskader dat diende als grondslag voor de productie van de projectie - bijvoorbeeld als regelgeving voorschrijft welke gegevens aan welke afnemers geleverd mogen of moeten worden.

Verklaring

De verklaring omvat een verwijzing naar het algoritme of de algoritmes die zijn gebruikt om van één of meer gevolgen een projectie af te leiden, inclusief de versie daarvan. Zo is achteraf reconstrueerbaar op welke manier de projectie tot stand is gekomen.

Registratie

Bij iedere concrete levering kan het moment van opname in de leveringenstaat worden meegeleverd. Of dat wenselijk is, hangt af van de situatie. Bij een vraag naar de actuele stand is registratietijd vaak niet relevant. In andere gevallen kan het meesturen ervan juist ongewenst zijn, omdat het informatie kan onthullen die niet met iedereen gedeeld mag worden, zoals het feit dat een correctie heeft plaatsgevonden.

Geldigheid

Bij projecties die zijn opgebouwd uit meerdere gevolgen, is het belangrijk onderscheid te maken tussen de geldigheidsdatum van de projectie zelf en de domeindatums van de gegevens daarbinnen.

De geldigheidsdatum van een projectie geeft aan vanaf welk moment deze weergave in deze vorm als 'juist' of 'waar' beschouwd wordt. Die datum zegt (dus) niets over de ouderdom van in de projectie betrokken objecten of andere daarin opgenomen gegevens.

Neem als voorbeeld de volgende gevolgen:

• woz-object w1 ontstaan | gebeurd op 15-08-1994
• belanghebbende bij woz-object w1 is p1 | gebeurd op 23-08-1994
• belanghebbende bij woz-object w1 is p2 | gebeurd op 19-10-2009
• belanghebbende bij woz-object w1 is p3 | gebeurd op 07-03-2023

Het WOZ-object bestaat al sinds 15-08-1994, maar de projectie is voor het laatst bijgewerkt naar aanleiding van het gevolg van 07-03-2023. Die datum markeert dus niet het ontstaan van het object, maar het meest recente domeinmoment dat de huidige vorm van de projectie heeft bepaald.

Zonder die toelichting riskeert een afnemer de datum verkeerd te interpreteren. Uit de projectie moet de betekenis daarom voldoende duidelijk blijken - bijvoorbeeld door de geldig vanaf-datum expliciet aan de projectie te koppelen (zie het voorbeeld hieronder), of door aan te geven dat die datum de laatste relevante wijziging in het domein betreft.

projectie l1
  geldig vanaf 07-03-2023
  woz-object w1
    eerste registratie 15-08-1994
    belanghebbenden
      p1
        start belang 23-08-1994
        einde belang 18-10-2009
      p2
        start belang 19-10-2009
        einde belang 06-03-2023
      p3
        start belang 07-03-2023

Zekerheid

Zekerheidsaanduidingen zijn in de eerste plaats relevant voor afnemers. Zekerheid moet daarom zichtbaar zijn in leveringen en (dus) onderdeel zijn van projecties.

Omdat onzekerheid diep kan doorwerken in ketens, is het niet altijd voldoende alleen de zekerheid van een projectie als geheel aan te geven. Een daartoe geautoriseerde afnemer moet ook kunnen zien welk onderliggend gevolg de bron van twijfel is, zodat hij kan beoordelen in hoeverre zijn eigen verwerking daarop steunt en hoe hij daarmee wil omgaan.

Afhankelijk van de situatie kan een afnemer er bijvoorbeeld voor kiezen een bedrijfsregel situationeel buiten werking te stellen, onzekerheid door te geven aan zijn eigen afnemers, of processen die op de gegevens steunen expliciet te laten waarschuwen wanneer zij onzekere gegevens tegenkomen.

Onttrekking

Of een onttrekking ingrijpt in het gevolgenjournaal, de leveringenstaat, of beide, hangt af van waar de fout zat. Zat deze fout uitsluitend in de wijze waarop leveringen uit het gevolgenjournaal werden afgeleid - en niet in de gevolgen zelf - dan volstaat het de afleidingswijze te corrigeren en nieuwe projecties te produceren.

In alle gevallen resulteert een onttrekking in opname van een vervallen op-moment (zie ook corrigeren) bij de door de onttrekking geraakte projecties. Daarmee wordt de projectie voor actief gebruik afgesloten, zonder dat de oorspronkelijke vastlegging verdwijnt. De onttrokken projectie blijft om de herhaalbare vraag te waarborgen technisch behouden. Die is daarna echter alleen onder specifieke voorwaarden - bijvoorbeeld voor juridisch of historisch onderzoek - toegankelijk.

Als de onttrekking betrekking heeft op identiteitsdragende kenmerken van een projectie, wordt de volledige projectie onttrokken. Bij niet-identiteitsdragende kenmerken kan onttrekking beperkt blijven tot die kenmerken, mits de implementatie dit technisch toelaat.

Resultaat voor onttrokken gegevens moet in normaal verkeer hetzelfde resultaat zijn als bevragingen van niet-bestaande gegevens.

Ontwerpafwegingen

TODO

Dit moet nog verder uitgewerkt worden

Temporaliteit

Een belangrijke factor voor een projectie is de keuze voor wat betreft temporaliteit. Voor het kunnen beantwoorden van de herhaalbare vraag is bitemporaliteit een eis: Als ingegrepen wordt op de tijdlijn, bijvoorbeeld als gevolg van een correctie, dient de projectie nog steeds de oorspronkelijke snapshot te kunnen reproduceren.

Bitemporaliteit brengt op zichzelf echter complexiteit met zich mee die niet in alle gevallen nodig is. Wanneer een herhaalbare vraag kunnen stellen minder of niet van belang is, zou een specifieke temporele projectie op de geldigheidstijdlijn of alleen een actuele state projectie ook kunnen voldoen.

Query-complexiteit versus query-flexibiliteit

De keuze van gegevensrepresentatie van een projectie en de gewenste informatie die een afnemer blieft bepaalt de complexiteit van de (database)query die gedaan moet worden om in een informatiebehoefte te voorzien. In het voorgestelde patroon, waarin we commando's, gevolgen en projecties van elkaar scheiden, hebben we niet meer de 'ballast' van de commandokant, en kunnen we onze projecties specifieker optimaliseren voor de afnemer(s).

Hier zijn echter nog steeds afwegingen in te maken. Een projectie kan dusdanig gebouwd worden op een manier dat de payload response van een query as is (in bijvoorbeeld een json of xml structuur) opgeslagen wordt in de database. We noemen dit snapshotting. Deze wijze van opslaan heeft een aantal voordelen:

1. Dit is de best mogelijke manier om de herhaalbare vraag te kunnen beantwoorden: De payload wordt as-is opgeslagen, en veranderende code beïnvloedt deze payload niet.
2. Omdat de structuur van het bericht vast ligt, ook nadat er codewijzigingen gedaan worden, kan er in terugmeldingen en onderzoeken via bijvoorbeeld xpath of jsonpath hard verwezen worden naar entiteiten of velden waarover getwijfeld wordt.
3. De (database)query is eenvoudig: Op basis van tijdstippen en een index dient een payload opgezocht te worden. Dit voorkomt grotendeels het leveren van foutieve informatie als gevolg van foutief geïmplementeerde queries.

Zeker in combinatie met bitemporaliteit zien wij snapshotting als een goede keuze voor wat betreft informatielevering. Bitemporaliteit kan, in combinatie met bijvoorbeeld ingewikkelde correcties, zeer ingewikkelde situaties opleveren die zelfs voor experts moeilijk te doorgronden zijn. Het feit dat de query eenvoudig is en de payload statisch is bij snapshotting, zelfs in bitemporele vorm, maakt dat deze projectievorm uitermate robuust is voor het beantwoorden van de herhaalbare vraag.

Snapshotting heeft echter ook nadelen: Omdat de datastructuur zo rigide vast ligt kun je moeilijker, of niet, meerdere soorten vragen beantwoorden met dezelfde projectie. Ook leent deze vorm van opslag zich minder voor joins (het combineren van verschillende payloads/entiteiten). Dit alles maakt deze structuur minder flexibel, en dit dwingt je tot het maken van veel hele afnemerspecifieke projecties.

Het meer traditionele relationele model kan naargelang behoefte dan nog steeds een goede keuze zijn. Een relationeel model, en zeker een bitemporeel relationeel model, is veel flexibeler in het kunnen beantwoorden van allerhande soorten queries. De aard van de datarepresentatie maakt echter wel de queries en de mapping naar de doelstructuur van de payload complexer, wat de herhaalbaarheid van vragen doet afnemen.

Betrouwbare modellen versus onbetrouwbare realiteit

Een goed datamodel beschrijft structuren, entiteiten en properties van een domein. Een huisnummer is een getal, terwijl een adres een straatnaam bevat als string met een maximaal aantal karakters. Deze eigenschappen worden idealiter goed gevalideerd aan de commandokant, en door dat te doen kun je duidelijke contracten afspreken met je afnemers over wat voor data je levert en in welke vorm. Dergelijke modellen bepalen databasestructuren en beperkingen voor wat betreft gegevensopslag.

De realiteit is echter vaak weerbarstig: Ooit verkeerd geïmplementeerde validaties, oude data uit migraties of veranderingen in het datamodel naar verloop van tijd kunnen er in veel gevallen voor zorgen dat de data die je hebt niet altijd voldoet aan het voorgeschreven gegevensmodel. Huisnummers met letters, te lange straatnamen... Als je gebonden bent aan het principe van het kunnen beantwoorden van de herhaalbare vraag zal deze data altijd foutief blijven.

Een relationeel model biedt duidelijkheid over het datamodel, maar is minder flexibel als het gaat om data die niet aan dit model voldoet. Er moet altijd een keuze gemaakt worden: voor zeldzame uitzonderingen dient het model aangepast te worden, of deze uitzonderingen kunnen niet verwerkt worden. Hetzelfde probleem geldt vaak voor berichtvalidaties via bijvoorbeeld XSD's.

De consequenties van bijvoorbeeld een verhuizing niet doorgeven omdat een straatnaam te lang bevonden wordt zien wij als zeer onwenselijk. Afhankelijk van de datakwaliteit kan het dan een betere keuze zijn om data-opslag en berichtverkeer flexibeler te maken zodat afwijkingen van het datamodel wel opgeslagen en gecommuniceerd kunnen worden. Richting een afnemer kan het dan wenselijk zijn deze communicatie te doen met een extra melding: "in dit bericht voldoen we niet aan het datamodel".

Generaliseerbaar versus specifieke implementatie

Moet nog verder ingevuld worden.

Varianten

Hieronder volgt een niet-uitputtende lijst van varianten van projecties die gebruikt kunnen worden. Elke projectievariant heeft voor- en nadelen die, afhankelijk van de use case, sterker of minder sterk gelden. Het is niet ons doel om te stellen welk van deze varianten de voorkeur geniet. Wel willen we voor- en nadelen van projectievarianten benoemen.

Temporaliteit	Relationele database	Snapshots	Projectiegevolgen
actueel
temporeel
bitemporeel

Transactionaliteit

Een gevolg legt 1 besluit of gebeurtenis vast. Dit besluit kan bestaan uit deelbesluiten of anderszins opdeelbare elementen, maar uiteindelijk betreft het nog steeds 1 besluit, dat (voor zover relevant voor de projectie) in zijn geheel wel of niet verwerkt dient te worden in een projectie, wat in databasetermen betekent dat een gevolg altijd in precies 1 databasetransactie verwerkt dient te worden. Het verwerken van een door de business erkend gevolg in meerdere (database)transacties kan er namelijk toe leiden dat datacorruptie optreedt: als een gevolg in twee transacties verwerkt wordt, zou de tweede transactie mis kunnen gaan, waarbij een illegale situatie ontstaat.