VERA 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

Inhoud

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 gegevensdomeinen

De kleurcodering sluit aan bij de kleuren die binnen CORA worden gebruikt, als een domein ook is beschreven in CORA. Doordat VERA meer gegevensdomeinen 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 gegevensdomein een tekenobject komt. Het tekenobject is bijvoorbeeld een klasse in een klassenmodel, 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 klassenamen 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 klassen 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 klasse 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 klassen 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 Klassen 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 klasse is en wanneer niet. De richtlijn geeft informatie over hoe bepaald wordt over welke attributen het gaat en vervolgens wanneer deze attributen als aparte klasse 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 klasse.
  • Op hetzelfde onderwerp betrekking hebben. Ze gaan bijvoorbeeld over dezelfde soort gegevens of vormen samen informatie over de klasse.

Een dergelijke groep attributen (logisch bij elkaar horend) die met een klasse te maken heeft wordt als aparte klasse opgenomen wanneer de groep attributen:

  • Een veel-op-1 relatie heeft met de klasse.

Met andere woorden: de groep attributen kan meer dan één keer voorkomen bij de klasse 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 klasse 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 klasse 'kan' een groep attributen hebben of een klasse 'heeft' een groep attributen. Bij ‘kunnen’ wordt de groep als aparte klasse onderkend, bij ‘hebben’ niet. Anders gezegd wanneer de informatie uit de groep attributen niet altijd van toepassing is of niet altijd voorkomt op de klasse waar het mee te maken heeft dan wordt de groep als aparte klasse gemodelleerd. Dit betekent niet dat alles wat niet verplicht is automatisch in een aparte klasse 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 klasse opgenomen worden. Daarnaast kan de onderstaande richtlijn een handvat bieden wanneer er twijfel is of een groep attributen in een bestaande klasse als aparte klasse 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 klasse kunnen zijn.

GM03 Een klasse bevat geen eenvoudige afgeleide attributen

Een afgeleid attribuut is een attribuut dat is samengesteld uit andere attributen en/of informatie in de klasse. 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 klassen omdat deze berekend moeten worden door het systeeem dat de klasse 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 klasse 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 klasse aan te geven

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

  • Eenheid.soort is van het type Referentiedata EenheidSoort

De klasse 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 subklassen. De belangrijkste reden om in VERA wel of geen subklasse op te nemen is de afweging of er attributen bestaan die alleen voor die specifieke subklasse bestaan.

GM05 Gebruik het attribuut status om de procesvoortgang van een instantie van een klasse aan te geven

Iedere instantie van een klasse 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 klasse 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 klasse met begindatum en einddatum

Iedere instantie van een klasse 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 klasse 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-2012 16:00:00 betekent:
    • Wel geldig: tot vier uur ‘s middags op 7 mei.
    • Niet geldig: vanaf vier uur ‘s middags op 7 mei (zodra de tijd vier uur ‘s middags is, is het niet meer geldig).
  • Einddatum 7-5-2012 betekent:
    • Wel geldig: 7-5-2012 (tot middernacht)
    • Niet geldig: 8-5-2012 (vanaf middernacht)

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 klasseniveau gelegd; dat wil zeggen het meest algemene niveau dat van toepassing kan zijn. Met andere woorden: een associatie wordt altijd op een basisklasse gelegd wanneer de associatie voor alle subklassen van toepassing is of kan zijn. Is een associatie niet van toepassing op alle subklasse(n), dan zal deze dus niet op de basisklasse gelegd kunnen worden. Dit zou zelfs kunnen betekenen dat er een extra klasse tussen de basisklasse en de subklasse(n) wordt toegevoegd om de associatie op te kunnen leggen.

GM11 Gebruik van sleutelattributen

Elke klasse in VERA krijgt sleutelattributen om de klasse te kunnen identificeren. Misschien zijn deze niet altijd van toepassing. Er is besloten om voor de eenvoud deze attributen toch op alle klassen toe te passen.

