KARWEI 2.7 Webtekstversie

Voorwoord

Voor u ligt versie 2.7 van de KetenArchitectuur Werk en Inkomen (KArWeI). Met deze hernieuwde versie maken we het gebruik van een aantal nieuwe standaarden mogelijk in de SUWI Ketensamenwerking.

Architectuur is en blijft een belangrijk hulpmiddel om de voordelen die ICT in potentie biedt effectief en efficiënt aan te wenden. Daarom zal deze ketenarchitectuur ook de maatstaf zijn voor de beoordeling van voorgenomen ketenveranderingen en de gevolgen daarvan voor de inzet van ICT.

Dit document is versie 2.7 van KArWeI en bevat alleen een hoofdstuk Standaarden. Voor de overige architectuurafspraken verwijzen wij naar versie 2.6. Met versie 2.8, verwacht eind 2026, beschrijven we weer een volledige ketenarchitectuur maar dan in een nieuwe indeling met aanvullende afspraken.

Samenwerken slaagt bij een gezamenlijke context en doel, ondersteund door een set heldere afspraken. Deze ketenarchitectuur beoogt hieraan een bijdrage te leveren.

Utrecht, september 2026

Colofon

Managementsamenvatting

De Ketenarchitectuur Werk en Inkomen (KArWeI) versie 2.7 is de geactualiseerde opvolger van versie 2.6. Aanleiding voor de actualisering is het toestaan van nieuwe standaarden en het meer volgen van nationale standaarden in de SUWI-keten.

Positionering van de ketenarchitectuur

Ketenpartijen volgen de principes van de e-overheid, zoals de eenmalige uitvraag van gegevens, meervoudig gebruik van gegevens, servicegerichte architectuur, één loketgedachte, gebruik van open standaarden en open source software en de toepassing van webrichtlijnen. De NORA beschrijft deze principes en vormt daarmee het ICT-denk- en ontwikkelkader voor de SUWI Ketenarchitectuur. De ketenarchitectuur geeft een concrete invulling aan de algemene principes uit de NORA. Naast NORA stellen de referentiearchitecturen van UWV, de gemeenten (GEMMA), SZW (SODA), de Nederlandse API Strategie en BZK (GDI) een kader voor de Ketenarchitectuur Werk en Inkomen.

De ketenarchitectuur bevat afspraken over wat op SUWI-ketenniveau ingeregeld moet zijn om de uitvoering van wettelijke taken in het SUWI-domein als één samenhangend en betrouwbaar geheel te laten werken.

Disclaimer

Karwei 2.7 vervangt géén bestaande hoofdstukken van Karwei 2.6, maar consolideert de standaarden-gerelateerde inhoud die in Karwei 2.6 verspreid staat over de managementsamenvatting en de hoofdstukken 5, 6 en 7. Definitieve inpassing en redactionele afstemming op de rest van het document volgt in een separate opschonings- en herstructureringsslag als opmaat naar Karwei 2.8. Daarbij zal ook een harmonisatie en ontdubbeling plaatsvinden van afspraken in Karwei en de vernieuwde Suwi-koppelvlakstandaard.

Karwei 2.6 positioneert zich in hoofdstuk 2 ten opzichte van NORA, GEMMA, de UWV-architecturen, de Nederlandse API Strategie, SODA en GDI. Zowel Karwei 2.6 als de nieuwe Suwi-koppelvlakstandaard-inleiding verwijzen al naar de ‘pas toe of leg uit’-lijst, zonder Forum Standaardisatie expliciet als kader te benoemen. Dit hoofdstuk vult dit beeld aan specifiek voor standaarden, en maakt normstelling van Suwi-standaarden binnen de Suwi-keten meer expliciet.

In een volgende versie van Karwei zal een overzicht van algemene (verplichte of aanbevolen) standaarden worden opgenomen, met een toelichting over de toepassing en normstelling over het gebruik van deze standaarden binnen de Suwi keten.

Dit hoofdstuk bevat nog géén roadmap voor standaarden, implementatie en migratie. Voor nu hebben we ons gefocust op het verwijderen of actualiseren van standaarden.

Inleiding

Aanleiding van dit hoofdstuk is de vernieuwde Suwi-Koppelvlakstandaard, die de SuwiML Transactiestandaard opvolgt, REST tot voorkeursprotocol maakt conform de Nederlandse API Strategie, en GraphQL introduceert als nieuw alternatief protocol.

