Richtlijnen

Naamgeving

Voor een eenduidige en herkenbare architectuur passen we naamgevingsregels toe bij het uitwerken van de architectuur en techniek.

Algemene naamgevingsrichtlijnen AN01 termen en begrippen volgen algemeen geaccepteerd Nederlands

De termen en begrippen die gebruikt worden in de standaard, voor bijvoorbeeld entiteitnamen of attribuutnamen, volgen algemeen geaccepteerd Nederlands. Dit betekent dat deze termen en begrippen in principe voluit worden geschreven, tenzij het om een algemeen geaccepteerde afkorting gaat, bijvoorbeeld "BTW".

Schrijfwijze van elementen

Voor sommige elementen hanteren we in CORA een specifieke schrijfwijze, te weten:

Element	Schrijfwijze:
Afnemende rol	Altijd in enkelvoudig zelfstandig naamwoord
Applicatieservice	Een werkwoord eindigend op '-ing' gevolgd door soms een bijvoeglijk naamwoord en altijd één enkelvoudig zelfstandig naamwoord.
Bedrijfsfunctie	In enkelvoudig zelfstandig naamwoord eventueel in combinatie met een bijvoeglijk naamwoord of een werkwoord eindigend op 'atie'.
Bedrijfsproces	Altijd een werkwoord gevolgd door een meervoudig zelfstandig naamwoord
Bedrijfsservice	Bij voorkeur één enkelvoudig zelfstandig naamwoord eventueel voorafgegaan door een bijvoeglijk naamwoord of een werkwoord in de voltooid verleden tijd
Dienst	Bij voorkeur één enkelvoudig zelfstandig naamwoord eventueel voorafgegaan door een bijvoeglijk naamwoord of een werkwoord in de voltooid verleden tijd
Hoofdbedrijfsfunctie	Altijd in enkelvoudig zelfstandig naamwoord
Informatieobject	Indien mogelijk een enkelvoudig zelfstandig naamwoord
Product	Altijd in enkelvoudig zelfstandig naamwoord eventueel voorafgegaan door een bijvoeglijk naamwoord
Werkproces	Altijd een werkwoord gevolgd door een enkelvoudig zelfstandig naamwoord

Producten & diensten

Producten

We hanteren de schrijfwijze voor product: altijd in enkelvoudig zelfstandig naamwoord eventueel voorafgegaan door een bijvoeglijk naamwoord

Diensten

We hanteren de schrijfwijze voor dienst: bij voorkeur één enkelvoudig zelfstandig naamwoord eventueel voorafgegaan door een bijvoeglijk naamwoord of een werkwoord in de voltooid verleden tijd

Bedrijfsservices

We hanteren de schrijfwijze voor bedrijfsservice: bij voorkeur één enkelvoudig zelfstandig naamwoord eventueel voorafgegaan door een bijvoeglijk naamwoord of een werkwoord in de voltooid verleden tijd

Rollen

We hanteren de schrijfwijze voor actoren met een rol: altijd in enkelvoudig zelfstandig naamwoord

Bedrijfsfuncties

We hanteren we de schrijfwijze voor (hoofd)bedrijfsfuncties: altijd in enkelvoudig zelfstandig naamwoord

Processen

Bedrijfsprocessen

We hanteren de schrijfwijze voor bedrijfsprocessen: altijd een werkwoord gevolgd door een meervoudig zelfstandig naamwoord

Werkprocessen

We hanteren we de schrijfwijze voor werkprocessen: altijd een werkwoord gevolgd door een enkelvoudig zelfstandig naamwoord

Applicatieservices

Omdat de applicatieservices altijd één of meerdere handelingen betreft, hebben we ervoor gekozen de schrijfwijze daarop af te stemmen:

We hanteren de schrijfwijze voor applicatieservices: altijd een werkwoord eindigend op '-ing' gevolgd door soms een bijvoeglijk naamwoord en altijd één enkelvoudig zelfstandig naamwoord

Logisch gegevensmodel

Toepassen gegevensobject relatie

GM01 Gegevensmodellen zijn enkelvoudige datamodellen

In het gegevensmodel worden de gegevens en hun relaties op een bepaald moment in de tijd gemodelleerd. De gebruikte kardinaliteit tussen entiteiten in het logisch gegevensmodel drukt dus de mogelijke relaties op een dergelijk moment in de tijd uit. Voor het raadplegen van gegevens op een ander tijdstip dan het huidige zal gewerkt moeten worden met peildatums. Bij het doorgeven van mutaties kunnen in de attributen van een entiteit wel gegevens gebruikt worden die afwijken van het huidige moment.

Zo is bij een klant bijvoorbeeld het inkomen opgenomen. Op een bepaald moment in de tijd (voor een bepaald jaar) kan deze klant maar één inkomen hebben. In de administratie zal voor deze klant ook voor andere jaren een inkomen opgenomen zijn. Het VERA gegevensmodel zegt in deze situatie dat een klant altijd maximaal één inkomen heeft op ieder moment in de tijd.

Gevolg is dat bijvoorbeeld het bericht (operatie) voor het raadplegen van een klant op de VERA koppeling in principe altijd het geldige inkomen van dat moment teruggeeft. Voor het opvragen van inkomens uit het verleden, toekomst, of van een bepaald jaar zijn aparte berichten gedefinieerd waarin gegevens opgevraagd kunnen worden met behulp van peildatums of peilperiodes.

Het gegevensmodel wordt hierdoor consistent en eenvoudiger te begrijpen. Gevolg is wel dat voor een groot aantal entiteiten in het gegevensmodel begin- en einddatums toegevoegd moeten worden om een levenscyclus aan te kunnen geven, en dat er specifieke berichten gedefinieerd zijn om gegevens uit het verleden (of de toekomst) te kunnen raadplegen.

Gegevensobjecten

GM02 Entiteiten worden afgebakend op de logische groepering van attributen

Deze richtlijn is opgesteld om bij het modelleren in VERA te kunnen bepalen wanneer iets een aparte entiteit is en wanneer niet. De richtlijn geeft informatie over hoe bepaald wordt over welke attributen het gaat en vervolgens wanneer deze attributen als aparte entiteit opgenomen moeten worden.

Bij het modelleren kunnen attributen herkend worden die bij elkaar horen omdat ze:

Voor de business een functie hebben. Bijvoorbeeld omdat er processen zijn die specifiek deze attributen beheren en niet de volledige entiteit. Op hetzelfde onderwerp betrekking hebben. Ze gaan bijvoorbeeld over dezelfde soort gegevens of vormen samen informatie over de entiteit. Een dergelijke groep attributen (logisch bij elkaar horend) die met een entiteit te maken heeft wordt als aparte entiteit opgenomen wanneer de groep attributen:

Een veel-op-1 relatie heeft met de entiteit. Met andere woorden: de groep attributen kan meer dan één keer voorkomen bij de entiteit waar het mee te maken heeft.

Een eigen levenscyclus kent. De groep attributen ontstaat eerder of later in de tijd of wordt in een andere frequentie aangepast of vastgesteld dan de entiteit waar het mee te maken heeft. Bijvoorbeeld wanneer de groep attributen vanaf een bepaalde datum van toepassing is. Een andere manier om hier naar te kijken is het verschil tussen 'kunnen' en 'hebben'. Een entiteit 'kan' een groep attributen hebben of een entiteit 'heeft' een groep attributen. Bij ‘kunnen’ wordt de groep als aparte entiteit onderkend, bij ‘hebben’ niet. Anders gezegd wanneer de informatie uit de groep attributen niet altijd van toepassing is of niet altijd voorkomt op de entiteit waar het mee te maken heeft dan wordt de groep als aparte entiteit gemodelleerd. Dit betekent niet dat alles wat niet verplicht is automatisch in een aparte entiteit terecht komt. Een relatie heeft een naam, of die nu gevuld is of niet. Op dezelfde wijze heeft een eenheid een omschrijving en woningwaardering heeft punten. Maar optioneel kan een eenheid een verkoopvraagprijs en een verkoopminimumprijs bevatten.