Bij het uitwisselen van gegevens tussen systemen zijn er veel mogelijke sleutels van toepassing:

  • De sleutel van het verzendende systeem en welk systeem dat is (id).
  • De sleutel van het ontvangende systeem en welk systeem dat is (onderdeel van de klasse).
  • De sleutel van een gegevensbeheerder die over systemen heen geldt (onderdeel van de klasse).
  • De sleutel die gebruikers kunnen lezen en onthouden (code).

Afhankelijk van welke standaard wordt gebruikt voor de uitwisseling (StUF, XBRL etc.) wordt hier verschillend mee omgegaan. Dit geldt niet voor de vierde sleutel, hiervoor gebruiken we het attribuut ‘code’ binnen VERA.

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 klassen, en van de relaties tussen klassen. Daarbij beschrijven we de attributen van de klassen in detail.

GT02 Stel gegevensmodellen op in Archimate

VERA biedt diagrammen die de verschillende klassen 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 Klasse

Klassen zijn de gegevens die gemodelleerd worden. In de diagrammen wordt hiervan alleen de naam opgenomen, geen attributen of operaties.

Voorbeeld Generalisatie / specialisatie

Een klasse is een specialisatie van een andere klasse (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 klasse verwijst naar een andere klasse. 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 klassen uit aanverwante domeinen

In de diagrammen staan alle klassen uit het domein en ook zijn de navigeerbare klassen uit andere domeinen opgenomen. Dit om de samenhang tussen de domeinen inzichtelijk te maken en om de context voor het domein duidelijk te maken. De diagrammen relaties en vastgoed bevatten geen klassen uit andere domeinen i.v.m. leesbaarheid. Algemene klassen zoals Geometrie, Auditinfo, Referentiedata zijn uitzonderingen: die relaties komen nergens terug in de diagrammen.

2.3 Naamgeving voor gegevensmodellen

GN01 De naam van een klasse of attribuut dient in enkelvoud opgeschreven te worden

Namen van klassen 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 klasse. Bijvoorbeeld:

  • Relatie.contactmomenten

GN02 Een klassenaam is uniek over alle domeinen heen

Een naam van een klasse moet uniek zijn. Dit geldt zowel binnen een gegevensdomein als over alle gegevensdomeinen heen. Ook woorden die voorkomen in andere klassen moeten vermeden worden.

GN03 Een klassenaam is geschreven in de UpperCamelCasing stijl

Namen van klassen 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 klassenaam 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 klassenaam 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 klassenaam 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 klasse 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 klasse uit de standaard. Bijvoorbeeld:

  • Relatie.naam van het type string (primitief)
  • Eenheid.adres van het type Adres (klasse 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 klasse

Binnen een klasse moet de naam van een attribuut uniek zijn. Indien een attribuut in een andere klasse 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 klasse 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 klassen 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 klasse 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 klasse maar die moeten dan een verschillende functie hebben.

Alle waarden of klasse 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 klasse

De naam van een attribuut begint nooit met de naam van de klasse. De klasse 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 klasse; die attributen hebben juist bij voorkeur de naam van de andere klasse tenzij een specifieke sub set bedoeld wordt. Bijvoorbeeld:

  • gebouw: attribuut van klasse Gebouw
  • wijk: attribuut van klasse Wijk
  • buurt: attribuut van klasse Buurt

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

  • bovenliggendeEenheid: attribuut van klasse Eenheid in de klasse 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 klassen is zichtbaar bij het relationele attribuut

In de diagrammen is navigatie tussen klassen 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 VERA maakt gebruik van de StUF standaard

Hoewel VERA er formeel geen deel van uitmaakt volgt VERA de open StUF standaard (VNG/KING).

KI02 Een release van VERA is gebaseerd op een vastgestelde StUF versie

Bij elk release van VERA zal worden vermeld welke versie van StUF wordt ondersteund. Omdat er vanaf VERA 2.0 een keuze is gemaakt voor StUF is het noodzakelijk in het kader van terugwaartse compatibiliteit een aantal uitgangspunten te benoemen. Deze uitgangspunten worden in de releasenotes opgenomen;

  • Modelleerrichtlijnen - GM09 Alle attributen zijn optioneel
  • Modelleerrichtlijnen - GM12 Attributen die in de toekomst komen te vervallen worden in een release aangegeven
  • Koppelvlak richtlijnen - KI01 VERA maakt gebruik van de StUF standaard

In de namespace wordt het versienummer opgenomen van de gebruikte versie van StUF. De gebruikte versie voor het genereren van de entiteiten wordt eveneens opgenomen, waardoor het technisch mogelijk is verschillende versies van VERA van elkaar te onderscheiden. Door voorgenoemde punten is het mogelijk om terugwaartse compatibiliteit te bieden.

KI03 Toevoegingen aan StUF

VERA voegt, naast de twee bestaande StUF horizontale sectormodellen voor de overheid, een eigen horizontaal sectormodel toe aan de StUF familie. Nieuwe VERA sectormodellen volgen de ontwerppatronen van StUF zoals die horen bij de gebruikte StUF versie.

KI04 Volgen van (inter)nationale standaarden

De door VERA beschreven berichten en schema’s moeten voldoen aan de te volgen StUF versie.

KI05 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. In de koppelvlakdefinities is volgens de StUF methodiek uitgewerkt hoe met het aspect tijd wordt omgegaan.

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 XSD en WSDL

De klassen en hun relaties worden technisch uitgewerkt in XSD’s. Voor het vastleggen van de mogelijke interacties met de webservices bestaan WSDL 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 StUF en aangepast voor het gebruik in VERA. Dit wordt beschreven in de betreffende VERA versie.

3.4 Namespaces en versie

De verwachting is dat de stichting VERA vele producten gaat opleveren. Om op voorhand geen beperkingen op te leggen is er voor gekozen om een opbouw van de namespace te kiezen, die het mogelijk maakt om deelproducten op te leveren, of namespaces te gebruiken die niet StUF gerelateerd zijn. Dus: http://<site van stichting>/<product>/<deelproduct>/<naam van horizontaal sectormodel>/<versienummer>.

De VERA 2.0 XSD’s krijgen de volgende name space: http://www.stichting-vera.nl/StUF/sector/vera/0310

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

Versienummer van StUF waarop de versie is gebaseerd Bijv. 0310.

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

Versienummer van VERA 2.0 was als volgt in de berichten opgenomen: version="031001“.


Uitgangspunten

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

U01 StUF als standaard voor berichtenverkeer

VERA heeft gekozen StUF te hanteren als open standaard op basis van principe P03. De doelstelling van VERA om te komen tot uniformering en standaardisering op het gebied van gegevensuitwisseling komt overeen met de StUF doelstellingen. De StUF standaard (VNG/KING, 2013) is bewezen toepasbaar en wordt al gebruikt voor het koppelvlak met de basisregistraties.

StUF wordt beheerd door het Kwaliteitsinstituut Nederlandse Gemeenten (KING) en standaardiseert de syntax en techniek van berichten. VERA maakt gebruik van deze standaard om de logische gegevensmodellen om te zetten in gestandaardiseerde services en berichten. Alleen het SOAP protocol wordt ondersteund voor uitwisseling van gegevens tussen systemen.

StUF kent een eigen beheerprocedure. Door de keuze voor StUF adopteert VERA tevens het versiebeheer zoals StUF dit definieert. Iedere nieuwe versie van VERA voldoet aan de op dat moment geldende StUF versie.


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

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

VERA bevat een uitwerking die gebruik maakt van StUF (U01). StUF bouwt verder op de open standaarden XML via SOAP. Faciliteiten voor REST/JSON zijn nog geen onderdeel van StUF en daardoor ook niet van VERA.

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

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

U06 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 informatieuitwisseling 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.

U07 Kengetallen sluiten aan bij de VERA klassen

De informatieuitwisseling sluit aan bij de VERA klassen: Er wordt dus geen nieuw klassenmodel 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.




VERA&CORA logo.png