7.5: Samenstellen berichten
7.5 Samenstellen berichten, versionering en publicatie
7.5.1 Toelichting op het gebruik van “afdDefintionVersion”
“afdDefintionVersion” 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 berichten uit het FPR gelaagde ordermodel 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.
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-s, voorbeeldberichten en de OAS vallen onder die release/tag.
De naam van de juli release 2024 was bijvoorbeeld “2024_Juli” met tag v1.1.0. 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.