Voldoet de groep attributen aan één van bovenstaande regels, dan moet het als aparte entiteit opgenomen worden. Daarnaast kan de onderstaande richtlijn een handvat bieden wanneer er twijfel is of een groep attributen in een bestaande entiteit als aparte entiteit opgenomen moet worden:

De groep attributen komt overeen met een CORA bedrijfsobject. Wanneer in CORA de groep attributen (de semantiek) apart onderkend wordt als object (en dus in de vocabulaire van de business) dan zou de groep attributen in het logisch model ook een aparte entiteit kunnen zijn.

GM03 Een entiteit bevat geen eenvoudige afgeleide attributen

Een afgeleid attribuut is een attribuut dat is samengesteld uit andere attributen en/of informatie in de entiteit. Dergelijke attributen worden niet in deze versie van VERA opgenomen. Vaak zijn afgeleide attributen te bepalen door het uitvoeren van presentatielogica. Met presentatielogica wordt de logica bedoeld die verantwoordelijk is voor het presentabel maken van gegevens voor de eindgebruiker.

In sommige gevallen zal er echter een complexe berekening plaats moeten vinden om het afgeleide attribuut te bepalen. Dergelijke complex af te leiden attributen kunnen wel opgenomen worden in de entiteiten omdat deze berekend moeten worden door het systeeem dat de entiteit samenstelt.

Enkele voorbeelden van deze richtlijn:

Stel er zijn twee groepen met woningwaarderingspunten (subtotalen). Het totaal aan woningwaarderingspunten over alle groepen heen, mag opgenomen worden als attribuut. Er zal door het systeem een sommatie uitgevoerd moeten worden om tot het puntentotaal te komen. Het puntentotaal over de groepen heen wordt als attribuut opgenomen aangezien er een wiskundige berekening uitgevoerd moet worden. Stel een entiteit bevat een begin- en einddatum. Een attribuut dat aangeeft of de huidige dag tussen de begin- en einddatum valt, wordt beschouwd als een afgeleid attribuut. Dit omdat er valt af te leiden of de huidige dag tussen de begin- en einddatum valt. Het attribuut is een voorbeeld van af te leiden logica, aangezien het desbetreffende system waarde hecht aan het gegeven of de huidige dag tussen de begin- en einddatums valt. Het bepalen of de huidige dag tussen twee datums valt, is geen complexe berekening. Stel een telefoonnummer is opgesplitst in vier nummerdelen. Het gehele telefoonnummer wordt niet opgenomen als VERA attribuut, aangezien de nummers samengevoegd worden tot een telefoonnummer voor de eindgebruiker. De concatenatie is presentatielogica, aangezien het logica betreft die aangeeft hoe het resultaat aan de eindgebruiker gepresenteerd moeten worden. Er kan bijvoorbeeld per afnemer verschillend besloten worden of er een streepje wordt geplaatst tussen het netnummer en abonneenummer.

Attributen

GN01 De naam van een entiteit of attribuut dient in enkelvoud opgeschreven te worden Namen van entiteiten en attributen dienen in enkelvoud aangegeven te worden. Bijvoorbeeld:

Eenheid
Pand
NatuurlijkPersoon

Uitzondering hierop zijn die attributen die een associatie bevatten naar een collectie van een andere entiteit. Bijvoorbeeld:

Relatie.contactmomenten

GN02 Een entiteitnaam is uniek over alle domeinen heen Een naam van een entiteit moet uniek zijn. Dit geldt zowel binnen een gegevensdomein als over alle gegevensdomeinen heen. Ook woorden die voorkomen in andere entiteiten moeten vermeden worden.

GN03 Een entiteitnaam is geschreven in de UpperCamelCasing stijl Namen van entiteiten worden volgens de UpperCamelCasing gewoonte geschreven. In deze gewoonte wordt begonnen met een hoofdletter en elk volgend woord dat normaliter met een spatie gescheiden wordt van het voorgaande, wordt weer met een hoofdletter begonnen. Bijvoorbeeld:

NatuurlijkPersoon
BouwkundigElement
Relatiegroep
Natuurlijk persoon bestaat uit twee woorden, in dat geval begint de entiteitnaam met een hoofdletter. Het volgende woord wordt zonder spatie achter het eerste woord geplaatst, en begint met een hoofdletter.
Bouwkundig element bestaat uit twee woorden. De entiteitnaam begint met een hoofdletter. Het volgende wordt zonder spatie achter het eerste woord geplaatst, en begint vervolgens met een hoofdletter.
Relatiegroep bestaat uit één woord. De entiteitnaam begint met een hoofdletter en vervolgens kleine letters.

We gaan hierbij uit van de algemeen geldende Nederlandse spelling. Er worden dus alleen hoofdletters toegepast voor woorden die conform de spellingsregels gescheiden geschreven dienen te worden. Men heeft bij het gebruik van camel casing nogal eens de neiging om kunstmatig hoofdletters toe te voegen terwijl dit niet nodig is. Om dit eenduidig te kunnen bepalen wordt gestandaardiseerd op de algemeen geldende Nederlandse spelling. De spellingsregels kunnen worden getoetst bij de Nederlandse Taalunie. Zelfstandige naamwoorden schrijf je altijd aan elkaar.

GM04 Gebruik het attribuut soort om onderscheid tussen typeringen binnen een entiteit aan te geven Binnen een entiteit kunnen meerdere typen of soorten voorkomen. Bijvoorbeeld verschillende soorten woningen. Woning zou hierbij de entiteit zijn, maar van een woning moet wel aangegeven kunnen worden wat voor soort of type het betreft. Dit onderscheid binnen een entiteit wordt aangegeven met het attribuut ‘soort’. Deze attributen zijn altijd van het type Referentiedata. Bijvoorbeeld:

Eenheid.soort is van het type Referentiedata EenheidSoort

De entiteit Eenheid kent verschillende typeringen voor eenheden. Het attribuut ‘soort’ is van het type referentiedata voor alle mogelijke eenheidsoorten.

Een uitzondering op deze regel is wanneer het in vaktaal of formele taal gebruikelijk is om het ‘type’ te noemen. Zo is het in de bedrijfsadministratie gebruikelijk om over een 'boekingstype' te spreken. In dit soort uitzonderlijke gevallen mag afgeweken worden van deze regel en kan er een attribuut 'boekingstype' in plaats van 'boekingssoort' opgenomen worden.

Het gebruik van het attribuut ‘soort’ staat los van het wel of niet definiëren van subentiteiten. De belangrijkste reden om in VERA wel of geen subentiteit op te nemen is de afweging of er attributen bestaan die alleen voor die specifieke subentiteit bestaan.

GM05 Gebruik het attribuut status om de procesvoortgang van een instantie van een entiteit aan te geven Iedere instantie van een entiteit doorloopt een aantal processtappen tijdens zijn levenscyclus, bijvoorbeeld aangemaakt, actief, vervallen. Dit soort informatie wordt aangegeven met het ‘status’ attribuut. Bijvoorbeeld:

Eenheid.status is van het type Referentiedata EenheidStatus

De entiteit Eenheid kent verschillende statussen. Het attribuut ‘status’ is van het type referentiedata voor alle mogelijke statussen van de eenheid.

GM06 Duid aanvang en einde van de levenscyclus van een instantie van een entiteit met begindatum en einddatum

Iedere instantie van een entiteit heeft een begin- en einde van zijn levenscyclus. Dit wordt aangegeven met de attributen ‘begindatum’ en ‘einddatum’. Andere alternatieven als start- en stopdatum worden niet gehanteerd. Bijvoorbeeld:

Eenheid.begindatum van type datetime
Eenheid.einddatum van type datetime

De entiteit Eenheid heeft voor een bepaalde eenheid een instantie. Deze instantie heeft een begindatum en -tijdstip en een einddatum en -tijdstip.

