5 april _iv3_indeling_JSON.docx

Transcriptie

1 Verplichte indeling Elk iv3-json bestand bestaat uit 3 verplichte elementen met binnen elk element een aantal verplichte elementen en/of sleutels: (alle elementen en sleutels zijn met kleine letters en in enkelvoud). Let op, elk van onderstaande elementen moet in elke levering voorkomen, behalve de balans_xxx elementen (in groen), die zijn voor een begrotingslevering optioneel maar voor kwartalen en jaar verplicht. De dikgedrukte elementen geven verzamelingen weer. Een verzameling kan andere verzamelingen bevatten of een set sleutels waaraan telkens een waarde moet worden gegeven. metadata o overheidslaag o overheidsnummer o overheidsnaam o boekjaar o periode o status o datum contact o naam o o telefoon data o lasten taakveld o baten taakveld o balans_lasten o balans_baten o balans_standen balansdatum Naast de verplichte elementen en verplichte sleutels staat het elke instantie vrij om extra informatie toe te voegen. Indien de informatie wordt uitgebreid, kan het zijn dat er een splitsing van records plaatsvindt, waardoor de combinatie van bijvoorbeeld lasten, taakveld en categorie vaker voorkomt. Dit is geen enkel probleem. In de bijlage zijn voorbeelden te vinden van zulke splitsingen.

