feat(gateway): OAS validation structured errors

app/_kong_plugins/oas-validation/examples/structured-errors.yaml

@@ -0,0 +1,31 @@
+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:
+  gateway: '3.15'
+
+weight: 850
+
+config:
+  api_spec: |-
+    contents of entire API spec go here
+  structured_errors: true
+  max_structured_errors: 10
+  verbose_response: true
+
+tools:
+  - deck
+  - admin-api
+  - konnect-api
+  - kic
+  - terraform

app/_kong_plugins/oas-validation/index.md

@@ -134,3 +134,50 @@ 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:
+
+<!--vale off-->
+{% table %}
+columns:
+  - title: Parameter
+    key: param
+  - title: Default
+    key: default
+  - title: Description
+    key: description
+rows:
+  - param: |
+      [`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`.
+      <br><br>
+      Requires `verbose_response` to be set to `true`.
+      <br><br>
+      When disabled, the plugin preserves the original non-structured error format.
+  - param: |
+      [`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. `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.
+      <br><br>
+
+      {:.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.
+{% endtable %}
+<!--vale on-->