“Voorkeursprotocol”: REST. REST API's sluiten aan op de overheidsbrede ontwikkeling naar gestandaardiseerde, API-gebaseerde gegevensuitwisseling. De Nederlandse API Strategie positioneert API's als een belangrijke bouwsteen voor het veilig, interoperabel en herbruikbaar delen van gegevens. Deze richting is verder geconcretiseerd in de Digikoppeling Koppelvlakstandaard REST API en de Nederlandse REST API Design Rules. Ook de actuele Digikoppeling-roadmap richt zich op verdere doorontwikkeling van het REST API-profiel, onder meer in combinatie met FSC. REST wordt daarom voor nieuwe Suwi-integraties als voorkeursprotocol gehanteerd.

"Deprecated": SuwiML / WUS. SuwiML wordt binnen de Suwi-keten breed toegepast. De onderliggende Digikoppeling Koppelvlakstandaard WUS is echter verouderd en wordt in de praktijk steeds minder toegepast. De voorgenomen uitfasering van WUS betekent dat SuwiML/WUS voor bestaande integraties vooralsnog relevant blijft, maar voor nieuwe integraties niet langer als voorkeurskeuze wordt beschouwd.

“Alternatief protocol”: GraphQL. GraphQL wordt binnen het Suwi-domein onderzocht als aanvullend protocol. Een referentie-implementatie is ontwikkeld om verdergaande dataminimalisatie mogelijk te maken. De actuele Digikoppeling-roadmap 2026–2027 bevat expliciet onderzoek naar uitbreiding van Digikoppeling met GraphQL. GraphQL kan daarmee worden ingezet voor specifieke situaties waarin fijnmazige gegevensselectie en dataminimalisatie zwaar wegen, maar heeft vooralsnog niet dezelfde status als het bestaande Digikoppeling REST API-profiel.

Leeswijzer

Dit hoofdstuk brengt alle bepalingen over standaarden, gegevensuitwisselingsprotocollen en de daarbij horende afspraken samen die in Karwei 2.6 verspreid stonden in verschillende hoofdstukken.

Dit hoofdstuk in Karwei 2.7 vervangt géén bestaande hoofdstukken van Karwei 2.6, maar consolideert de standaarden-gerelateerde inhoud die in Karwei 2.6 verspreid staat over de managementsamenvatting en de hoofdstukken 5, 6 en 7. Definitieve inpassing en redactionele afstemming op de rest van het document volgt in een separate opschonings- en herstructureringsslag als opmaat naar Karwei 2.8. Daarbij zal ook een harmonisatie en ontdubbeling plaatsvinden van afspraken in Karwei en de vernieuwde Suwi-koppelvlakstandaard.

Karwei 2.6 positioneert zich in hoofdstuk 2 ten opzichte van NORA, GEMMA, de UWV-architecturen, de Nederlandse API Strategie, SODA en GDI. Zowel Karwei 2.6 als de nieuwe Suwi-koppelvlakstandaard-inleiding verwijzen al naar de ‘pas toe of leg uit’-lijst, zonder Forum Standaardisatie expliciet als kader te benoemen. Dit hoofdstuk vult dit beeld aan specifiek voor standaarden, en maakt normstelling van Suwi-standaarden binnen de Suwi-keten meer expliciet.

In een volgende versie van Karwei zal een overzicht van algemene (verplichte of aanbevolen) standaarden worden opgenomen, met een toelichting over de toepassing en normstelling over het gebruik van deze standaarden binnen de Suwi keten.

Dit hoofdstuk bevat nog géén roadmap voor standaarden, implementatie en migratie.

Afspraken

Architectuur afspraken over standaarden

Deze afspraken zijn bedoeld als vervanging een aantal standaarden-gerelateerde afspraken die verspreid in Karwei 2.6 en 2.7 staan, en voegt enkele nieuwe afspraken toe die voortkomen uit de duiding van de transportlaag. De oorspronkelijke nummering blijft ter herleidbaarheid vermeld; definitieve hernummering en opschoning vindt plaats in een volgende versie van Karwei.

Basisafspraken binnen de Suwi-koppelvlakstandaard

Naast de bovenstaande architectuurafspraken bevat de Suwi-koppelvlakstandaard uitgangspunten en basisafspraken als onderdeel van de koppelvlakstandaard. Enkele voorbeelden:

• Gegevenssets zijn afgestemd op wettelijke taak en proportionaliteit via Berichten-op-maat. De berichten-op-maat bevatten alleen de elementen waar de afnemer toe gerechtigd is om op te vragen. Hiermee is het een middel om de doelbinding te waarborgen.