GM07 Gebruik detailAttribuutnaam om hiërarchische relaties tussen attributen aan te geven Tussen sommige attributen kan een hiërarchische relatie bestaan. De waarde in een attribuut kan een waarde uit een ander attribuut nader specificeren. Bijvoorbeeld een eenheid dat van de soort ‘woning’ is, maar vervolgens nader verbijzonderd wordt als een ‘2-onder-1-kap woning’. Dit wordt aangegeven door de namen van de twee attributen aan elkaar gelijk te maken met de prefix 'detail' voor het attribuut op het laagste niveau. Bijvoorbeeld:

soort en detailSoort
status en detailStatus

GM08 Een attribuut voor een einde van een periode kan een date of een datetime datatype hebben

Voor datums en tijden die het einde aangeven van een periode (bijvoorbeeld einddatum en -tijdstip) worden twee verschillende datatypes onderkend: date en datetime. Aan deze datatypes wordt niet alleen gekoppeld of de tijdcomponent wel of niet van toepassing is, maar ook een uitspraak over de betekenis van de datum.

Een datetime datatype staat voor een geldigheid "tot" de aangegeven waarde (exclusief aangegeven waarde). Een date datatype staat voor een geldigheid "tot en met" de aangegeven waarde (inclusief aangegeven waarde). Bijvoorbeeld:

Einddatum 7-5-2021 16:00:00 betekent:
Wel geldig: tot vier uur ‘s middags op 7 mei (anders gezegd: tot en met 15:59:59 op 7 mei)
Niet geldig: vanaf vier uur ‘s middags op 7 mei (anders gezegd: om 16:00:00 op 7 mei is het gegeven niet meer geldig).

Einddatum 7-5-2021 betekent:
Wel geldig: op 7-5-2021 tot en met middernacht (anders gezegd: tot en met 00:00:00 op 7 mei)
Niet geldig: vanaf 8-5-2021 vanaf één seconde na middernacht (anders gezegd: om 00:00:01 op 8 mei is het gegeven niet meer geldig).

Voor het begin van een periode (bijvoorbeeld begindatum en –tijdstip) wordt dit onderscheid niet gemaakt. Hierbij is het namelijk intuïtief dat de periode altijd begint vanaf het moment dat is aangegeven (een specifiek tijdstip of middernacht aan het begin van een dag).

GN04 Een attribuutnaam is geschreven in de lowerCamelCasing stijl Namen van attributen worden volgens de lowerCamelCasing gewoonte geschreven. In deze gewoonte wordt begonnen met een kleine letter en elk volgend woord wat normaliter met een spatie gescheiden wordt, wordt weer met een hoofdletter begonnen. Bijvoorbeeld:

kadastraalNummer
status
erfpachtPerTermijnBedrag

In het bovenstaande voorbeeld worden de woorden kadastraal en nummer samengevoegd tot kadastraal nummer. We gaan ook hierbij uit van de algemeen geldende Nederlandse spelling. Zie GN03.

GN05 Een attribuut heeft een primitief datatype of een entiteit als datatype Attributen in VERA hebben datatypes. De set aan beschikbare datatypes is beperkt. Een datatype kan of een primitief type zijn of een (collectie van) een bestaande entiteit uit de standaard. Bijvoorbeeld:

Relatie.naam van het type string (primitief)
Eenheid.adres van het type Adres (entiteit uit de standaard)

De set aan primitieve types is gelijk aan de set aan datatypes die zijn opgenomen in de XSD standaard W3C, 2012 (W3C, 2012). De meest gangbare types hieruit zijn:

string
integer
boolean
decimal
duration
datetime
date
time
anyURI
base64Binary

GN06 Een attribuutnaam is uniek binnen een entiteit Binnen een entiteit moet de naam van een attribuut uniek zijn. Indien een attribuut in een andere entiteit een vergelijkbare functie heeft, dan moet, indien mogelijk, ook dezelfde naam worden gebruikt. Bijvoorbeeld: Voor het verwijzen naar een medewerker is de attribuutnaam medewerker. Als in een andere entiteit ook wordt verwezen naar een medewerker dan moet dat attribuut bij voorkeur ook de naam medewerker krijgen en niet de meer algemene naam relatie of een heel andere naam zoals werknemer.

GN07 Een attribuutnaam van een collectie is altijd in meervoud Een attribuut kan als datatype een collectie van primitieve types of entiteiten bevatten. Wanneer dat zo is wordt de attribuutnaam in het meervoud geschreven. Dit is een expliciete uitzondering op de richtlijn GN01 waarin gesteld wordt dat attributen altijd in enkelvoud geschreven worden. Bijvoorbeeld:

Publicatie.eenheden van type Collectie type Eenheid.

De entiteit publicatie kan een collectie eenheden bevatten. Het is overigens niet toegestaan om simpelweg het attribuut eenheid vaker te laten voorkomen in Publicatie. Wel kunnen er uiteraard meerdere attributen zijn van dezelfde entiteit maar die moeten dan een verschillende functie hebben. Alle waarden of entiteit instanties in een collectie hebben dezelfde functie en prioriteit, er is geen sprake van een specifieke ordening or rangvolgorde.

GN08 Een attribuutnaam begint nooit met de naam van de entiteit De naam van een attribuut begint nooit met de naam van de entiteit. De entiteit Eenheid mag geen attribuut eenheidId of eenheidsoort bevatten. Het attribuut eenheidId zal aangepast moeten worden naar id en het attribuut eenheidsoort naar soort. Een uitzondering op deze richtlijn is een attribuut dat refereert naar een andere entiteit; die attributen hebben juist bij voorkeur de naam van de andere entiteit tenzij een specifieke sub set bedoeld wordt. Bijvoorbeeld:

gebouw: attribuut van entiteit Gebouw
wijk: attribuut van entiteit Wijk
buurt: attribuut van entiteit Buurt

Wel kan de naam later in de attribuutnaam voorkomen. Bijvoorbeeld:

bovenliggendeEenheid: attribuut van entiteit Eenheid in de entiteit Eenheid

GN09 Een attribuutnaam eindigt met het onderwerp van het attribuut De naam van een attribuut moet voldoende beschrijvend zijn. Door de naam van een attribuut te eindigen met het onderwerp waar het attribuut over gaat. Deze richtlijn valt als volgt te interpreteren:

Goed:

overlijdensdatum: De datum van overlijden. Het onderwerp van het attribuut is de datum.
gebeurtenistijdstip: Het tijdstip waarop een gebeurtenis plaatsvindt. Het onderwerp is het tijdstip.
kortingspercentage: Het percentage dat aan korting wordt verkregen of wordt gegeven.

Fout:

datumOverlijden: Het onderwerp van het attribuut is de datum. Het overlijden geeft een betekenis aan de datum. Daarom is dit een incorrect gedefinieerd attribuut.
percentageKorting: Het woord korting is een bijvoeglijk naamwoord dat aangeeft om welk percentage het gaat. Dit is om deze reden een incorrect gedefinieerd attribuut.

GN10 Associatie tussen entiteiten is zichtbaar bij het relationele attribuut In de diagrammen is navigatie tussen entiteiten aangegeven door middel van associatie-relaties met een pijl in de richting van de relatie. Deze associaties zijn in de attribuutoverzichten opgenomen als attributen.

GN11 Een attribuutnaam die uit een externe registratie komt begint met een prefix van de externe registratie Attribuutnamen die komen uit externe registraties als de BAG, GBA, WOZ etc. moeten een prefix krijgen van deze administraties. Bijvoorbeeld:

BagAdres.bagNummeraanduidingIdentificatie
Eenheid.wozEenheden

GM09 Alle attributen zijn optioneel In VERA worden de attributen standaard optioneel opgenomen. Hier is voor gekozen om zo min mogelijk belemmeringen op te werpen voor de implementeerbaarheid. Attributen die niet gevuld kunnen worden vanuit het systeem kunnen leeggelaten worden zonder de VERA definities te breken. Het is hiermee dus de verantwoordelijkheid van de bericht ontvangende partij om te bepalen welke attributen gevuld moeten zijn en hoe hiermee omgegaan wordt. Door deze richtlijn is de drempel om VERA toe te passen laag omdat het ieder systeem de ruimte geeft om tot optimale berichten te komen. Maar omdat wat voor het ene systeem een optioneel veld is, dat voor een ander systeem misschien niet zo is, blijft data-integriteit een verantwoordelijkheid van het eigen systeem.