2 Elke sleutel krijgt steeds één waarde. Bij het bepalen van de waarde zijn er de volgend mogelijkheden: A. er dient gekozen te worden uit een beperkt aantal mogelijke waarden die in principe nooit wijzigen (overheidslaag is Provincie, Gemeente of GR) B. er dient gekozen te worden uit een lijst met mogelijke waarden, maar die kunnen per jaar en per overheidslaag verschillen (taakvelden of balanscodes) C. invulling moet aan een bepaald format voldoen ( adres) D. de invulling is volkomen vrij (contactpersoon naam) Met behulp van al deze informatie kan een iv3-json bestand opgebouwd worden. Een JSON bestand is platte tekst. Belangrijk is het gebruik van accolades en aanhalingstekens. Elke sleutel wordt altijd gevolgd door een waarde en een element kan een verzameling van sleutels en bijbehorende waarden bevatten, gescheiden door komma s. Een verzameling wordt telkens omsloten door accolades. Bijvoorbeeld: {"metadata":{ "overheidslaag" : "Gemeente", "overheidsnummer" : "1234", "overheidsnaam" : "StadsDorp", "boekjaar": "2018", "periode": "1", "status" : "Realisatie" }, In het geval van de bedragen, bestaat de levering uit veel verzamelingen die er telkens hetzelfde uitzien. Dit noemen we een lijst. Een lijst wordt telkens omsloten door vierkante haken. Zie hieronder bijvoorbeeld de lijst van de balans_baten: In de volgende pagina s vindt u informatie over de correcte vulling van een JSON bestand en de validatie van dat bestand.

3 JSON-Schema Voor het valideren van JSON bestanden bestaat het zogenaamde JSON-schema. Hierin kunnen elementen en sleutels worden beschreven en gelimiteerd, verplichtingen en beperkingen worden vastgelegd. Feitelijk is dit de beschrijving van de grammaticaregels van JSON bestanden. Er bestaat standaard programmatuur om een JSON bestand te valideren met een JSON-schema. Jaarlijks kunnen er wijzigingen zijn in taakvelden, categorieën en balanscodes, alsmede in de plausibiliteitscontroles. Bovendien kunnen de codes en controles afwijken per overheidslaag. Voor deze indelingen worden definitie bestanden klaar gezet. In het JSON schema zijn de volgende keuze waarden opgenomen (in het zwart de exacte naam van de sleutel, in het groen de mogelijke vulling): metadata o overheidslaag keuze uit: Provincie Gemeente GR o overheidsnummer tekst, bestaande uit 4 cijfers o overheidsnaam vrije invulling o boekjaar jaartal tussen 2018 en 2030 o periode keuze uit 0 (code voor Begroting) 1 (code voor 1 e kwartaal) 2 (code voor 2 e kwartaal) 3 (code voor 3 e kwartaal) 4 (code voor 4 e kwartaal) 5 (code voor jaarrekening) o status keuze uit: Realisatie Begroting Bijgestelde begroting o datum Datum/tijd van aanmaak document contact o naam vrije invulling o vrije invulling, volgens indeling o telefoon vrije invulling, uitsluitend cijfers data Van alle sleutels hieronder is in het schema uitsluitend vastgelegd dat ze voor moeten komen, de codelijsten waaruit gekozen kan worden staan in de definitie-bestanden. Bedragen zijn valuta-waarden (mag met decimalen, met als decimaalteken een punt), de overige sleutels krijgen strings. Elk van de verzamelingen mag naast de verplichte sleutels worden

4 uitgebreid met extra sleutels en waarden. Hier kan dus meer detail informatie worden toegevoegd door bijvoorbeeld grootboekomschrijvingen toe te voegen. o lasten taakveld o baten taakveld o balans_lasten o balans_baten o balans_standen balansdatum

5 Definitie bestand De definitie bestanden zijn ook volgens het JSON-format ingedeeld. Deze bestanden bevatten de informatie die per jaar en per overheidslaag verschillend is, alsmede informatie over indeling van de verwachte records. In de naamgeving van de definitie bestanden is duidelijk de overheidslaag en het boekjaar terug te vinden. De definitie bestanden kennen de volgende indeling: Metadata o boekjaar o periode o overheidslaag codelijsten o taakveld o balanscode o balansdatum o categorie_lasten o categorie_baten dimensies o lasten o baten o balans_lasten o balans_baten o balans_standen controlelijst grijze_cellen o lasten o baten o balans_lasten o balans_baten Codelijsten De codelijsten komen overeen met de lijsten in het BBV, maar zijn uitgebreid met een hiërarchie. taakveld In dit voorbeeld ziet u een stukje van het element taakveld. Het element taakveld bestaat uit een lijst van codes op hoofdniveau (in dit voorbeeld de codes 0. en 1. Met bijbehorende omschrijving). Elke code op hoofdniveau bevat weer een lijst met (sub) codes (bijvoorbeeld 0.1 en 1.2). Door deze hiërarchie is het mogelijk om sub totalen en totalen af te leiden.

6 Alle records in de levering die als taakveld code 1.1 en 1.2 hebben, worden opgeteld tot een record met de taakveldcode 1. Zo worden de hoofdtaakvelden berekend. Vervolgens worden alle hoofdtaakvelden opgeteld tot het Totaal taakveld. Deze omschrijving wordt gebruikt door de plausibiliteitscontroles, die verderop in dit document beschreven worden. Het woord Totaal wordt door de programmatuur tijdens het inlezen toegevoegd aan de het element taakveld. In de levering verwachten we uitsluitend records met daarin de subcodes. Dat komt overeen met de huidige leveringen in Excel, daar worden alle subcodes ingevuld en de totaalregels berekend. Balansdatum De balansdatums zijn de kolomkoppen van de balans, de beginstand en de eindstand. Om verwarring te voorkomen is dezelfde terminologie gebruikt als in het Excelsjabloon. Dus 1 januari en Ultimo. Indien er zou zijn gekozen voor Primo, zou de indruk kunnen ontstaan dat per kwartaal de stand van het begin van DAT kwartaal moet worden ingevuld, en dat is uiteraard niet de bedoeling. Categorie Bij de categorieën worden enkele nieuwe termen geïntroduceerd. In het Excelsjabloon is geen sprake van een onderscheid van hoofdcodes en subcodes, maar in de plausibiliteitscontroles wordt wél gebruik gemaakt van een opdeling van bij elkaar horende categorieën. Om subtotalen te kunnen realiseren, is ook voor de categorieën een hiërarchie geïntroduceerd. Er is onderscheid tussen: - code: Lopende Rekening (categorieën 1.1 t/m 5.1) - code: Financiele Rekening (categorie 6.1) - code: Interne verrekeningen (categorieën 7.1 t/m 7.5) dat ziet er als volgt uit: Ten bate van de leesbaarheid zijn er enkele coderegels weggelaten in het plaatje. Ook hier verwachten we uitsluitend records op sub-code niveau, zodat de programmatuur zelf de totalen kan berekenen. In het definitie-bestand is onderscheid tussen categorie_lasten en categorie_baten, net als in de Excel-tabbladen. In de records van het JSON bestand wordt echter in beide gevallen de sleutel categorie gebruikt. De ingevulde categorie wordt uiteraard wel gevalideerd met de juiste codelijst.

7 Dimensies In de dimensies is vastgelegd welke combinatie van codelijsten daar verwacht wordt en welke naam de sleutel in de data-levering moet krijgen. Bijvoorbeeld: In dit voorbeeld ziet u dat de tabel lasten wordt samengesteld door de combinatie van de codelijsten categorie_lasten en taakveld (die als sleutelnaam categorie resp. taakveld moeten krijgen). In de uiteindelijke levering ziet dit er als volgt uit: Een voorbeeld van een definitie bestand is 05_iv3_definities_Gemeente_2018_voorbeeld.JSON.pdf. Omdat zo n bestand vrij groot kan worden, is in dit bestand volstaan met enkele records per soort. Controles De controles maken veelal gebruik van de eerder genoemde totalen en subtotalen. De methodiek is gebaseerd op regels met een volgnummer die achter elkaar worden uitgevoerd. U moet zich voorstellen dat in het geheugen van de computer diverse overzichten worden opgebouwd die erg lijken op de tabbladen van Excel. Daar is elke identificeerbaar met een regelnummer en een kolomletter. In onze computer is elk bedrag identificeerbaar door de combinatie van rekeningsoort (lasten, baten, balans_lasten, enz.), taakveld en categorie. (bij balans natuurlijk balanscode in plaats van taakveld). De combinatie lasten, taakveld 0., categorie Lopende Rekening verwijst dus naar een totaal van hoofdtaakveld 0. En dan de som van categorieën 1.1 tm 5.1. Elke regel van een controle bevat een variabelenaam waarvan de inhoud vervolgens wordt beschreven. Dit kan door een verwijzing naar een combinatie zoals hiervoor is beschreven, óf de uitkomst van een berekening waarbij eerder gevulde variabelen kunnen worden gebruikt. Voorbeeld 1: In het Excel-sjabloon, het eerste veld van Toets1, staat deze formule: SOM('5.Verdelingsmatrix lasten'!$c$163:$ae$163) dat is de som van de totaalregel onderaan het tabblad lasten van de categorieën 1 tm 5. Feitelijk bestaat deze telling uit 2 delen, het totaal van de taakvelden, plus het totaal van de balansmutaties. Omdat die in de JSON indeling in 2 aparte onderdelen zijn opgenomen, moet de formule hier in 3 delen worden weergegeven: 1 e deel:

8 Hier wordt een nieuwe variabele geïntroduceerd aan het systeem: Totaal_lasten_taakv_LR, uitsluitend ten bate van deze toets. Het bedrag moet worden gevonden in de tabel lasten, van de taakvelden de regel met als code Totaal taakveld, hetgeen dus het totaal van alle taakveld codes is. En dan de kolom met de code Lopende Rekening, hetgeen dus het subtotaal betreft van de categorieën 1 tm 5. 2 e deel: Hier wordt wederom een nieuwe variabele geïntroduceerd: Totaal_lasten_balans_LR. De methodiek is hetzelfde, maar nu niet van lasten, maar van de tabel balans_lasten. 3 e deel: Weer een nieuwe variabele: Totaal_lasten_LR, maar nu is er geen verwijzing naar een tabel, maar de aankondiging dat er een formule gebruikt wordt. De formule is Totaal_lasten_taakv_LR + Totaal_lasten_balans_LR. Hier worden de 2 variabelen van de voorgaande regels gebruikt om de nieuwe waarde samen te stellen. De variabele Totaal_lasten_LR bevat nu hetzelfde bedrag als de originele formule van Excel. Deze zelfde methodiek is gebruikt om de volgende totalen te bepalen. Uiteindelijk komen de volgende drie formules aan bod: Nr 15 is de formule om het Absolute verschil van 2 saldi te bepalen, Lopende Rekening en Financiële rekening Nr16 is een berekening met een deling erin En Nr 17 is de uiteindelijke uitkomst van de toets. Dit resultaat kan Waar of Onwaar zijn, waarbij Waar resulteert in de waardering voldoende en Onwaar in onvoldoende. Alle controles zullen deze vorm krijgen, zodat ze ook voor andere softwarebouwers goed implementeerbaar zijn.

9