Voeg regel toe voor error structuur bij Bad Requests

[TimvdLippe]

Hier was initieel geen consensus voor bij de behandeling van het hoofdstuk "Error Handling".

[github-actions]

Preview link voor pull request
Diff met W3CDiff

[TimvdLippe]

Deze wijziging is gedeeltelijk goedgekeurd op het TO API van 2026-03-03. Alle regels behalve /core/error-handling/bad-request zijn goedgekeurd. Voor deze laatste regel wordt de discussie verder gevoerd met inachtneming van de input van Kadaster over hun huidige omgang van error handling (CC @strijm). Hier zal er expliciet worden gekeken naar de huidige oplossing bij Haal Centraal en worden gekeken naar:

1. Het mogelijk hernoemen van errors naar invalid-params
2. Analyseren van impact van name vervangen door location
3. Kijken hoe de gedetailleerde specificatie van error handling in .feature bestanden bij Kadaster te vatten is in de structuur

#251 (comment)

Het mogelijk hernoemen van errors naar invalid-params

Dit lijkt me niet wenselijk, omdat je een JSON property niet kunt beschouwen als een "param" (in tegenstelling tot query en header parameters). Hier zit dus een semantische mismatch. Om deze reden was gekozen voor de algemenere term errors, in lijn met de voorbeelden in de RFC en bijv ook in dit blog.

Analyseren van impact van name vervangen door location

Het gebruik van name impliceert een enkelvoudige naam van een top-level property (in het geval van een body value). Dat lijkt ook de manier waarop het in de genoemde API's wordt gebruikt. Je wil echter ook errors kunnen rapporteren voor dieper gelegen waardes (zoals nested object properties of array items). Vandaar dat er gekozen is voor de bredere term location die voor body values een locator van de value verwacht (JSON Pointer voor JSON, XPath voor XML). Voor parameters is de waarde van location enkel de naam.

@joostfarla in #251 (comment)

Mogelijkheden voor naamgeving van het JSON veld:

1. "errors"
2. "invalid-params"
3. "invalid-input"

[TimvdLippe]

@kad-sprenr Dit is de PR waar Mark en ik het over hadden. Ben jij in de gelegenheid hier naar te kijken en de conversatie voort te brengen met de andere API experts?

[kad-sprenr]

@TimvdLippe Wij zijn het op zich eens om 'errors' te gebruiken omdat je daarmee de voorbeelden in RFC9457 volgt en dat lijkt momenteel de standaard te zijn voor het uitbreiden van problem+json. Wat @strijm en ik het liefste zien is dat die RFC volledig gevolgd wordt en niet gedeeltelijk, dus dat ook 'name' hernoemd wordt naar 'pointer', en niet naar iets dat afwijkt van de RFC (zoals location).

[TimvdLippe]

Vandaag offline besproken. Het plan is om de examples/ zoals ze hier in de repository staan te updaten met fouten en dan kijken of het haalbaar is om de voorgestelde structuur te implementeren. Vermoeden is dat frameworks dit niet out-of-the-box doen, maar dat het wel mogelijk is om dit soort structuren terug te geven. Die aanname moeten we dus verifiëren. @kad-sprenr gaat dat ook nog doen voor Spring Boot (die staat niet bij ons in de repository).

[TimvdLippe]

@kad-sprenr Het is 17:00, dus kwam nog niet verder vandaag, maar deze class is een begin. Naar mijn weten gebruiken zowel Quarkus als Spring Boot dezelfde Jakarta classes. Dus het zou mij verbazen als het in Spring Boot niet ook nog werkt.

Later deze week ga ik hier weer aan verder, maar hopelijk helpt dit qua inspiratie.