GM10 Associaties leggen op het hoogst mogelijke niveau Een associatie tussen twee zaken wordt op entiteitniveau gelegd; dat wil zeggen het meest algemene niveau dat van toepassing kan zijn. Met andere woorden: een associatie wordt altijd op een basisentiteit gelegd wanneer de associatie voor alle subentiteiten van toepassing is of kan zijn. Is een associatie niet van toepassing op alle subentiteit(en), dan zal deze dus niet op de basisentiteit gelegd kunnen worden. Dit zou zelfs kunnen betekenen dat er een extra entiteit tussen de basisentiteit en de subentiteit(en) wordt toegevoegd om de associatie op te kunnen leggen.

GM11 Gebruik van id's Elke entiteit in VERA krijgt standaard id's om de entiteit te kunnen identificeren.

id; string; De primaire sleutel van het gegeven in het bronsysteem. Je verstuurd een entiteit altijd met het eigen id. Id kan leeg zijn. idExtern; string; De primaire sleutel van het gegeven in het doelsysteem. Deze idExtern wisselt om met id afhankelijk van de richting van de gegevensuitwisseling. Als je een bericht stuurt dan vul je het id met je eigen primaire sleutel. Meestal een nummer of guid. Als je ook het externe id van het gegeven weet kun je deze in idExtern meesturen. Als je een bericht ontvangt dan is het id uit het bericht het id dat je opslaat in idExtern en is idExtern uit het bericht je eigen id waarop je kunt matchen. idGegevensbeheerder; string; De primaire sleutel van het gegeven van de gegevensbeheerder. Bijv. de overheid of andere standaarden. Code; string; De sleutel die gebruikers kunnen lezen en onthouden.

Verdere toelichting gebruik van ID's: Identificatie gegevensobjecten

Berekeningen maken met attributen Binnen verschillende klasses zijn attributen te vinden waarmee berekeningen gemaakt kunnen worden. Denk hierbij aan afmetingen zoals oppervlaktes of inhoud, bedragen op overeenkomsten, of een herinneringsmoment o.b.v. datums. Alle informatie die een woningcorporatie beschikbaar moet hebben zijn middels een berekening via deze attributen te bepalen. Vanuit VERA proberen wij zelf samengestelde (opgetelde/berekende) velden weg te blijven omdat de verschillende berekeningen die nodig zijn per doel uiteenlopen. De basisattributen horen wel in het gegevensmodel thuis en middels eigen bedrijfsregels of met behulp van informatiserings platformen kunnen de correcte berekeningen gemaakt worden om de corporaties te voorzien van het samengestelde attribuut waar naar zij op zoek zijn. Binnen het model bestaan enkele uitzonderingen waarvan bepaald is dat deze dusdanig breed binnen de sector wordt gebruikt en nuttig is om als attribuut te definieren. Indien opgemerkt wordt dat een dergelijk attribuut zou moeten bestaan maar niet te vinden is dan kan dit worden aangevraagd bij het VERA-architectuurteam (vera-architectuurteam@aedesdatastandaarden.nl).

De verschillende data types van attributen Per attribuut wordt bepaald in welke format deze over de lijn gaat in de communicatie tussen partijen. Aansluitend op het bovenstaande verhaal zijn vanwege deze reden een groot aantal attributen gedefinieerd in dergelijk format waarmee gerekend kan worden. De verschillende formats die bestaan zijn: string (platte tekst), datum, datum-tijd, decimal/integer/long, boolean en binary data (bijv. BASE64 representatie van een bestaand zoals een PDF).

String is het type dat het meest zal voorkomen en is zoals eerder vermeld 'platte tekst'. Hier kan niet mee gerekend worden tenzij de data door een partij zelf omgezet wordt in een ander type. In de gevallen waar een attribuut als string is gedefinieerd is de verwachting dat met deze velden ook geen berekening hoeft te worden gemaakt. Denk hierbij aan een 'id' of 'naam'.

Verder zullen attributen de decimal duiding hebben waarmee direct berekeningen uitgevoerd kunnen worden, denk hierbij aan 'oppervlakteTotaal' of 'brutohuur'.

Naast de decimal attributen zijn ook andere berekenbare attributen die een datum of datum-tijd aangeven. Een 'einddatum' op een overeenkomst is een datum type. Een 'registratiedatum' is over het algemeen een datum-tijd type. Beide attributen kunnen berekeningen op worden uitgevoerd indien wenselijk.

In sommige gevallen bestaan ook attributen die met een boolean worden geduid omdat voor deze attributen logisch gezien geen andere waarde bestaat dan 'Ja' (true) of 'Nee' (false). Denk hierbij aan een attribuut 'verkoop' op de klasse 'eenheid' die aangeeft of de eenheid voor verkoop is of niet.

Tot slot zullen enkele attributen van het type binary (base 64 binary) zijn. Denk hierbij aan het 'bestand' attribuut bij de 'informatieobject' klasse die een representatie is van een bestand dat gedeeld moet worden tussen partijen, bijv. een foto, document of andersoortige bestanden.

Relaties, soorten en rollen

We hebben de implementatie van de entiteiten Relatie, NatuurlijkPersoon, Rechtspersoon, Relatiegroep en Relatierol consistent gemaakt.

Op hoofdlijnen:

Er zijn geen directe verwijzingen in attributen meer naar NatuurlijkPersoon, Rechtpersoon en Relatiegroep. Deze zijn allemaal omgezet naar een attribuutverwijzing naar Relatie of Relaties.

Attribuutnamen met specifieke rollen zijn samengevoegd naar een Relatie of Relaties attribuut. Bij de verwezen Relaties kan de rol die van toepassing is worden opgenomen.

Het is mogelijk gemaakt om direct bij een relatiegroep een collectie van de relaties op te nemen. Dat hoeft niet meer via Relatierol.

Bijvoorbeeld:

Attribuut Eenheid.eigenaar was een verwijzing naar een relatie in eerdere versies van VERA. Nu vind je de eigenaar in Eenheid.Relaties waar Relatie.relatierol.soort = "Eigenaar". Om deze functionaliteit te kunnen leveren in het logische VERA model is het nodig om in het technische datamodel van leveranciers een koppeltabel te hebben tussen Eenheden en RelatieRollen. Optioneel kan men daarbij ook de relatie vastleggen zodat je die niet via de rol hoeft op te zoeken.

Attribuut CollectiefObject.eigenaar was een verwijzing naar een Rechtspersoon in eerdere versies. Nu vind je de de eigenaar in CollectiefObject.relaties waar Relatie.relatierol.soort = "Eigenaar".

→ Meer informatie over het toepassen van relaties

Referentiedata

RD01 Uniciteit attribuut Code

Code is uniek binnen de referentiedatasoort waartoe de code behoort.

RD02 Naamgeving attribuut Code

De code bestaat uit drie tekens, tenzij het binnen de referentiedatasoort niet mogelijk is een unieke, betekenisvolle, code op basis van drie tekens toe te voegen. In dat geval is het toegestaan een extra teken te gebruiken.

