From 81ef793d76973137c96c1069ad7eec95ced1dfbf Mon Sep 17 00:00:00 2001 From: lena-larionova Date: Thu, 11 Jun 2026 14:04:19 -0700 Subject: [PATCH 1/3] oas validation structured errors --- .../examples/structured-errors.yaml | 29 +++++++++++++ app/_kong_plugins/oas-validation/index.md | 43 +++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 app/_kong_plugins/oas-validation/examples/structured-errors.yaml diff --git a/app/_kong_plugins/oas-validation/examples/structured-errors.yaml b/app/_kong_plugins/oas-validation/examples/structured-errors.yaml new file mode 100644 index 0000000000..f0b5a8f5e4 --- /dev/null +++ b/app/_kong_plugins/oas-validation/examples/structured-errors.yaml @@ -0,0 +1,29 @@ +title: 'Enable structured validation errors' + +description: | + Return validation errors as a structured list instead of a flat string. + +extended_description: | + By default, validation errors are returned as a single flat string. + Enable `structured_errors` to receive errors in [JSON Schema draft 2020-12 Output Structure](https://json-schema.org/draft/2020-12/json-schema-core#name-output-structure), + with `instanceLocation` and `keywordLocation` fields for each error. + + Use `max_structured_errors` to cap the number of errors returned. + Any errors over the cap are discarded. + +min_version: '3.15' + +weight: 850 + +config: + api_spec: |- + contents of entire API spec go here + structured_errors: true + max_structured_errors: 10 + +tools: + - deck + - admin-api + - konnect-api + - kic + - terraform diff --git a/app/_kong_plugins/oas-validation/index.md b/app/_kong_plugins/oas-validation/index.md index 802abd57b4..1a32a97750 100644 --- a/app/_kong_plugins/oas-validation/index.md +++ b/app/_kong_plugins/oas-validation/index.md @@ -134,3 +134,46 @@ If validation fails, the webhook URL receives a response with JSON payload, whic See the [Event Hooks](/gateway/entities/event-hook/) reference for details on how to configure an Event Hook. + +## Error handling + +By default, when the OAS Validation plugin reports schema violations, it embeds all errors into a single string inside the `message` field. +This makes it difficult for client applications to parse, display, or log validation failures in a structured way. + +The following settings control how validation errors are reported: + + +{% table %} +columns: + - title: Parameter + key: param + - title: Default + key: default + - title: Description + key: description +rows: + - param: | + `structured_errors` {% new_in 3.15 %} + default: "`false`" + description: | + Enable `structured_errors` to receive validation errors as a structured list instead of a flat string, following [JSON Schema draft 2020-12 Output Structure](https://json-schema.org/draft/2020-12/json-schema-core#name-output-structure). Each error includes `instanceLocation` (the path in the request or response body where the violation occurred) and `keywordLocation` (the path in the schema that triggered the error). +

+ When disabled, the plugin preserves the original non-structured error format. + - param: | + `max_structured_errors` {% new_in 3.15 %} + default: "unset (all errors returned)" + description: | + Caps the number of structured validation errors returned in the response. Must be greater than 0. Requires `structured_errors` to be enabled. Any extra errors over the cap are discarded. + - param: "`collect_all_errors`" + default: "`false`" + description: | + Collects all validation errors instead of stopping at the first error. + Only takes effect when `structured_errors` is disabled. +

+ **Note:** Be careful when enabling this option, as it does affect performance. + - param: "`verbose_response`" + default: "`false`" + description: | + If set to `true`, returns a detailed error message for invalid requests and responses. Useful while testing. +{% endtable %} + \ No newline at end of file From 9145cc9f28ca994d9cdca5d00b7ef1dc893d8979 Mon Sep 17 00:00:00 2001 From: lena-larionova Date: Thu, 11 Jun 2026 14:25:26 -0700 Subject: [PATCH 2/3] add verbose_response requirement --- .../oas-validation/examples/structured-errors.yaml | 1 + app/_kong_plugins/oas-validation/index.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/app/_kong_plugins/oas-validation/examples/structured-errors.yaml b/app/_kong_plugins/oas-validation/examples/structured-errors.yaml index f0b5a8f5e4..128d7ff0f0 100644 --- a/app/_kong_plugins/oas-validation/examples/structured-errors.yaml +++ b/app/_kong_plugins/oas-validation/examples/structured-errors.yaml @@ -20,6 +20,7 @@ config: contents of entire API spec go here structured_errors: true max_structured_errors: 10 + verbose_response: true tools: - deck diff --git a/app/_kong_plugins/oas-validation/index.md b/app/_kong_plugins/oas-validation/index.md index 1a32a97750..614a27f72f 100644 --- a/app/_kong_plugins/oas-validation/index.md +++ b/app/_kong_plugins/oas-validation/index.md @@ -156,7 +156,9 @@ rows: `structured_errors` {% new_in 3.15 %} default: "`false`" description: | - Enable `structured_errors` to receive validation errors as a structured list instead of a flat string, following [JSON Schema draft 2020-12 Output Structure](https://json-schema.org/draft/2020-12/json-schema-core#name-output-structure). Each error includes `instanceLocation` (the path in the request or response body where the violation occurred) and `keywordLocation` (the path in the schema that triggered the error). + Enable `structured_errors` to receive validation errors as an `errors` array instead of a flat string, following [JSON Schema draft 2020-12 Output Structure](https://json-schema.org/draft/2020-12/json-schema-core#name-output-structure). Each error includes `instanceLocation` (the path in the request or response body where the violation occurred), `keywordLocation` (the path in the schema that triggered the error), and `error`. +

+ Requires `verbose_response` to be set to `true`.

When disabled, the plugin preserves the original non-structured error format. - param: | From 3081da26e258d5809d1e775a40264d4783a8b901 Mon Sep 17 00:00:00 2001 From: lena-larionova <54370747+lena-larionova@users.noreply.github.com> Date: Fri, 12 Jun 2026 12:43:41 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --- .../oas-validation/examples/structured-errors.yaml | 3 ++- app/_kong_plugins/oas-validation/index.md | 14 ++++++++------ 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/app/_kong_plugins/oas-validation/examples/structured-errors.yaml b/app/_kong_plugins/oas-validation/examples/structured-errors.yaml index 128d7ff0f0..622d81cf90 100644 --- a/app/_kong_plugins/oas-validation/examples/structured-errors.yaml +++ b/app/_kong_plugins/oas-validation/examples/structured-errors.yaml @@ -11,7 +11,8 @@ extended_description: | Use `max_structured_errors` to cap the number of errors returned. Any errors over the cap are discarded. -min_version: '3.15' +min_version: + gateway: '3.15' weight: 850 diff --git a/app/_kong_plugins/oas-validation/index.md b/app/_kong_plugins/oas-validation/index.md index 614a27f72f..558825182a 100644 --- a/app/_kong_plugins/oas-validation/index.md +++ b/app/_kong_plugins/oas-validation/index.md @@ -153,7 +153,7 @@ columns: key: description rows: - param: | - `structured_errors` {% new_in 3.15 %} + [`structured_errors`](/plugins/oas-validation/reference/#schema--config-structured-errors) {% new_in 3.15 %} default: "`false`" description: | Enable `structured_errors` to receive validation errors as an `errors` array instead of a flat string, following [JSON Schema draft 2020-12 Output Structure](https://json-schema.org/draft/2020-12/json-schema-core#name-output-structure). Each error includes `instanceLocation` (the path in the request or response body where the violation occurred), `keywordLocation` (the path in the schema that triggered the error), and `error`. @@ -162,18 +162,20 @@ rows:

When disabled, the plugin preserves the original non-structured error format. - param: | - `max_structured_errors` {% new_in 3.15 %} + [`max_structured_errors`](/plugins/oas-validation/reference/#schema--config-max-structured-errors) {% new_in 3.15 %} default: "unset (all errors returned)" description: | - Caps the number of structured validation errors returned in the response. Must be greater than 0. Requires `structured_errors` to be enabled. Any extra errors over the cap are discarded. - - param: "`collect_all_errors`" + Caps the number of structured validation errors returned in the response. Must be greater than 0. `structured_errors` must also be enabled. Any extra errors over the cap are discarded. + - param: "[`collect_all_errors`](/plugins/oas-validation/reference/#schema--config-collect-all-errors)" default: "`false`" description: | Collects all validation errors instead of stopping at the first error. Only takes effect when `structured_errors` is disabled.

- **Note:** Be careful when enabling this option, as it does affect performance. - - param: "`verbose_response`" + + {:.info} + > **Note:** Be careful when enabling this option, as it does affect performance. + - param: "[`verbose_response`](/plugins/oas-validation/reference/#schema--config-verbose-response)" default: "`false`" description: | If set to `true`, returns a detailed error message for invalid requests and responses. Useful while testing.