• Binnen de Suwi-keten geven we bij voorkeur een sub-OIN of OIN uit op basis van een wettelijke uitvoeringstaak (Doelbinding en autorisatie via OIN/sub-OIN.)

Harmonisatie en ontdubbeling van afspraken in Karwei en de koppelvlakstandaard vindt plaats in een volgende versie van Karwei.

Kaders

De Suwi-keten opereert niet in een vacuüm: standaardisatiekeuzes moeten passen binnen een aantal externe kaders op het gebied van standaarden, van EU-niveau tot sociaal-domeinniveau.

EIRA – European Interoperability Reference Architecture

EU-kader vanuit het ISA²-programma van de Europese Commissie, gebaseerd op het European Interoperability Framework (EIF). Biedt architectuurbouwstenen, gemeenschappelijke terminologie en standaarden voor interoperabele, grensoverschrijdende overheidsdienstverlening.

Forum Standaardisatie

Formele beheerder van de ‘pas toe of leg uit’-lijst en de lijst met aanbevolen standaarden.

NORA – Nederlandse Overheid Referentie Architectuur

Overkoepelend Nederlands architectuurkader. Beheert een algemeen NORA standaardenoverzicht, de standaarden binnen de GDI domeinarchitectuur Gegevensuitwisseling en het overzicht ‘Standaarden in het Federatief Datastelsel’.

FDS – Federatief Datastelsel en GBO – Generieke Bronontsluiting

Nieuw afsprakenstelsel voor domeinoverstijgend gegevens delen tussen overheden, onderdeel van de Interbestuurlijke Datastrategie (IBDS) en opvolger van de visie op het Stelsel van Basisregistraties. Het programma realisatie FDS heeft een eerste lijst met standaarden opgesteld die partijen in eerste instantie moeten toepassen om federatief datadelen mogelijk te maken.

SODA – referentiearchitectuur sociaal domein

Referentiearchitectuur van het Ministerie van SZW voor het sociaal domein, nog in ontwikkeling en niet formeel vastgesteld.

SODA conformeert zich voor standaarden volledig aan bestaande verplichtingskaders, en licht de toepassingsgebieden ervan binnen het SZW domein nader toe.

Suwi standaarden

De Suwi standaarden beschrijven, conform het uitgangspunt in afspraak STD-01, alleen wat aanvullend is op Digikoppeling en andere verplichte standaarden.

Uitwisselingsstandaard SGR/SuwiML

Het Suwi-Gegevensregister (SGR) is de standaard die binnen het Suwi-domein wordt gehanteerd voor het uitwisselen van gegevens tussen de Suwi-partijen.

Op hoofdlijnen bevat het SGR enerzijds een Conceptueel Gegevensmodel (object en gegevensdefinities van met de centrale voorziening uitgewisselde gegevens) en de technische standaarden. Anderzijds bevat het SGR een Berichtenregister. Het Berichtenregister geeft weer ten behoeve van welke wettelijke taak (doelbinding) welke gegevenssoorten (proportionaliteit) door wie (verantwoordelijke) aan wie (verwerker) met de centrale voorziening worden uitgewisseld.

Het Suwi Gegevensregister (SGR) en SuwiML (en opvolger “Suwi-Koppelvlakstandaard”) vormen tezamen de uitwisselingsstandaard SGR/SuwiML.

SuwiML Berichtenstandaard

De SuwiML Berichtenstandaard beschrijft de functionele en technische richtlijnen voor het definiëren van SuwiML berichten en koppelvlakken met betrekking tot de inhoudelijke structuur van de gegevens die moeten worden uitgewisseld. Het beschrijft de opzet en het gebruik van het SuwiML basisschema voor het definiëren van de body van SuwiML berichten. Daarmee biedt dit document een beschrijving voor het samenstellen van SuwiML berichtschema’s alsook toepassingsonafhankelijke richtlijnen voor het realiseren van gegevensuitwisseling tussen de partijen in de Suwi-keten.

Suwi Transactiestandaard 3.1

Voor asynchrone gegevensdeling blijft vooralsnog de Suwi Transactiestandaard 3.1 van kracht.

Suwi Transactiestandaard 4.0

De SuwiML Transactiestandaard is volledig compliant geworden met Digikoppeling (WUS) sinds de introductie van SuwiML Transactiestandaard 4.0, welke van kracht werd in 2020.