De code wordt gevormd door de eerste drie tekens van de naam van het item (DOC voor “Documenten niet aangeleverd"), tenzij een andere lettercombinatie een betekenisvolle(r) resultaat geeft, bijvoorbeeld de beginletters van een naam die uit drie woorden bestaat (VAH voor “Verkoop aan huurder”)

RD03 Hiërarchie binnen referentiedata

Het gebruik van het attribuut Parent is optioneel. Indien van toepassing wordt de parent van een waarde weergegeven als {BOVENLIGGENDE REFERENTIEDATASOORT}.{CODE}.

Een waarde heeft ten hoogste één parent.

RD04 Geldigheid van een waarde

Vervallen waarden krijgen een Einddatum. Van vervallen waarden kan in de omschrijving een toelichting worden gegeven op de verwijdering (bijvoorbeeld omdat de waarde is vervangen door een andere waarde, of de reden waarom een waarde is komen te vervallen).

Nieuw toegevoegde waarden krijgen een Begindatum.

De attributen Begindatum en Einddatum bepalen daarmee of een waarde geldig is op een peilmoment.

RD05 Informatiedomein(en) bij een waarde

Het attribuut Informatiedomein wordt gebruikt om aan te geven in welk(e) informatiedomein(en) de referentiedatasoort gebruikt word(t)(en).

Koppelvlakken

KI01 Volgen van (inter)nationale standaarden De door VERA beschreven berichten en schema’s volgen richtlijnen die zijn opgesteld door VNG Common Ground.

KI02 Administratieve correcties Richtlijn: "GM01 Gegevensmodellen zijn enkelvoudige datamodellen” beschrijft dat de attributen begindatum en einddatum onderdeel zijn van het logische gegevensmodel. De richtlijn gaat alleen over het opstellen van de logische gegevensmodellen. Hoe de technische interface werkt staat hier los van. Door voor enkelvoudigheid in het gegevensmodel te kiezen is het bijvoorbeeld duidelijk wat de enkelvoudige relaties voor een bericht zijn en tot op welk niveau uniciteit geldig is.

Bij het opvragen van historische gegevens (in verleden of toekomst) gaat het bij VERA altijd om de zogenaamde ‘formele’ historie, oftewel: ‘de geldige data’. De transactionele historie – ook wel gedefinieerd als administratieve correcties – zijn geen onderdeel van de VERA standaard. Bij het opvragen in het verleden wordt er dus altijd vanuit gegaan dat men de formeel geldige data opvraagt en niet alle details omtrent administratieve correcties. Het doorvoeren van administratieve correcties kan ingediend worden als RFC als in de praktijk blijkt dat er behoefte is aan deze functionaliteit.

Documentrichtlijnen voor koppelvlakken

KT01 Technische modellen zijn opgesteld in OpenApi en YAML De entiteiten en hun relaties worden technisch uitgewerkt in YAML. Voor het vastleggen van de mogelijke interacties met de webservices bestaan OpenApi documenten die zijn vormgegeven volgens de VERA standaard. In de paragraaf Interoperabiliteit worden uitgangspunten en aandachtsgebieden genoemd inzake de interoperabiliteit met verschillende platforms.

Naamgeving voor koppelvlak beschrijvingen

KN01 Naamgeving technische uitwisseling De naamgeving voor de verschillende onderdelen van de technische uitwisseling is gebaseerd op VNG Common Ground en aangepast voor het gebruik in VERA. Dit wordt beschreven in de betreffende VERA versie.

Versie

Om versies van de standaard bij te houden wordt er gewerkt met een versienummer. De opbouw van dit nummer bestaat uit twee delen:

Iteratie van de versie van VERA als nummer van twee posities. Bijv. 01.

Het versienummer van VERA is vastgelegd in de specificatie van de informatiemodellen van de gegevensdomeinen en ketenprocessen.

Procesberichten

Horizontaal versus verticaal (procesberichten)

Het VERA model bestaat uit een verzameling van klassen met onderliggende attributen en eventueel andere klassen. Volgens richtlijnen van VERA is het mogelijk om op al deze klassen te muteren (bijv. een create/post of update/put). Dit wordt ook wel het horizontale model genoemd. Het horizontale model bevat klassen met hun basisgegevens zoals bijvoorbeeld een overeenkomst. Deze klasse heeft een set aan attributen die bij elke vorm van een overeenkomst gebruikt kunnen worden, ongeacht de procescontext. Ditzelfde zou je kunnen toepassen op andere klassen.

Tegenover het horizontale model en de berichten die daarin mogelijk zijn bestaat het 'verticale model' waarin procesberichten prominent zijn. In deze zogeheten procesberichten komen de verschillende klassen van het horizontale model terug. Afhankelijk van procescontext is echter een afwijkende behoefte aan aanvullende informatie nodig. Afhankelijk van de procescontext en de behoefte zullen de berichten voor dezelfde entiteit anders qua payload kunnen zijn. Dit wordt duidelijker aan de hand van een voorbeeld. Wanneer men vanuit de procescontext van het WRV proces een eenheid aanbiedt is informatiebehoefte anders dan wanneer men redeneert vanuit de procecontext van het beheren van vastgoedgegevens. Beide processen hebben middels de laatste versie van VERA een API om eenheden aan te bieden of updaten (post en put /eenheden) maar de body van deze berichten is niet hetzelfde. Ze maken beide gebruik van de klasse uit het horizontale model en hebben verder specifieke velden naar behoefte van de procescontext. Zo heeft de eenheid in procescontext bijvoorbeeld een publicatielabel maar de eenheid in beheren vastgoedgegevens niet. Andersom heeft de eenheid bij beheren vastgoedgegevens een attribuut 'wozeenheden' en is deze niet aanwezig op de eenheid in de context van het WRV procesbericht.

API implementatierichtlijnen

Authenticatie in VERA API's

De VERA API's kennen twee authenticatiewijzen: 1. API-KEY Deze authenticatiewijze maakt het mogelijk om op basis van een API-KEY mee te sturen toegang te geven tot bepaalde gegevens. Dit is een simpele manier van authenticatie waarbij de API-KEY toegang geeft tot de hele API. 2. oAuth2 met scopes Met oAuth is het mogelijk om naast authenticatie ook een vorm van autorisatie teo te passen. Het concept wat hiervoor wordt gebruikt zijn de zgn. Scopes. Iedere resource in VERA API's kent de volgende scopes: Alleen lezen, of lezen en schrijven. De aanroepende partij dient op het moment van authenticatie mee te geven voor welke scopes er toegang wordt gevraagd.

Specificatie in YML files In de YML files wordt onderscheid gemaakt tussen globale scopes, en resource specifieke scope. De globale scope geeft Lees-/Schrijfrechten op alle resources in het model. De resource specifieke scopes zijn per API methode ingesteld. Voor een Post/Patch methode op een resource zijn schrijfrechten nodig. Voor de Get methode alleen leesrechten. Standaardnaamgeving voor de scope op resource niveau volgt het volgende patroon: <Model>.<Resource>.<Access> Model - Het vera model (WRV, OHD etc,…) Resource - Naam van de resource in het model (Eenheden, Overeenkomsten etc,..) Access - Read of ReadWrite

Voorbeelden: 
* VHE.Eenheden.Read
* VHE.Eenheden.ReadWrite

De globale scope wordt per model gedefinieerd en kent volgende naamgeving: <Model>.<All>.<Acces>

Voorbeelden:
* WRV.All.Read
* WRV.All.ReadWrite

Identificatie van gegevensobjecten

Consistente en uniforme benaming en structuur van sleutels voor objecten binnen VERA is van groot belang voor gegevensbeheer, softwareontwikkeling en interoperabiliteit tussen verschillende systemen.|Architectuur banner1600x300.webp}} Naast unieke identificatie van gegevens binnen het eigen systeem is het ook van belang om dezelfde gegevens te kunnen identificeren in gekoppelde systemen. VERA hanteert hierbij de volgende belangrijke uitgangspunten:

• Een gegeven wordt beheerd door één bronsysteem: single-source-of-truth
• Aanmaken, wijzigen of verwijderen van gegevens dient altijd plaats te vinden in het bronsysteem
• In de uitwisseling van een gegeven tussen systemen is altijd gebaseerd op de unieke sleutel van het bronsysteem.
  
  

Voor het uniek identificeren van entiteiten binnen VERA zijn er een aantal standaard id's opgenomen:

