Forumadvies versiewijziging OAS

Vergadering:	Forum Standaardisatie 17 juni 2026
Agendapunt:	2B
Documentnummer:	FS-20260617-02B
Aan:	Forum Standaardisatie
Van:	Stuurgroep Open Standaarden
Datum:	2 juni 2026
Bijlagen:	Intakeadvies OAS versie 3.1 Expertadvies OAS versie 3.1 Verslag reactie(s) internetconsultatie OAS versie 3.1
Rechten	CC0 publieke domein verklaring
Download	Forumadvies versiewijziging OAS (PDF)

Advies

Het Forum Standaardisatie adviseert het OBDO om:

1. OpenAPI Specification (OAS) in de nieuwe versie (3.1) te blijven verplichten aan de overheid (‘Pas toe of leg uit’) via plaatsing op de ‘Pas toe of leg uit’-lijst van het Forum Standaardisatie .
2. Het predicaat ‘Uitstekend beheer’ voor Nederlandse intermediair (Erkend Nederlands Intermediair) voor nu niet toe te kennen aan het Kennisplatform API’s.

Het opgestelde functioneel toepassingsgebied voor OAS 3.1 op de ‘Pas toe of leg uit’-lijst is ongewijzigd ten opzichte van OAS versie 3.0 en als volgt omschreven:

OAS moet worden toegepast op het beschrijven/specificeren van een REST API.

Het Forum Standaardisatie adviseert om de versie van OAS te actualiseren op de ‘Pas toe of leg uit’-lijst vanuit het belang dat OAS wordt gebruikt in andere standaarden van Logius, waaronder REST API Design Rules en Digikoppeling (in het bijzonder koppelvlakspecificatie REST-API). De huidige versie 3.0 op de ‘Pas toe of leg uit’-lijst is niet langer de gangbare versie. OAS is een internationale standaard met een internationale beheerorganisatie (OpenAPI Initiative).

Kennisplatform API’s heeft het verzoek ingediend om in aanmerking te komen voor het predicaat ‘Uitstekend beheer’ voor Nederlandse intermediair (Erkend Nederlands Intermediair) voor de registratie OAS. Met dat predicaat hoeven toekomstige versies van OAS in principe niet opnieuw te worden getoetst door het Forum Standaardisatie voor het toekennen van de status ‘Pas toe of leg uit’. De toetsingsprocedure wijst uit dat OAS 3.1 niet voldoet aan alle gestelde eisen binnen het criterium ‘Open standaardisatieproces’, zodanig dat aan Kennisplatform API’s het predicaat ‘Uitstekend beheer’ voor Erkend Nederlands intermediair kan worden toegekend. Er wordt nog niet voldaan aan de structurele financieringseisen.

Er is sprake van breed draagvlak voor het gebruik van OAS 3.1. Meerdere leveranciers bieden ondersteuning voor de standaard. Tegelijk moet de standaard actiever worden gepromoot en de implementatie beter worden ondersteund. Na publicatie van een nieuwe OAS-versie is een duidelijke aankondiging met toelichting essentieel om adoptie te stimuleren.

In de rest van dit document wordt dit advies nader onderbouwd. Hoofdstuk 2 geeft een korte uitleg van het nut en belang van de standaard. Hoofdstuk 3 beschrijft het proces waarmee dit advies tot stand kwam, alsmede de vervolgstappen. Hoofdstuk 4 beschrijft de resultaten van de toetsing van de standaard op de inhoudelijke hoofdcriteria. Tot slot geeft hoofdstuk 5 aanvullende adviezen om de adoptie van de standaard te stimuleren.

Korte beschrijving van de standaard

Over de standaard

Een OpenAPI Specification (OAS) beschrijft de eigenschappen van de data die een REST API als input accepteert en als output teruggeeft en welke functionaliteit de API biedt (bijvoorbeeld HTTP methoden als GET, PUT, POST, PATCH, DELETE, etc.). OAS specificeert alleen welke attributen de API verwerkt en hun datatypen, en niet welke implementatie er achter de API schuilgaat. OAS is dus een beschrijvende taal en heeft geen binding met specifieke programmeertalen. Daarnaast beschrijft OAS de security vereisten om toegang te krijgen tot de implementatie van de API. Versie 3.0 van OAS is opgenomen op de ‘Pas toe of leg uit’-lijst.