De SuwiML Transactiestandaard 4.0 wordt met deze versie van Karwei vervangen door de vernieuwde Suwi-Koppelvlakstandaard.

Suwi-Koppelvlakstandaard

De Suwi-Koppelvlakstandaard is de opvolger van de SuwiML Transactiestandaard 4.0 en is leidend voor alle synchrone koppelvlakken (WUS, REST en GraphQL) tussen organisaties in de Suwi keten. De Suwi-Koppelvlakstandaard is compliant met Digikoppeling.

Naast een set basisafspraken die voor elk koppelvlak gelden, onderscheidt ze hierbij een aantal protocol-specifieke uitwerkingen die hieronder worden toegelicht.

Suwi-Koppelvlakstandaard SuwiML: Suwi-Koppelvlakstandaard SuwiML beschrijft de bepalingen die van toepassing zijn op SuwiML webservices, d.w.z. synchrone webservices binnen de Suwi-keten die gebruik maken van XML. Suwi-Koppelvlakstandaard “SuwiML” sluit aan op het Digikoppeling WUS-profiel.

Geïnspireerd op de structuur van Koppelvlakspecificaties die is ingezet door Logius, zijn de bepalingen uit de voormalige Suwi berichtenstandaard en SuwiML transactiestandaard 4.0 opgenomen in de “Suwi-Koppelvlakstandaard SuwiML” en vormen nu één geïntegreerd afsprakenstelsel voor SuwiML.

Suwi-Koppelvlakstandaard REST API: Suwi-Koppelvlakstandaard REST API beschrijft de bepalingen die van toepassing zijn op synchroon berichtenverkeer via REST API’s binnen de Suwi-keten. Suwi-Koppelvlakstandaard “REST API” sluit aan op het Digikoppeling REST API-profiel mét FSC en de NLgov REST API Design Rules (ADR) en Logboek Data Verwerking (LDV).

Suwi-Koppelvlakstandaard GraphQL: Suwi-Koppelvlakstandaard GraphQL beschrijft de bepalingen die van toepassing zijn op synchroon berichtenverkeer via GraphQL API’s binnen de Suwi-keten.

Er bestaat (nog) geen officiële Digikoppeling-GraphQL standaard; de Suwi-Koppelvlakstandaard GraphQL loopt hierin voorop. Suwi-Koppelvlakstandaard GraphQL is gebaseerd op het Digikoppeling REST API-profiel mét FSC en Logboek Data Verwerking (LDV), en is inhoudelijk geïnspireerd op de REST API Design Rules van de Nederlandse API Strategie.

Standaarden catalogus

Nadere kenmerken van Suwi-standaarden

*1) REST/JSON ondersteunt geen gestandaardiseerde querytaal zoals GraphQL. Queries kunnen wel worden ondersteund middels een URL-conventie die ontworpen en geïmplementeerd moet worden. Bijvoorbeeld: "GET /personen/123456789?fields=naam".

Suwi normenkader voor standaarden

Toelichting op normenkader

Deprecated: SuwiML / WUS. SuwiML wordt binnen de Suwi-keten breed toegepast. De onderliggende Digikoppeling Koppelvlakstandaard WUS is echter verouderd en wordt in de praktijk steeds minder toegepast. De voorgenomen uitfasering van WUS betekent dat SuwiML/WUS voor bestaande integraties vooralsnog relevant blijft, maar voor nieuwe integraties niet langer als voorkeurskeuze wordt beschouwd.

Voorkeursprotocol: REST. REST API's sluiten aan op de overheidsbrede ontwikkeling naar gestandaardiseerde, API-gebaseerde gegevensuitwisseling. De Nederlandse API Strategie positioneert API's als een belangrijke bouwsteen voor het veilig, interoperabel en herbruikbaar delen van gegevens. Deze richting is verder geconcretiseerd in de Digikoppeling Koppelvlakstandaard REST API en de Nederlandse REST API Design Rules. Ook de actuele Digikoppeling-roadmap richt zich op verdere doorontwikkeling van het REST API-profiel, onder meer in combinatie met FSC. REST wordt daarom voor nieuwe Suwi-integraties als voorkeursprotocol gehanteerd.

Alternatief protocol: GraphQL. GraphQL kan worden ingezet voor specifieke situaties waarin fijnmazige gegevensselectie en dataminimalisatie zwaar wegen, maar heeft vooralsnog niet dezelfde status als het bestaande Digikoppeling REST API-profiel.

Referenties (aanvullend op Karwei 2.6 bronnenlijst)