attribuut	type	Definitie
id	string	De unieke, primaire sleutel van het gegeven binnen het systeem waar het gegeven vastgelegd is en waarmee de associaties met andere entiteiten binnen hetzelfde systeem worden gelegd.
idExtern	string	De unieke, primaire sleutel van het gegeven in het bronsysteem waar het gegeven beheerd wordt. Met bronsysteem bedoelen we het systeem waarin de entiteit beheerd wordt binnen het ICT landschap van een organisatie. Het bronsysteem is de single-source-of-truth.
idOrganisatie	string	De verwijzing naar de organisatie waar de bron van het gegeven ligt. Behorende bij 'idExtern'.
idAdministratie	string	De verwijzing naar de administratie binnen de specifieke organisatie waar de bron van het gegeven ligt. Horende bij 'idExtern'.
idGegevensbeheerder	string	De primaire sleutel van het gegeven van de gegevensbeheerder. Bijv. de overheid of andere standaarden.
code	string	De sleutel die gebruikers kunnen lezen en onthouden.

Single-source-of-truth Bovengenoemde set aan sleutels is bruikbaar voor verschillende situaties. Wanneer een gegeven in één systeem vastligt en niet wordt uitgewisseld dan is het gebruik van 'id' (en mogelijk 'code') voldoende; een gegeven wordt aan de hand van één veld uniek geïdentificeerd in het systeem en er is geen relatie met andere systemen. Bij uitwisseling van gegevens tussen systemen is het noodzakelijk om hetzelfde gegeven in het ene systeem te kunnen herkennen in het andere systeem. Een belangrijk uitgangspunt hierbij is dat er altijd maar één bron van de waarheid is voor een gegeven: wanneer een gegeven gewijzigd wordt moet dat altijd in het bronsysteem doorgevoerd worden (single-source-of-truth). Met de attributen 'idExtern', 'idOrganisatie' en 'idAdministratie' is het mogelijk om gegevens in een systeem te relateren aan het gegeven in het bronsysteem.

Regels voor gebruik id's Er zijn de volgende regels voor gebruik van id's:

POST - Bij een POST request wordt GÉÉN 'id' meegestuurd naar het bronsysteem omdat het bronsysteem de unieke sleutel van het gegeven bepaald. Het bronsysteem is nl. de eigenaar van het gegeven. In de response van het bronsysteem wordt het unieke 'id' van het gegeven teruggestuurd en kan in het doelsysteem geregistreerd worden als 'idExtern'. Het doelsysteem bepaald voor het lokaal opgeslagen gegeven een eigen uniek 'id'. Dit kan hetzelfde 'id' zijn als het bronsysteem maar dat hoeft niet. De combinatie 'idExtern' + 'idOrganisatie' + 'idAdministratie' bepaald de uniciteit van het gegeven in het doelsysteem.

PATCH/PUT - Bij het wijzigen van een gegeven in het bronsysteem moet het unieke 'id' in het bronsysteem gebruikt worden voor de identificatie. Het doelsysteem moet daarvoor gebruik maken van de sleutel in het attribuut 'idExtern' in het doelsysteem. De attributen 'idOrganisatie' en 'idAdministratie' kunnen gebruikt worden om het specifieke bronsysteem te bepalen.

GET - Het opvragen van één gegeven (GET by id) gaat uit van het 'id' van het bronsysteem waar de GET op uitgevoerd wordt. Ook hier gebruik je het attribuut 'idExtern' samen met 'idOrganisatie' en 'idAdministratie' om het juiste bronsysteem te bepalen.

Toepassing in de praktijk In deze paragraaf zijn een aantal mogelijke praktijksituaties beschreven waarin het gebruik van de verschillende sleutels duidelijk gemaakt wordt.

Situatie 1 : Synchronisatie tussen bron- en doelsysteem zonder PubSub In de situatie dat twee systemen gegevens uitwisselen met elkaar is altijd één van de twee systemen de bron. Wanneer er wijzigingen in de bron plaatsvinden zal dit door het bronsysteem kenbaar gemaakt worden bij het doelsysteem. In deze situatie is het bronsysteem bekend met het bestaan van het doelsysteem en zijn afspraken gemaakt over het verstrekken van de informatie aan het doelsysteem.

scenario 1 : Informatie relatie gewijzigd in bronsysteem

1. Event wordt verstuurd naar het doelsysteem dat 'id'=1 is gewijzigd
2. Doelsysteem bepaald op basis van 'id'=1 de juiste relatie in het eigen systeem. Filter daarbij is: 'idExtern'=1
3. Doelsysteem voert een GET uit naar bronsysteem met 'id'=1 en haalt de relatie-informatie op.
4. Doelsysteem ontvangt de gegevens en slaat deze op bij de relatie met 'idExtern'=1

scenario 2 : Informatie relatie wijzigen in bronsysteem door doelsysteem

1. Doelsysteem bepaald het 'id' van de relatie in het bronsysteem aan de hand van het 'idExtern' (=2).
2. Doelsysteem voert een PATCH uit naar bronsysteem met 'id'=2 en geeft de gewijzigde gegevens door.

scenario 3 : Nieuwe relatie opgevoerd in bronsysteem

1. Notificatie wordt verstuurd naar het doelsysteem dat 'id'=4 is toegevoegd in bronsysteem
2. Doelsysteem voert een GET uit naar bronsysteem met 'id'=4 en haalt de relatie-informatie op.
3. Doelsysteem ontvangt de gegevens en slaat deze op als nieuwe relatie met 'idExtern'=4 en een eigen unieke sleutel binnen het doelsysteem (D4).

scenario 4 : Nieuwe relatie opgevoerd door het doelsysteem Het is bekend dat nieuwe relaties opgevoerd moeten worden in het bronsysteem.

1. Doelsysteem voert een POST uit zonder 'id' en geeft de gegevens van de relatie door aan bronsysteem.
2. Bronsysteem maakt de relatie aan en geeft het 'id' van het bronsysteem ('id'=6) terug in het response.
3. Doelsysteem slaat 'id'=6 op als 'idExtern' bij de betreffende relatie

Situatie 2 : Synchronisatie tussen bron- en doelsysteem met PubSub In de situatie dat twee systemen gegevens uitwisselen met elkaar via een zogenaamd Publish/Subscribe mechanisme zal het doelsysteem zich abonneren op events van het bronsysteem. Wanneer een gegeven aangemaakt of gewijzigd (of verwijderd) wordt in het bronsysteem zal er door het bronsysteem een event verstuurd worden naar de eventbus. Omdat het doelsysteem zich heeft geabonneerd op events van het bronsysteem zal het bericht door het doelsysteem worden opgepakt en kunnen de gegevens in het doelsysteem bijgewerkt worden.

scenario 1 : Informatie relatie gewijzigd in bronsysteem

1. Event wordt op de eventbus gezet dat 'id'=1 is gewijzigd
2. Omdat doelsysteem zich heeft geabonneerd op events van bronsysteem krijgt het doelsysteem een notificatie dat de relatie met 'id'=1 is gewijzigd.
3. Het doelsysteem bepaald op basis van 'id'=1 de juiste relatie in het eigen systeem. Filter daarbij is: 'idExtern'=1
4. Doelsysteem voert een GET uit naar bronsysteem met 'id'=1 en haalt de relatie-informatie op.
5. Doelsysteem ontvangt de gegevens en slaat deze op bij de relatie met 'idExtern'=1

scenario 2 : Informatie relatie wijzigen in bronsysteem door doelsysteem

1. Doelsysteem bepaald het 'id' van de relatie in het bronsysteem aan de hand van het 'idExtern' (=2).
2. Doelsysteem voert een PATCH uit naar bronsysteem met 'id'=2 en geeft de gewijzigde gegevens door.
3. Omdat de relatie met 'id'=2 is gewijzigd in het bronsysteem wordt er een event op de Eventbus gezet.
4. Het doelsysteem ontvangt een notificatie en kan indien gewenst de relatie opvragen.

scenario 3 : Nieuwe relatie opgevoerd in bronsysteem

