VERA richtlijnen

VERA Standaard > Architectuur > Richtlijnen

Op basis van de algemene principes en uitgangspunten zijn er richtlijnen opgesteld die worden gebruikt bij de ontwikkeling van VERA. Er zijn richtlijnen voor:

• Modelleren
• Diagrammen
• Naamgeving
• Koppelvlakdefinities
• Kengetallen

1 Algemeen

AL01 Formuleer standaarden en richtlijnen in gebiedende of generaliserende wijs

Formulering van standaarden en richtlijnen moeten in gebiedende of generaliserende wijs zijn.

AL02 Neem referenties naar externe bronnen op als link

Gebruik hyperlinks voor verwijzingen naar externe bronnen.

AL03 Visualisaties van gegevensdomeinen gebruiken een vastgestelde kleurcodering

De figuren van de domeinen volgen een vaste kleurcodering zodat makkelijk te herkennen is welk VERA gegevensdomein het betreft. De vastgestelde kleurcodering is:

Domein	RGB	CORA
Relaties	R:0 G:153 B:204	Ja
Vastgoed	R:255 G:153 B: 0	Ja
Overeenkomsten	R:204 G: 51 B:153	Ja
Onderhoud	R:108 G:146 B: 0	Ja
Projectontwikkeling	R:119 G:119 B:119	Ja
Woonruimteverdeling	R:51 G: 83 B:118
Dossier	R:181 G:168 B:69
Organisatie	R:80 G:226 B:212
Financiën	R:255 G:255 B:102
Kwaliteit	R:255 G:255 B:255
Algemeen	R:255 G:255 B:255

Tabel 1.1 Kleurcodering VERA informatiedomeinen

De kleurcodering sluit aan bij de kleuren die binnen CORA worden gebruikt, als een domein ook is beschreven in CORA. Doordat VERA meer informatiedomeinen kent dan CORA zijn aanvullende kleurcoderingen gekozen voor deze domeinen. De kleurcodering dient gebruikt te worden in alle diagrammen en illustraties om in één oogopslag te kunnen zien uit welk informatiedomein een tekenobject komt. Het tekenobject is bijvoorbeeld een entiteit in een gegevensmodel, een blok in een diagram of een illustratie. Voor het verbeteren van de leesbaarheid kunnen ook kleurschakeringen gebruikt worden. Bijv. 20% transparant. De RGB kleurcode is opgenomen om te borgen dat in het hele document dezelfde kleurstelling wordt gebruikt en kan ook worden gebruikt om documentatie van derden aan te laten sluiten bij de kleurstelling in de VERA standaard.

1.1 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".

2. Logisch gegevensmodel

2.1 Modelleerrichtlijnen

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.

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.

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).

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

GM12 Attributen die in de toekomst komen te vervallen worden in een release aangegeven

Omdat er gestreefd wordt naar backward-compatibiliteit is het noodzakelijk dat attributen die in een voorgaande versie van VERA zijn gespecificeerd, niet direct in de opeenvolgende versie worden verwijderd. Dit heeft als consequentie dat bij het uitbreiden van de berichtdefinities er rekening mee moet worden gehouden dat er (tijdelijk) verschillende manieren (kunnen) zijn om een element te gebruiken.

In de oplevering van iedere VERA versie worden in de releasenotes uitgangspunten benoemd met hierin (indien van toepassing):

• Indicatie welke attributen zijn toegevoegd
• Aanbeveling over het gebruik van attributen die enkel aanwezig zijn in verband met de compatibiliteit
• Een toelichting over het mogelijk verwijderen van de elementen in een volgende versie

Zolang attributen nog bestaan moeten deze werken. De attributen waarvan bekend is dat deze komen te vervallen moeten bij een nieuwe realisatie van een koppeling zo veel mogelijk vermeden worden. Ook kan men voor bestaande koppelingen het uitfaseren van deze attributen organiseren.

2.2 Tekenrichtlijnen voor gegevensmodellen

GT01 VERA beschrijft gegevensmodellen

Het logische model beschrijft de structuur van en de referenties tussen de gegevensobjecten binnen de entiteiten, en van de relaties tussen entiteiten. Daarbij beschrijven we de attributen van de entiteiten in detail.

GT02 Stel gegevensmodellen op in Archimate

VERA biedt diagrammen die de verschillende entiteiten uit de standaard in relatie met elkaar laten zien. Deze diagrammen worden opgesteld volgens de volgende de Archimate standaard.

GT03 Diagrammen van logische gegevensmodellen volgen een vastgestelde tekenrichtlijnen

Het gegevensmodel wordt gemodelleerd volgens de UML standaard. De gebruikte richtlijnen zijn overgenomen van de UML standaard. Binnen de wiki worden deze in Archimate diagrammen gepresenteerd. In de diagrammen worden alleen de entiteiten en hun onderlinge relaties weergegeven. De attributen worden bij de diagrammen getoond. In onderstaande tabel zijn de tekenrichtlijnen opgenomen.

Voorbeeld	Naam	Toelichting
Voorbeeld	Entiteit	Entiteiten zijn de gegevens die gemodelleerd worden. In de diagrammen wordt hiervan alleen de naam opgenomen, geen attributen of operaties.
Voorbeeld	Generalisatie / specialisatie	Een entiteit is een specialisatie van een andere entiteit (ook wel subtype). In het voorbeeld is NatuurlijkPersoon een subtype van Relatie. Het subtype erft de sleutelattributen van het basistype en heeft dus in de specificatie geen eigen sleutelattributen.
Voorbeeld	Associatie	Een entiteit verwijst naar een andere entiteit. Op de associatie geven we de naam van de relatie aan. Indien deze in meervoud is geformuleerd dan betreft het een meervoudige associatie.

GT04 Opnemen van entiteiten uit aanverwante domeinen

In de diagrammen staan alle entiteiten uit het domein en ook zijn de navigeerbare entiteiten uit andere domeinen opgenomen. Dit om de samenhang tussen de domeinen inzichtelijk te maken en om de context voor het domein duidelijk te maken. Soms worden niet alle navigeerbare entiteiten uit andere domeinen opgenomen i.v.m. leesbaarheid. Algemene entiteiten zoals Referentiedata, extraAttributen, Sturingslabels en informatieobjecten zijn uitzonderingen: die relaties komen nergens terug in de diagrammen.

2.3 Naamgeving voor gegevensmodellen

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.

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

3. Koppelvlakken

3.1 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.

3.2 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.

3.3 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.

3.4 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.

Uitgangspunten

Vanuit de voorgenoemde principes maakt VERA gebruik van uitgangspunten om de ontwikkeling concreter vorm te geven.

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 XML

Als uitgangspunt voor de uitwerking van koppelvlak definities is vanuit principe P03 gehanteerd dat deze gebruik maken van XML. 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 XML gekozen omdat dit formaat gestructureerde verwerking en validatie mogelijk maakt. Daarnaast is XML een wijdverbreide standaard die door elk technologisch platform ondersteund wordt.

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.

---