Een API (Application Programming Interface) is een veel toegepaste en essentiële technologie om moderne applicaties (en databronnen) snel en effectief met elkaar te verbinden en eenvoudig informatie uit te wisselen. REST (representational state transfer) is een techniek die veel wordt gebruikt om de bereikbaarheid van API's via het internet te structureren en implementeren.

Versie 3.1 van de standaard bevat breaking changes ten opzichte van versie 3.0. Deze breaking changes zorgen ervoor dat betere en meer soorten code generatie mogelijk worden, maar is daardoor niet backward compatible met de vorige versie. Zoals aangegeven op de website van de specificatie van de standaard is de migratie van JSON Schema Draft 5 naar JSON Schema Draft 12 de basis van de breaking changes. Alle tooling die voor JSON Schema bestaat kan direct worden gebruikt in combinatie met API-designs. Hierdoor kunnen JSON Schema’s federatief worden hergebruikt. Voor meer informatie over de voordelen van OAS 3.1: zie de blog op developer.overheid.nl.

De belangrijkste voordelen van OAS 3.1:

• De compliancy met JSON Schema is verbeterd;
• De eenduidigheid in de API-security bij toepassing van mutual TLS is verbeterd;
• De beschrijving van webhooks is verbeterd;
• Verduidelijking van begrippen, toelichtingen en voorbeelden zijn verbeterd.

Waarom is deze versie belangrijk?

OAS 3.1 draagt bij aan een betere gegevensuitwisseling tussen diverse partijen en betere toegankelijkheid van gegevens doordat OAS REST API’s toegankelijker maakt door deze op een gestandaardiseerde manier te beschrijven. Een stabiele en eenduidige wijze van beschrijven van REST API’s maakt het eenvoudiger om een API te documenteren. Dit bevordert het gebruik van API’s.

OAS 3.1 vormt het fundament voor het beschrijven van API-functionaliteit, beveiliging en toegankelijkheid, wat bijdraagt aan interoperabiliteit en begrijpelijkheid van overheids API's. OAS 3.1 zorgt voor een grotere toegankelijkheid van de REST API’s door ze op een gestandaardiseerde manier te beschrijven. Een stabiele en eenduidige wijze maakt het eenvoudiger om een API te beschrijven en te gebruiken en daarmee gegevensuitwisseling tussen diverse partijen eenvoudiger en toegankelijker vorm te geven, terwijl hergebruik en standaardisatie zorgen voor lagere kosten. Migratie vanaf OAS 3.0 is eenvoudig en kan grotendeels worden geautomatiseerd. OAS 3.1 vormt daarmee een belangrijke stap vooruit voor overheidsorganisaties die met REST API’s werken.

REST API’s worden in de praktijk op verschillende manieren gestructureerd en beschreven. Daardoor moeten softwareontwikkelaars de structuur van een REST API eerst verkennen en doorgronden voor ze deze kunnen gebruiken. Het gebruik van REST API’s zonder standaard beschrijvingswijze is daardoor minder efficiënt dan wanneer er een standaard zoals OAS 3.1 wordt gebruikt.

Betrokkenen en proces

Gevolgde procedure

Logius (de indiener) heeft OAS in de nieuwe versie (3.1) op 10 augustus 2022 aangemeld voor plaatsing op de ‘Pas toe of leg uit’-lijst.

De toenmalige procedurebegeleider heeft op 20 september 2022 een intakegesprek gevoerd met de indiener, in aanwezigheid van Bureau Forum Standaardisatie. In dit gesprek is onderzocht of OAS in de nieuwe versie (3.1) voldoet aan de criteria om in procedure te worden genomen. De resultaten van het onderzoek zijn vastgelegd in het intakeadvies.

Op basis van het intakeadvies heeft het Forum Standaardisatie op 7 december 2022 besloten de standaard in procedure te nemen. Vervolgens heeft de procedurebegeleider in overleg met de indiener en Bureau Forum Standaardisatie een expertgroep samengesteld en een voorzitter aangesteld om de standaard te toetsen.

De leden van de expertgroep zijn op 5 april 2023 bijeengekomen om de standaard te toetsen aan de criteria en geïdentificeerde aandachtspunten te bespreken. De experts kwamen tot de conclusie dat het nog te vroeg was OAS in de nieuwe versie (3.1) te verplichten, waarna de toetsingsprocedure werd gepauzeerd. De experts adviseerden de procedure voort te zetten zodra OAS voldoende voortgang heeft geboekt op de geconstateerde aandachtspunten. Omdat de expertsessie voortijdig werd gestopt, zijn de resultaten niet vastgesteld en gepubliceerd in een expertadvies.

