Repository navigation
Gebruik tags voor het identificeren van endpoints die een bepaalde module implementeren #365
Description
Bij het schrijven van de linter regels voor de nieuwe pagination module kwamen tegen het fundamentele probleem aan: we weten niet wanneer een API(-endpoint) de module implementeert. Daardoor is het niet mogelijk om bepaalde regels te schrijven. Hier is een bepaalde marker voor nodig om te weten "en nu zijn deze linter regels van toepassing".
Er is eerder al gesproken over het gebruiken van JSON schema extensions om extra attributen toe te voegen aan een OpenAPI specificatie. Hier kunnen dan de modules in worden vastgelegd. Dit was toen relevant voor het automatisch tonen van een homepage voor een API.
We zouden ook de tags van OpenAPI zelf kunnen gebruiken. In het geval van pagination zou een endpoint die paginated results terug geeft dan een tag moeten hebben met nlgov-mod-pagination. De linter regels kunnen deze tag dan gebruiken als filter om daarna een regel toe te passen. Tevens kan het API register de tags gebruiken om aan te geven welke modules allemaal in een API worden toegepast.
Activity
dvh commentedon Nov 11, 2026
Ik ben geen voorstander van het gebruik van
tagshiervoor en wel om de volgende twee redenen:tagskennen weliswaar een vrije invulling, maar daarmee is het gebruik hiervan voor andere doeleinden dan mensen misschien zelf al bepaald hebben niet backwards compatible. Voorbeeld: API 1 gebruikt tags om een onderscheid te maken tussen gesloten en publieke endpoints, API 2 gebruikt tags om operaties te groeperen op onderwerp (bijv. "vergunningsaanvraag").tagskennen een eigenname, endescription(de link in jouw issue linkt naar OAS 3.2 waarbij er meer velden zijn om tagging nog breder in te kunnen zetten) die nu al gebruikt kunnen worden om DX te verhogen door bijvoorbeeld extra informatie over dit onderwerp te geven. OpenAPI tooling gebruiken tags ook veelal om deze groepering op een gebruiksvriendelijke manier te renderen. Oftewel: tags worden vaak gebruikt als human-readable categorieën. Technisch gezien kunnen we daar machine-readable "ADR-tags" aanhangen, maar dan worden die ook gerenderd door bestaande tooling waardoor mogelijke bestaande "tagging-strategieën" kapot gaan.tagsbeperken zich tot operatieniveau (of hoger), waarmee we nog steeds het probleem dat we hebben met bijvoorbeeld de geomodule niet oplossen: we moeten hier weten welk veld een geometrie claimt te zijn zodat we dat specifieke veld kunnen linten.Eigen extensies raken geen bestaande tooling en maken het bovendien mogelijk om ook op veldniveau dingen aan te kunnen geven tbv het checken op ADR compliance. Bestaande functionaliteit "misbruiken" alleen maar voor onze compliance checks lijkt mij niet de juiste weg. Als het gaat om tags zou ik eerder graag zien dat dit juist op een andere manier meer wordt gestandaardiseerd om betere DX (en AX) af te dwingen.