Ga naar inhoud

7.5: Samenstellen berichten

7.5 Samenstellen berichten, versionering en publicatie

7.5.1 Toelichting op het gebruik van afdDefinitionVersion

afdDefinitionVersion wordt gevuld met het versienummer (uit de “Naam schema”) van het VBPUO-JSON-schema.

Het VBPUO-JSON-schema voor de functionele berichten en de VBPUO_Feedback_Message wordt door SIVI onderhouden met behulp van “AFD Online Samenstellen (AOS)” en wordt daarin geadministreerd met de volgende metagegevens:

Metagegeven AOS schema Waardes (voorbeeld)
SIVI community AFD 2.0
Berichtsoort: Protocol PUO Vermogensbeheer
Domein: Algemeen
Naam schema: VBPUO-###.##

Tabel : Metagegevens (AOS) VBPUO-schema

In het (AOS) VBPUO-schema worden de VBPUO-berichtstructuren gedefinieerd als ”functies” bijvoorbeeld de functie: “Bericht_1._Vermogen_(0001a)”. Vanaf release 2027 zijn 10 inhoudelijke berichten en het Feedbackbericht actief; 5 FPR-berichten zijn vervallen (zie §6.4). Per “functie” worden vervolgens 3 JSON-schema’s gegenereerd die op GitHub worden gepubliceerd (“commit”). Deze JSON-schema’s hebben de volgende doelen:

JSON-Schema toegelicht

Doelen nadere omschrijving Voorbeeld filenaam
Berichtstructuur Definiëring van de structuur, verplichte elementen en veldvalidaties, met interne en externe referenties om dataconsistentie en standaardisatie te waarborgen. VBPUO-001.00-Bericht_1._Vermogen_(0001a).json
Codelijsten/tabellen: Definieert de codelijsten (bijvoorbeeld pensioenuitvoerder- en valutacodes) die worden gebruikt als referenties in het JSON-schema voor veldvalidatie. VBPUO-001.00-Bericht_1._Vermogen_(0001a)-afdCodelists.json
Verbandscontroles Definieert de regels voor verbandscontroles in het JSON-schema om de geldigheid en consistentie van gegevensrelaties te waarborgen. VBPUO-001.00-Bericht_1._Vermogen_(0001a)-validationRules.json

Tabel : JSON-Schema's (uit AOS) toegelicht

7.5.1.1 Versienummer / afdDefinitionVersion bij een GitHub release

Het versienummer een AOS-schema moet worden opgenomen in elk te verzenden bericht. Dit nummer is te vinden in de Berichtstructuur als constante onder afdDefinitionVersion.

Onder dit nummer zijn de JSON-Schemas terug te vinden op https://portal.sivi.org/organisationschemas. De berichten die met dit schema worden gemaakt – binnen het schema VBPUO zijn die gedefinieerd als functies – worden gepubliceerd op GitHub.

Bestandsnaam versus afdDefinitionVersion

De bestandsnamen van de JSON-schema's bevatten een versienummer als onderdeel van de naam, bijvoorbeeld VBPUO-001.00-Bericht_1._Vermogen_(0001a).json. Dit versienummer is bevroren op de waarde die gold bij eerste publicatie en wordt bij latere releases niet bijgewerkt.

De reden hiervoor is de koppeling met de OpenAPI Specificatie (OAS). De OAS verwijst naar de JSON-schema's via een directe bestandspad-referentie ($ref):

$ref: 'VBPUO-Bericht_1._Vermogen_(0001a)/VBPUO-001.00-Bericht_1._Vermogen_(0001a).json'

Als het versienummer in de bestandsnaam bij elke release zou worden bijgewerkt, moesten ook alle $ref-verwijzingen in de OAS worden aangepast. Omdat implementerende partijen (PUO's en vermogensbeheerders) hun API-implementaties op de OAS baseren, zou elke bestandsnaamswijziging een aanpassing vereisen in alle geïmplementeerde API's in de sector. Dit is bewust vermeden.

Het gevolg is dat bestandsnaam en inhoud uiteen kunnen lopen: de bestandsnaam vermeldt 001.00 terwijl het veld afdDefinitionVersion binnenin het schema de actuele waarde bevat, zoals 001.02.

Let op: gebruik voor implementatie en validatie altijd de waarde van afdDefinitionVersion — niet het versienummer in de bestandsnaam.

afdDefinitionName volgt de bestandsnaam. Het veld afdDefinitionName heeft in elk schema een vaste waarde: de bestandsnaam zonder .json, dus met 001.00. Voor bericht 1 is dat VBPUO-001.00-Bericht_1._Vermogen_(0001a), voor het feedbackbericht VBPUO_Feedback_Message-001.00-VBPUO_Feedback_Message. Die naam verandert niet bij een nieuwe release. De versie staat alleen in afdDefinitionVersion: 001.05 voor de tien berichten, 001.02 voor het feedbackbericht. Zie GitHub issue #140.

Zie ook: GitHub issue #58

7.5.2 Publicatie op GitHub versienummer en tag

Bij het releasen op GitHub krijgt de release een Naam en een Tag. Alle JSON-schema's en de OAS vallen onder die release/tag. De voorbeeldberichten staan vanaf release 2027 in een eigen map, Voorbeeldberichten, met een submap per release. Daar is main leidend: voorbeelden kunnen tussen twee releases worden verbeterd of aangevuld, zonder nieuwe release van de standaard. Elke wijziging staat in de LEESMIJ van de releasemap. De tag bevat de voorbeelden zoals ze op de releasedatum waren; de actuele voorbeelden staan op main. Voorbeelden zijn niet normatief; bij verschil gelden de JSON-schema's en deze handleiding. Voor release 2027 zijn er voorbeelden voor alle actieve berichten en het feedbackbericht, waaronder de FPR-route met beleggingsportefeuilles in de berichten 2 en 3 en reserves in bericht 1. Ze zijn opgebouwd naar situaties uit de praktijk, met bestaande pensioenuitvoerders uit de codelijst AFDIDP en fictieve bedragen en kenmerken, en valideren tegen de JSON-schema's en de verbandscontroles van §6.3.1 en §6.3.2.

De naam van release 2027 is bijvoorbeeld “Release 2027 (v1.4.0)” met tag v1.4.0 (zie releases). De GitHub-releasenaam en -tagnummer zijn niet terug te vinden in de pay-load van de berichten. Zowel de berichten als de OAS hebben een eigen releasenummer.

7.5.3 JSON Schema-versies

Per bericht worden meerdere JSON-gerelateerde bestanden gepubliceerd: - berichtstructuur; - codelijsten; - validation rules.

Vanaf release 2027 worden deze bestanden gepubliceerd conform JSON Schema Draft 2020-12.

Hierbij geldt: - berichtstructuren gebruiken $defs; - interne referenties gebruiken #/$defs/...; - externe AFD-referenties verwijzen naar het 2020-12-pad; - validation rules blijven inhoudelijk ongewijzigd.