Document updated on Feb 5, 2025

Response Schema Validation for API Endpoints

The response JSON schema validator adds a schema validation before the gateway returns the response to the end-user or before it’s merged in the endpoint with the rest of the backends.

Before returning the response, you can define the minimum response fields and their characteristics through JSON schema syntax (drafts 04, 06, and 07 supported).

You can use this plugin in conjunction with other components and perform validations, and you can insert it either in the endpoint section or the backend section. For instance, it can be part of a sequential proxy call and decide that the response does not have enough data to move forward and cancel the cascading connection.

Configuration

The configuration is straightforward, as you only need to write the desired JSON schema you expect in the response at the endpoint or backend levels (you can place it in both). For example, to validate that the backend response has a specific schema, you would do:

{
  "url_pattern": "/mybackend",
  "extra_config": {
    "validation/response-json-schema": {
      "schema": {
        "type": "object",
        "required": [
          "user"
        ]
      },
      "error": {
        "body": "We couldn't process you request, try again later.",
        "status": 401
      }
    }
  }
}

The configuration above declares a very simple JSON schema that checks the existence of a property user in the response. All backend manipulations (e.g.: deny, allow, target, etc.) take place before the validator runs, so when planning your validations make sure to take into account any previous modifications.

There are other attributes you can use. This is the configuration possible:

At the endpoint level the validator works exactly the same, and runs also after other manipulations. Here is the same example but with more detail on the validated JSON Schema:

{
  "endpoint": "/foo",
  "extra_config": {
    "validation/response-json-schema": {
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "user": {
            "type": "object",
            "properties": {
              "username": {
                "type": "string"
              },
              "user_id": {
                "type": "number"
              },
              "status": {
                "type": "string",
                "enum": [
                  "registered",
                  "banned"
                ]
              }
            },
            "required": [
              "username",
              "user_id"
            ]
          }
        },
        "required": [
          "user"
        ]
      },
      "error": {
        "body": "We couldn't process you request, try again later.",
        "status": 401
      }
    }
  }
}

Migration from old plugin

Prior to v2.9 the response-schema-validator offered this functionality, and is now deprecated as it is supported natively. If you used the plugin you will need to execute the following change in your configuration:

{
   "endpoint": "/foo",
   "extra_config": {
-    "plugin/req-resp-modifier": {
-      "name": [
-        "response-schema-validator"
-      ],
-      "response-schema-validator": {
-        "schema": {},
-        "error": {
-          "body": "The server encountered an internal error. Please try again later.",
-          "status": 500
-        }
+    "validation/response-json-schema": {
+     "schema": {},
+     "error": {
+        "body": "The server encountered an internal error. Please try again later.",
+        "status": 500
       }
     }
}

As you can see the following changes are needed:

• The plugin/req-resp-modifier is renamed to "validation/response-json-schema
• The name property goes away
• The extra response-schema-validator level goes away
• The attributes schema and error stay the same.