Op 12 juni 2025 heeft de indiener aangegeven dat de geconstateerde aandachtspunten zijn opgepakt en dat de procedure kan worden voortgezet. Daarnaast heeft Forum Standaardisatie geconcludeerd dat er voldoende voortgang is geboekt op de genoemde aandachtspunten. Daarom is besloten de procedure voort te zetten met OAS in de nieuwe versie (3.1) voor plaatsing op de ‘Pas toe of leg uit’-lijst. Tijdens de voortzetting van de procedure is op 19 september 2025 versie 3.1.2 beschikbaar gekomen. Dit betreft een patchversie waarin geen wijzigingen zijn doorgevoerd in de requirements ten opzichte van versie 3.1.0, maar wel verduidelijkingen en verbeteringen zijn aangebracht in definities, toelichtingen en voorbeelden. Aangezien dit een beperkte versiewijziging betreft, is de procedure voortgezet zoals die oorspronkelijk met versie 3.1 is gestart.

Naar aanleiding hiervan is op 26 januari 2026 opnieuw een expertbijeenkomst georganiseerd. De uitkomst van dit expertonderzoek is vastgelegd in het expertadvies.

Het Forum Standaardisatie publiceerde dit expertadvies ter openbare consultatie via de website van Internetconsultatie van 24 maart 2026 tot 21 april 2026. In de openbare consultatie is één openbare reactie en één niet-openbare reactie ontvangen. De reacties zijn aansluitend voorgelegd aan de indiener van de standaard.

Dit Forumadvies is opgesteld op basis van het expertadvies, reacties uit de openbare consultatie en inzichten van de leden van het Forum Standaardisatie. Indien het Forum Standaardisatie instemt met dit advies, wordt het aan het Overheidsbrede Beleidsoverleg Digitale Overheid (OBDO) ter besluitvorming voorgelegd.

Resultaat van het expertonderzoek

De experts die betrokken waren bij het expertonderzoek adviseren om OAS in de nieuwe versie (3.1) te blijven verplichten aan de overheid (‘Pas toe of leg uit’), voor toepassing bij het beschrijven/specificeren van een REST API.

Daarnaast adviseren de experts het Kennisplatform API’s om na publicatie van een nieuwe versie van OAS een heldere aankondiging over en toelichting op de nieuwe versie van de standaard te ontsluiten om de adoptie te vergroten. Verder adviseren de experts het Forum Standaardisatie om, wanneer de AsyncAPI-standaard wordt aangemeld voor opname op de ‘Pas toe of leg uit’-lijst of de lijst met aanbevolen standaarden, te onderzoeken of een aanvullend profiel voor AsyncAPI nodig is om OAS 3.1 en AsyncAPI goed op elkaar te laten aansluiten. Ook adviseren de experts aan het ministerie van Binnenlandse Zaken om de financiering voor het onder de aandacht brengen van de standaard en het ondersteunen van de implementatie daarvan voor minimaal drie jaar te garanderen, zodat een organisatie de rol van Nederlandse intermediair formeel kan vervullen. Kennisplatform API’s is in beeld om deze rol te vervullen. Ook Logius wordt gezien als een mogelijke partij hierin. Indien de financiering in 2026 rondkomt en de opdrachtgever (BZK) hiermee instemt, adviseren de experts het Kennisplatform API’s binnen één jaar de de facto rol vast te leggen, de gemaakte afspraken te documenteren en deze beschikbaar te stellen, zodat deze voor iedereen inzichtelijk en toegankelijk zijn. Verder adviseren de experts het Forum Standaardisatie om bij de aanmelding van een nieuwe versie van OAS de formulering van het functioneel toepassingsgebied te heroverwegen en te onderzoeken of het nodig is de scope duidelijker af te bakenen (bijvoorbeeld alleen bij resource-based HTTP API’s). Dit voorkomt interpretatieverschillen, vergemakkelijkt consistente toepassing van de standaard en sluit aan bij de laatste API-ontwikkelingen.

Als laatste adviseren de experts het Forum Standaardisatie te reflecteren op de rol van een Erkend Nederlands Intermediair en te beoordelen of de extra formele processen en financiering in verhouding staan tot de te verwachten resultaten. Hierbij wordt benadrukt dat een sterkere focus op de intermediair als centrale plek voor kennisdeling en implementatieondersteuning als waardevoller kan worden gezien.