1. Het bronsysteem zet een event op de Eventbus waarin gemeld wordt dat een nieuwe relatie is opgevoerd met 'id'=4.
2. Omdat het doelsysteem zich heeft geabonneerd ontvangt het een notificatie voor relatie met 'id'=4.
3. Doelsysteem voert een GET uit naar bronsysteem met 'id'=4 en haalt de relatie-informatie op.
4. Doelsysteem ontvangt de gegevens en slaat deze op als nieuwe relatie met 'idExtern'=4 en een eigen unieke sleutel binnen het doelsysteem (D4).

scenario 4 : Nieuwe relatie opgevoerd door het doelsysteem Het is bekend dat nieuwe relaties opgevoerd moeten worden in het bronsysteem.

1. Doelsysteem voert een POST uit zonder 'id' en geeft de gegevens van de relatie door aan bronsysteem.
2. Bronsysteem maakt de relatie aan en geeft het 'id' van het bronsysteem ('id'=6) terug in het response.
3. Doelsysteem slaat 'id'=6 op als 'idExtern' bij de betreffende relatie
4. Omdat de relatie met 'id'=6 is aangemaakt in het bronsysteem wordt er een event op de Eventbus gezet.
5. Het doelsysteem ontvangt een notificatie en kan indien gewenst de relatie opvragen.

Situatie 3 : Synchronisatie van 2 bronsystemen naar 1 doelsysteem met PubSub Het is mogelijk dat een doelsysteem twee bronnen heeft waar de data vastligt. Een doelsysteem kan bijvoorbeeld de relaties van 2 bronsystemen samenvoegen. Belangrijk uitgangspunt blijft dat een gegeven altijd maar één bron (single-source-of-truth) heeft; een specifieke relatie kan niet in twee bronsystemen beheerd worden.

scenario 1 : Informatie relatie gewijzigd in bronsysteem O1

1. Event wordt door bronsysteem O1 op de eventbus gezet dat 'id'=1 is gewijzigd in administratie A1
2. Omdat doelsysteem zich heeft geabonneerd op events van bronsysteem O1 en O2 krijgt het doelsysteem een notificatie dat de relatie met 'id'=1 is gewijzigd in bronsysteem O1.
3. Het doelsysteem bepaald op basis van 'id'=1 de juiste relatie in het eigen systeem. Filter daarbij is: 'idExtern'=1, 'idOrganisatie'=O1 en 'idAdministratie'=A1
4. Doelsysteem voert een GET uit naar bronsysteem O1 en administratie A1 met 'id'=1 en haalt de relatie-informatie op.
5. Doelsysteem ontvangt de gegevens en slaat deze op bij de juiste relatie

scenario 2 : Informatie relatie wijzigen in bronsysteem O1 door doelsysteem

1. Doelsysteem bepaald het 'id' van de relatie in het bronsysteem aan de hand van het 'idExtern' (=2), 'idOrganisatie' (=O1) en 'idAdministratie' (A2).
2. Doelsysteem voert een PATCH uit naar het juiste bronsysteem met 'id'=2 en geeft de gewijzigde gegevens door.
3. Omdat de relatie met 'id'=2 is gewijzigd in bronsysteem O1 wordt er een event op de Eventbus gezet.
4. Het doelsysteem ontvangt een notificatie en kan indien gewenst de relatie opvragen.

scenario 3 : Nieuwe relatie opgevoerd in bronsysteem O2

1. Het bronsysteem O2 zet een event op de Eventbus waarin gemeld wordt dat een nieuwe relatie is opgevoerd met 'id'=4.
2. Omdat het doelsysteem zich heeft geabonneerd op bronsysteem O2 ontvangt het een notificatie voor relatie met 'id'=4.
3. Doelsysteem voert een GET uit naar bronsysteem O2 met Administratie A1 en 'id'=4 en haalt de relatie-informatie op.
4. Doelsysteem ontvangt de gegevens en slaat deze op als nieuwe relatie met 'idExtern'=4, idOrganisatie='O2', 'idAdministratie'=A1 en een eigen unieke sleutel binnen het doelsysteem (D4).

scenario 4 : Nieuwe relatie opgevoerd door het doelsysteem Het is bekend dat nieuwe relatie opgevoerd moeten worden in bronsysteem O2.

1. Doelsysteem voert een POST uit zonder 'id' naar bronsysteem O2 en Administratie A1
2. Bronsysteem O2 maakt de relatie aan en geeft het 'id' van het bronsysteem ('id'=6) terug in het response.
3. Doelsysteem slaat 'id'=6 op als 'idExtern', 'idOrganisatie'=O2 en 'idAdministratie'=A1 bij de betreffende relatie
4. Omdat de relatie met 'id'=6 is aangemaakt in bronsysteem O2 wordt er een event op de Eventbus gezet.
5. Het doelsysteem ontvangt een notificatie en kan indien gewenst de relatie opvragen.

Situatie 4 : Synchronisatie van 1 bronsysteem naar 2 doelsysteem met PubSub In het Publish/Subscribe-mechanisme kunnen meerdere doelsystemen abonneren op events van een bronsysteem. Het versturen van een event door het bronsysteem op een Eventbus kan daarmee door meerdere doelsystemen los van elkaar opgepakt worden.

scenario 1 : Informatie relatie gewijzigd in bronsysteem

1. Event wordt door bronsysteem op de eventbus gezet dat 'id'=1 is gewijzigd in administratie A1
2. De geabonneerde doelsystemen krijgen een notificatie en bepalen elk om welke relatie het gaat ('idOrganisatie'=O1, 'idAdministratie'=A1 en 'idExtern'=1) in het eigen systeem.
3. Doelsystemen voeren een GET uit naar bronsysteem O1 en administratie A1 met 'id'=1 en halen de relatie-informatie op.
4. Doelsystemen ontvangen de gegevens en slaan deze op bij de juiste relatie in het eigen systeem

scenario 2 : Informatie relatie wijzigen in bronsysteem door doelsysteem D1

1. Doelsysteem D1 bepaald het 'id' van de relatie in het bronsysteem aan de hand van het 'idExtern' (=2), 'idOrganisatie' (=O1) en 'idAdministratie' (A2).
2. Doelsysteem D1 voert een PATCH uit naar het juiste bronsysteem met 'id'=2 en geeft de gewijzigde gegevens door.
3. Omdat de relatie met 'id'=2 is gewijzigd in bronsysteem O1 wordt er een event op de Eventbus gezet.
4. Beide doelsystemen ontvangen een notificatie en identificeren de relatie in het eigen systeem.
5. Doelsysteem D2 zal een GET uitvoeren naar bronsysteem O1 om de (door doelsysteem D2) gewijzigde gegevens van de relatie op te vragen.
6. Doelsysteem D1 kan eventueel ook een GET uitvoeren om de gegevens in het eigen systeem bij te werken indien nodig.

scenario 3 : Nieuwe relatie opgevoerd door doelsysteem D2 Het is binnen doelsysteem D2 bekend dat een nieuwe relatie opgevoerd moeten worden in bronsysteem.

1. Doelsysteem D2 voert een POST uit zonder 'id' naar bronsysteem en Administratie A1
2. Bronsysteem maakt de relatie aan en geeft het 'id' van het bronsysteem ('id'=4) terug in het response.
3. Doelsysteem D2 slaat de relatie in het eigen systeem op met 'idExtern'=4, 'idOrganisatie'=O1 en 'idAdministratie'=A1 en met een eigen sleutel (D2_4)
4. Omdat de relatie met 'id'=4 is aangemaakt in bronsysteem wordt er een event op de Eventbus gezet.
5. Beide doelsystemen ontvangen een notificatie en identificeren de relatie in het eigen systeem.
6. Doelsysteem D1 zal de relatie nog niet kennen en daarom het nieuwe gegeven opslaan met 'idExtern'=4, 'idOrganisatie'=O1 en 'idAdministratie'=A1 en met een eigen sleutel (D1_4)
7. Doelsysteem D2 kan eventueel ook een GET uitvoeren om de gegevens in het eigen systeem bij te werken indien nodig.

