Response bij input validatie

De DSO schrijft een structuur voor waar een fout-response aan moet voldoen in het geval van validatiefouten:

{
    "type": "...",
    "title": "...",
    "status": 400,
    "detail": "...",
    "instance": "...",
    "invalid-params": [{
        "type": "...",
        "name": "<veldnaam>",
        "reason": "Maximale lengte overschreden.",
    }]
}

Op het forum is nagevraagd hoe er moet worden omgegaan met meerdere fouten op hetzelfde veld, met de conclusie dat dit beter gespecificeerd moet worden.

In de ZGW API’s kiezen we ervoor om elke fout op een veld als apart object op te nemen binnen de "invalid-params" sleutel. Dit laat clients toe om elke individuele fout te renderen zoals zij wensen.

Tevens voegen we op het hoofdniveau van fout-responses en binnen een object in "invalid-params" een sleutel "code" toe. Dit veld bevat een waarde die door machines begrepen kan worden, bijvoorbeeld "invalid" of "max_length_exceeded". De "type" sleutel is namelijk optioneel en bedoeld voor developers om meer informatie over het fouttype te lezen, en niet voor automatische verwerking.

Een voorbeeld response is dan:

{
    "type": "URI: https://zaken-api.vng.cloud/ref/fouten/ValidationError/",
    "title": "Ongeldige gegevens",
    "status": 400,
    "code": "invalid",
    "detail": "Er deden zich validatiefouten voor",
    "instance": "urn:uuid:2d3f8adb-470d-4bf4-8c43-4b2ebeef7504",
    "invalid-params": [
        {
            "name": "identificatie",
            "code": "max-length",
            "reason": "Maximale lengte overschreden.",
        },
            {
            "name": "identificatie",
            "code": "special-characters",
            "reason": "De identificatie mag geen speciale karakters bevatten.",
        }
    ]
}

Merk op dat de concrete codes hier fictief zijn en puur ter illustratie zijn.

VNG-Realisatie / API-Kennisbank

Response bij input validatie #98