Resultaat van de openbare consultatie

In de openbare consultatie is één openbare reactie en één niet-openbare reactie ontvangen. De volledige openbare reactie is in het consultatieverslag bijgevoegd. De samengevatte reacties van beide respondenten, evenals de reactie van indiener Logius daarop, zijn in de volgende paragrafen opgenomen.

Openbare reactie

Reactie van W. Pannebakker, 24 maart, Amsterdam

De openbare reactie is afkomstig van W. Pannebakker, Amsterdam, 24 maart 2026.

De respondent stelt dat de integratie van JSON Schema Draft 2020-12 in OpenAPI Specification (OAS) 3.1 de historische divergentie tussen OAS en JSON Schema oplost. Volgens de respondent maakt deze volledige compatibiliteit het mogelijk om datamodellen federatief te hergebruiken over verschillende domeinen heen, zonder handmatige vertaalslagen. De respondent licht toe dat waar versie 3.0 nog een afwijkende subset van JSON Schema hanteerde, versie 3.1 een uniforme datadefinitie mogelijk maakt. Dit draagt volgens de respondent bij aan het verminderen van complexiteit bij het ontwikkelen van ketenoverstijgende diensten en voorkomt isolatie ten opzichte van de internationale standaard voor data-interoperabiliteit. Daarnaast geeft de respondent aan dat OAS 3.1 de efficiëntie in softwareontwikkeling verhoogt door de precisie van automatische codegeneratie voor zowel API-documentatie als client libraries te verbeteren.

Geconstateerd is dat de reactie van Amsterdam niet volledig is ingediend. Er is contact opgenomen met respondent, maar er is geen reactie tijdig ontvangen.

Reactie van indiener Logius op W. Pannebakker

Indiener Logius onderschrijft de reactie van W. Pannebakker en geeft aan dat deze reactie goed is verwoord.

Niet-openbare reactie

Reactie van Anoniem

De respondent stelt dat de nieuwe versie wordt gezien als logisch gevolg van de behoefte aan interoperabiliteit en is nodig voor goede uitwisseling in de keten. Daarnaast geeft de respondent aan dat het gebruik van de gangbare versie bijdraagt aan eenvoudigere gegevensuitwisseling en federatief hergebruik. De samenstelling van de expertgroep wordt niet representatief geacht voor een areaal- of gebiedsbeheerder. Ten aanzien van het criterium ‘Toegevoegde waarde’ onderschrijft de respondent de hoofdlijn, maar plaatst een kanttekening bij de veronderstelling dat implementatiekosten laag zijn. Volgens de respondent vereist een wijziging van een bestaande OAS 3.0-publicatie een aanpassingsproces en is het voor grotere organisaties niet eenvoudig te bepalen welke API’s worden geraakt. Ten aanzien van backward compatibility stelt de respondent dat het ontbreken daarvan onvermijdelijk is om conform de onderliggende standaard te blijven. Wel is onvoldoende duidelijk welke gevolgen optreden wanneer een API-beschrijving van een eerdere versie niet correct kan worden ontsloten. Tot slot wordt gesteld dat opname op de lijst de adoptie van de standaard bevordert.

Reactie van indiener Logius op Anoniem

Indiener Logius geeft aan wat betreft de opmerking dat de samenstelling van de expertgroep niet representatief zou zijn voor een areaal- of gebiedsbeheerder, dat de standaard niet specifiek gericht is op areaal- of gebiedsbeheerder. Wel is vanuit de betrokkenheid van Geonovum en het Kadaster op geo-gebied in algemene zin rekening gehouden met het geo-domein. Wat betreft de opmerking over backward compatibility en de onduidelijkheid over mogelijke gevolgen wanneer een API-beschrijving van een voorgaande versie niet correct kan worden ontsloten, geeft indiener Logius aan dat een OAS/API-beschrijving altijd slechts aan één versie van de standaard kan voldoen.

Toetsing op inhoudelijke criteria

Het Forum Standaardisatie hanteert vier inhoudelijke hoofdcriteria om te toetsen of een standaard in aanmerking komt voor verplichten (‘Pas toe of leg uit’) of aanbevelen aan de overheid .

1. Heeft de standaard toegevoegde waarde?
2. Zijn de standaard en het standaardisatieproces voldoende open?
3. Heeft de standaard voldoende draagvlak?
4. Is opname op de lijst een passend middel om de adoptie te bevorderen?