Gebruik van Attributen in JSON Payload

Dit document beschrijft het juiste gebruik van attributen in JSON payloads bij het communiceren met onze REST API's. We volgen hierbij de specificaties van RFC 8259, waarin de definities van 'leeg' zijn vastgelegd:

Voor een waarde (simple type): null

Voor een object: {}

Voor een array: []

Bij het toepassen van deze definitie op een voorbeeldobject zoals "Relatie," zien we het volgende:

{
  "soort": {},
  "adressen": [],
  "geboortedatum": null
}

In dit voorbeeld worden de volgende situaties geïllustreerd:

• Het attribuut "soort" heeft geen Referentiedata-object gekoppeld. In dit geval wordt het als leeg beschouwd en vertegenwoordigd door {}.
• Het attribuut "adressen" is een lege verzameling van Relatieadres-objecten. Het wordt als leeg beschouwd en vertegenwoordigd door [].
• Het attribuut "geboortedatum" is een eenvoudig gegevenstype en heeft geen waarde. Hier wordt het als leeg beschouwd en vertegenwoordigd door null. Let op dat "null" niet tussen dubbele aanhalingstekens mag staan, zoals aangegeven in JSON-notatie.

Belangrijk om op te merken is dat het weglaten van attributen uit een bericht niet dezelfde betekenis heeft als 'leeg'. Hier volgt een overzicht van de interpretaties:

• Bij HTTP-methoden GET, POST en PATCH, wanneer een attribuut wordt weggelaten, wordt het genegeerd. Het heeft geen invloed op bestaande gegevens.
• Bij de HTTP-methode PUT moeten alle attributen aanwezig zijn. Het vervangt de bestaande gegevens volledig door de nieuwe gegevens in het payload-object.
• Bij de HTTP-methoden POST, PATCH en PUT worden attributen als leeg beschouwd wanneer ze worden weergegeven als leeg (bijvoorbeeld {} of []) of als null (zonder dubbele aanhalingstekens). Dit betekent dat de betreffende attributen worden leeggemaakt of verwijderd in de context van het verzoek.

Het correct begrijpen en toepassen van deze regels is cruciaal om consistentie en betrouwbaarheid te garanderen bij het gebruik van onze REST API's met JSON payloads.

Berichten

Koppelvlak richtlijnen

KI01 Volgen van (inter)nationale standaarden De door VERA beschreven berichten en schema’s volgen richtlijnen die zijn opgesteld door VNG Common Ground.

KI02 Administratieve correcties Richtlijn: "GM01 Gegevensmodellen zijn enkelvoudige datamodellen” beschrijft dat de attributen begindatum en einddatum onderdeel zijn van het logische gegevensmodel. De richtlijn gaat alleen over het opstellen van de logische gegevensmodellen. Hoe de technische interface werkt staat hier los van. Door voor enkelvoudigheid in het gegevensmodel te kiezen is het bijvoorbeeld duidelijk wat de enkelvoudige relaties voor een bericht zijn en tot op welk niveau uniciteit geldig is.

Bij het opvragen van historische gegevens (in verleden of toekomst) gaat het bij VERA altijd om de zogenaamde ‘formele’ historie, oftewel: ‘de geldige data’. De transactionele historie – ook wel gedefinieerd als administratieve correcties – zijn geen onderdeel van de VERA standaard. Bij het opvragen in het verleden wordt er dus altijd vanuit gegaan dat men de formeel geldige data opvraagt en niet alle details omtrent administratieve correcties. Het doorvoeren van administratieve correcties kan ingediend worden als RFC als in de praktijk blijkt dat er behoefte is aan deze functionaliteit.

Documentrichtlijnen voor koppelvlakken

KT01 Technische modellen zijn opgesteld in OpenApi en YAML De entiteiten en hun relaties worden technisch uitgewerkt in YAML. Voor het vastleggen van de mogelijke interacties met de webservices bestaan OpenApi documenten die zijn vormgegeven volgens de VERA standaard. In de paragraaf Interoperabiliteit worden uitgangspunten en aandachtsgebieden genoemd inzake de interoperabiliteit met verschillende platforms.

Naamgeving voor koppelvlak beschrijvingen

KN01 Naamgeving technische uitwisseling De naamgeving voor de verschillende onderdelen van de technische uitwisseling is gebaseerd op VNG Common Ground en aangepast voor het gebruik in VERA. Dit wordt beschreven in de betreffende VERA versie.

Versie

Om versies van de standaard bij te houden wordt er gewerkt met een versienummer. De opbouw van dit nummer bestaat uit meerdere delen: Het versienummer van VERA is vastgelegd in de specificatie van de gegevensmodellen en procesberichten.

Voor uitleg over het versienummer: VERA Release en versiebeleid

U01 UML wordt gebruikt om modellen in VERA op te stellen

Op basis van principe P03 wordt gebruik gemaakt van de Unified Modelling Language (UML) (Object Management Group, 2011) om VERA modellen op te stellen. UML is een modelmatige taal om ontwerpen en analyses van informatiesystemen te maken. De taal is sinds 1997 een ISO standaard en wordt de facto gebruikt bij het modelleren van informatiesystemen. Vanwege deze bekendheid in relatie tot ontwikkeling en implementatie van informatiesystemen wordt UML gebruikt om VERA modellen op te stellen.

U02 koppelvlakken maken gebruik van JSON REST

Als uitgangspunt voor de uitwerking van koppelvlak definities is vanuit principe P03 gehanteerd dat deze gebruik maken van JSON REST. Dit is een standaard van het World Wide Web Consortium voor de syntaxis van formele opmaaktalen waarmee gestructureerde gegevens kunnen worden weergeven in de vorm van platte tekst. Deze presentatie is zowel leesbaar voor machines als leesbaar voor de mens. VERA heeft voor JSON REST gekozen omdat dit formaat gestructureerde verwerking en validatie mogelijk maakt. Daarnaast is JSON REST een wijdverbreide standaard die door elk technologisch platform ondersteund wordt.

Kengetallen

U03 Voor kengetallen gaat VERA voor het meest bruikbare model

Eenvoud gaat voor architectonische elegantie. Om breed door de markt geaccepteerd te worden, is het belangrijk dat het model gebruiksvriendelijk is. Dit kan soms betekenen dat keuzes worden gemaakt ten koste van bijvoorbeeld volledigheid.

U04 VERA houdt zich bezig met het verzamelen van gegevens voor kengetallen

Vanuit de doelstelling van VERA om gegevensuitwisseling te standaardiseren is de methodiek gericht op het koppelvlak met het VERA gegevensmodel ten behoeve van rapportages en analyses. Over het tonen van data in de rapportages en analyses worden geen uitspraken gedaan.

U05 De kengetallenmethodiek is bruikbaar voor alle corporaties

De informatiebehoefte van kleine en grote corporaties kan aanzienlijk uiteen lopen. Ook de data- en informatiearchitectuur die hiervoor wordt opgesteld zal verschillen. Sommige corporaties zullen direct willen rapporteren op de gegevens uit VERA, andere corporaties zullen de VERA gegevens eerst historisch willen opslaan in bijvoorbeeld een datawarehouse en willen deze integreren met andere gegevensbronnen. Doel van de informatie-uitwisseling is om gegevens uit VERA zodanig te ontsluiten c.q. aan te bieden dat ze zowel bruikbaar zijn voor corporaties zonder datawarehouse als voor corporaties met een datawarehouse.

U06 Kengetallen sluiten aan bij de VERA entiteit

De informatie-uitwisseling sluit aan bij de VERA entiteiten: Er wordt dus geen nieuw gegevensmodel gerealiseerd. Dit scheelt veel werk en door VERA-structuur en -terminologie te hergebruiken, wordt het gebruiksgemak van het model verhoogd. De verantwoordelijkheid voor de aanlevering ligt bij de leveranciers van applicaties.

Nog verwerken:
** Richtlijnen VERA_richtlijnen