Ieder van deze hoofdcriteria heeft deelcriteria die staan beschreven op de website van het Forum Standaardisatie. Dit hoofdstuk beschrijft per criterium het resultaat van de toetsing.

Toegevoegde waarde

De toetsingsprocedure wijst uit dat OAS 3.1 voldoet aan het criterium ‘Toegevoegde waarde’.

Het opgestelde functioneel toepassingsgebied voor OAS 3.1 op de ‘Pas toe of leg uit’-lijst is ongewijzigd ten opzichte van OAS versie 3.0 en is als volgt omschreven:

OAS moet worden toegepast op het beschrijven/specificeren van een REST API.

OAS 3.1 is een internationale standaard en wordt beheerd door de OpenAPI Initiative (OAI), onderdeel van de Linux Foundation. De nieuwe versie van de standaard sluit beter aan bij Digikoppeling, waarin ook mutual TLS is vereist. Daarnaast is deze standaard complementair aan vele andere standaarden omdat het gaat over de specificatie van de API. Andere standaarden zoals bijvoorbeeld TLS, HTTP, Digikoppeling en Geo-standaarden gaan met name over de operationele werking van verbindingen en niet zozeer over het ontwerp of de specificatie van de interface. Voor REST API Design Rules is het mogelijk om herbruikbare schema's te definiëren, zodat automatisch aan de design regels wordt voldaan.

OAS 3.1 heeft meerwaarde ten opzichte van OAS 3.0. De kosten van implementatie zijn minimaal en een bestaande OAS 3.0-publicatie is bij een release eenvoudig geschikt te maken als OAS 3.1-publicatie. Voor een nadere toelichting zie het blog over OAS 3.1-migratie op developer.overheid.nl. Daarnaast is in OAS 3.1 Webhooks functionaliteit toegevoegd en is Mutual TLS opgenomen. Ook zijn er diverse technische verbeteringen aangebracht, zoals volledige compatibiliteit met JSON Schema. De migratie naar het nieuwe JSON Schema zorgt echter wel voor breaking changes. Met de opname van webhooks functionaliteit in versie 3.1 wordt het mogelijk om de beschrijving van API’s te voorzien van een signaleringsfunctie. Dit betekent dat door toepassing van de webhooks actief een signaal wordt gegeven bij wijziging van een gegeven in de ontsloten registratie. 

Als aandachtspunt is naar voren gekomen dat er soortgelijke standaarden bestaan voor het gebruik van webhooks, zoals AsyncAPI. Deze standaard is niet opgenomen op de ‘Pas toe of leg uit’-lijst en het Forum Standaardisatie concludeert dat dit geen concurrerende standaard is. OAS richt zich primair op REST API’s (synchrone uitwisseling), terwijl AsyncAPI zich primair richt op asynchrone, event-driven architecturen met berichtenprotocollen zoals Kafka, MQTT, AMQP en WebSockets.

De mogelijkheid om Mutual TLS te specificeren voor een API leidt tot meer eenduidigheid in de API security bij toepassing van Mutual TLS. De nieuwe versie van de standaard sluit ook beter aan bij de nieuwe versie van Digikoppeling, waarin ook Mutual TLS is vereist. Daarnaast hanteert Open Geospatial Consortium (OGC) OAS 3.1 als gangbare versie in hun geo API standaarden.

Tot slot zijn de privacyrisico’s van overheidsbrede adoptie van de standaard acceptabel. De standaard beschrijft alleen de API en wordt niet gebruikt in de runtimebevraging van de API en de security daarvan. OAS kent zelf geen privacyrisico’s, maar helpt wel om duidelijke privacygevoelige API-interacties goed te beschrijven. Verdere invulling van het omgaan met privacyrisico’s is uitgewerkt in de API Design Rules.

Open standaardisatieproces

De toetsingsprocedure wijst uit dat het beheer van OAS 3.1 niet volledig voldoet aan het criterium ‘Open standaardisatieproces’.

Kennisplatform API’s heeft het verzoek ingediend om in aanmerking te komen voor het predicaat ‘Uitstekend beheer’ als erkend Nederlands intermediair voor OAS 3.1. Daarmee hoeven de toekomstige versies van OAS 3.1 in principe niet opnieuw te worden getoetst door het Forum Standaardisatie. 

Kennisplatform API’s organiseert jaarlijks een aantal fysieke bijeenkomsten en wordt er in werkgroepen over de doorontwikkeling van API-gerelateerde standaarden overlegd. Hierbij worden ook internationale ontwikkelingen gedeeld en besproken. Daarnaast zijn de ontwikkeling en het beheer van de standaard belegd bij het OpenAPI Initiative.

Kennisplatform API’s is echter niet formeel ingericht. Daarnaast wordt nog niet voldaan aan de structurele financieringseisen. Indien aan deze eisen is voldaan, kan het Forum Standaardisatie bij de aanmelding van een volgende versie van OAS verkennen in hoeverre aan Kennisplatform API’s – als samenwerkingsverband – het predicaat ‘Uitstekend beheer’ voor erkend Nederlands intermediair kan worden toegekend.

Het specificatiedocument is vrij toegankelijk. Daarnaast is documentatie over het ontwikkel- en beheerproces vrij beschikbaar voor iedereen via deze GitHub-pagina. De standaard wordt beheerd door het Open API Initiative (OAI), een open community opgezet door de Linux Foundation. Daarnaast stelt het OAI de standaard onherroepelijk en royalty-free voor iedereen beschikbaar onder de Apache License, Version 2.0 en garandeert daarnaast dat bijdragers hun intellectueel eigendomsrecht onder dezelfde licentie onherroepelijk en royalty-free voor iedereen beschikbaar stellen.

Het besluitvormingsproces is toegankelijk voor alle belanghebbenden. Dit proces wordt begeleid door een Technical Steering Committee. Het OpenAPI Initiative moedigt zowel individuen als bedrijven aan om mee te doen; iedereen kan zich aanmelden voor de wekelijkse webconferenties van de TSC en deelnemen aan geplande werksessies.

Het OpenAPI Initiative (OAI), dat opereert onder de Linux Foundation, wordt gesteund door een consortium van technologiebedrijven. Hoewel het OAI lidmaatschapskosten hanteert die jaarlijks worden gefactureerd, garandeert de stabiele samenstelling van de leden en de samenwerking met de Linux Foundation een continue doorontwikkeling en financiering van de standaard.

De Nederlandse overheid draagt weliswaar momenteel niet direct bij aan de internationale ontwikkeling van de standaard, maar de toepassing van de standaard wordt wel actief gestimuleerd en ondersteund. Dit vindt plaats in het kader van het beheer van de API Design Rules en developer.overheid.nl. Wanneer vanuit de Nederlandse community de behoefte ontstaat om internationaal invloed uit te oefenen of aandacht te vragen voor specifieke Nederlandse belangen, wordt dit door het Kennisplatform API’s opgepakt, zonder dat zij hier een formele opdracht voor hebben. Dit heeft al eerder plaatsgevonden bij het indienen van een feature request (Mutual TLS). Het behartigen van de Nederlandse belangen van de standaard is de facto belegd bij het Kennisplatform API’s, waarvan de financiering jaarlijks wordt gegarandeerd. De facto houdt in dat het Kennisplatform API’s zich inhoudelijk met de standaard bezighoudt, maar geen formele, expliciete opdracht heeft om als intermediair op te treden.

Draagvlak

De toetsingsprocedure wijst uit dat OAS 3.1 voldoet aan het criterium ‘Draagvlak’.

Meerdere leveranciers bieden ondersteuning voor de standaard. Daarnaast kan de gebruiker de conformiteit van de implementatie van de standaard (laten) toetsen; op GitHub is tooling te vinden waarmee compliancy getest kan worden, dit is ingebouwd in de tooling. Verder is een lokaal profiel tot nu toe nog niet nodig gebleken. Tot slot staan op developer.overheid.nl diverse referenties van OAS-bestanden.

De adoptie is verder toegenomen en erkend bij de vorige versie door de belangrijkste stakeholders vanuit de overheid. Op de website van OpenAPI is te zien dat de adoptie van OAS versie 3.1 hoog is. Daarnaast staan alle deelnemers van het Kennisplatform API’s achter het verplichte gebruik van de standaard, waarmee zij de meerderheid van de overheids-API aanbieders vertegenwoordigen. Versie 3.1 wordt (nog) beperkt gebruikt binnen het organisatorisch werkingsgebied door Nederlandse overheidsorganisaties. De BRP API van de RvIG maakt gebruik van v3.1.0; bij de overgang zijn geen problemen ervaren omdat door de BRP API geen gebruik werd gemaakt van de onderdelen waarop de breaking changes van toepassing waren. Verder gebruiken zowel Nederlandse overheden (Rijk, provincies, gemeenten en waterschappen) als instellingen uit de (semi-) publieke sector de huidige standaard (OpenAPI 3.0); een overzicht van alle organisaties en API’s is te vinden op apis.developer.overheid.nl.

OAS versie 3.1 is niet backward compatible met eerdere versies van de standaard omdat er breaking changes zijn; zoals vermeld op de website van de specificatie van de standaard is de migratie van JSON Schema Draft 5 naar JSON Schema Draft 12 de basis van de breaking changes. Dit wordt ondervangen door voldoende beschikbare (internationale) ondersteunende tooling om OAS 3.1 te implementeren en de transitie van OAS 3.0 naar OAS 3.1 makkelijk te laten verlopen. Tot slot zijn er voldoende positieve signalen over toekomstig gebruik van de standaard door (semi-)overheidsorganisaties, het bedrijfsleven en burgers; zie daarvoor het artikel op developer.overheid.nl.

Opname op de lijst bevordert adoptie

De toetsingsprocedure wijst uit dat OAS 3.1 voldoet aan het criterium ‘Opname op de lijst bevordert adoptie’.

De ‘Pas toe of leg uit’-lijst is nodig om het gebruik van OAS 3.1 binnen de overheid te stimuleren. Veel organisaties houden zich strikt aan de ‘Pas toe of leg uit’-verplichting van Forum Standaardisatie en zullen deze nieuwe versie van de standaard pas gebruiken en vereisen als deze op de lijst staat. Dit wordt onderschreven door meerdere deelnemers van het Kennisplatform API’s.

Adviezen bij opname van de standaard

Het Forum Standaardisatie geeft de volgende adviezen bij plaatsing van versie 3.1 van OAS op de ‘Pas toe of leg uit’-lijst:

1. aan Kennisplatform API's om uiterlijk één maand na publicatie van de nieuwe OAS-versie een heldere aankondiging en toelichting – inclusief aandacht voor migratiescenario’s gezien dat versie 3.1 niet backward compatible is – op de nieuwe versie van de standaard te ontsluiten om de adoptie vergroten. Het Kennisplatform API’s richt zich op het beter laten aansluiten van API’s op de vraag, het delen van kennis over het toepassen van API’s en het afstemmen en waar nodig standaardiseren van werkwijzen tussen organisaties. Ook het project Implementatieondersteuning en Kennisborging kan hier een waardevolle bijdrage aan leveren.
2. aan Forum standaardisatie om, wanneer de AsyncAPI-standaard wordt aangemeld voor de opname op de ‘Pas toe of leg uit’-lijst of de lijst met aanbevolen standaarden, te onderzoeken of een aanvullend profiel voor AsyncAPI nodig is om OAS 3.1 en AsyncAPI goed op elkaar te laten aansluiten.
3. aan het ministerie van Binnenlandse Zaken om de financiering voor het onder de aandacht brengen van de standaard en het ondersteunen van de implementatie daarvan voor minimaal drie jaar te garanderen, zodat een organisatie de rol van Erkend Nederlandse intermediair formeel kan vervullen. Mogelijke partijen die deze rol zouden kunnen vervullen zijn het Kennisplatform API’s of Logius.
4. Aan het Kennisplatform API's om - indien de financiering dit jaar (2026) rondkomt en de opdrachtgever (BZK) ermee instemt - binnen één jaar de de facto rol vast te leggen, de gemaakte afspraken te documenteren en beschikbaar te maken, zodat deze voor iedereen inzichtelijk en toegankelijk zijn.
5. aan Logius en Forum Standaardisatie om bij aanmelding van een nieuwe versie van OAS de formulering van het functioneel toepassingsgebied te heroverwegen en te onderzoeken of het nodig is de scope duidelijker af te bakenen (bijvoorbeeld alleen bij resource-based HTTP API’s). Dit voorkomt interpretatieverschillen, vergemakkelijkt consistente toepassing van de standaard en sluit aan bij de laatste API-ontwikkelingen.
6. aan Forum Standaardisatie om op termijn te reflecteren op de rol van een Erkend Nederlands Intermediair en te beoordelen of de extra formele processen en financiering in verhouding staan tot de te verwachte resultaten. Een sterkere focus op de intermediair als centrale plek voor kennisdeling en implementatieondersteuning kan daarbij een invalshoek zijn.