API schema validation - Edge Security Acceleration - Alibaba Cloud Documentation Center

After you upload an API schema (such as an OpenAPI specification), the system automatically maps it to your managed APIs. It then validates incoming requests against this schema and applies your configured security policy to any non-compliant traffic.

How it works

Once your APIs are discovered and managed, you can enable schema validation across your entire API surface.

When a request reaches a point of presence (POP), ESA first checks if the request targets a managed API that has an associated schema.
- If not, the request proceeds to other security checks.
- If so, ESA proceeds to the next step.
ESA checks if the request is compliant with the schema:
- If non-compliant, the system applies your configured action (for example, Block) and records the event.
- If compliant, the request is allowed to pass.

Set up schema validation

To get started, upload an API schema and enable the validation.

In the ESA console, choose Websites, and then click the target site in the Website column.
In the left navigation pane, choose Security > API Security.
On the API Security page, select the Schema Validation tab, and click Schema Validation Settings.
On the settings page, click Upload Schema to upload your schema file.
ESA automatically matches the APIs defined in your schema file to your managed APIs. Review the matches and click OK.
After the schema is uploaded, configure the Actions for non-compliant requests. We strongly recommend starting with the Monitor action to observe and log for false positives without affecting legitimate traffic. Turn on the Status switch to enable validation.
Return to the Schema Validation tab to view your configured APIs and their validation status.

Analyze non-compliant requests

Once enabled, API Security continuously monitors requests for schema compliance. On the Schema Validation tab, you can filter by schema to see the number of non-compliant requests for each API over the last 24 hours.

An increase in non-compliant requests can indicate two main issues:

Client-side errors: Legitimate clients may be sending malformed requests. This can be caused by bugs in frontend code, incorrect parameter formats (e.g., form data instead of JSON), missing required parameters, or data type mismatches (e.g., a string instead of a boolean). Review your client-side implementation and consider adding stricter input validation.
Attack behavior: Attackers often send malformed requests to probe for vulnerabilities like SQL injection, cross-site scripting (XSS), or broken access control. A sudden spike in non-compliant requests may signal an attack. If you suspect an attack, Change the action to Block and configure stricter WAF rules.

Analyze request detail

To diagnose the root cause of non-compliant requests, you can inspect the sampled logs in Events or Security Analytics.

On the Schema Validation tab, identify an API with an unusual number of non-compliant requests.
Choose the appropriate tool based on the configured action:
- Action is None: Since no security action is triggered, these requests are best viewed in the broader logs available in Security Analytics.
- Action is Monitor/Block: Since a security event is triggered, the logs are easily accessible and correlated in Events.
This section uses Events as an example. In the left navigation pane, choose Security > Events.
To use Security Analytics, choose Security > Security Analytics in the navigation pane on the left.
On the Events page, scroll down to the Sampling Logs area. Filter for events triggered by API Security. Click the expand icon for a log entry to view its details. Analyze the request based on the features in the details. You can also pivot to Real-time Log for more details.

Change the action

You can set a global default action for all APIs or override it for a specific API.

Modify the global default action: On the Schema Validation tab, click Change in the Default Action column, and select an action:
- Block: Blocks non-compliant requests and records block logs.
- Monitor: Allows non-compliant requests to pass and records logs.
- None: Takes no action and does not log.
Configure an action for a specific API: In the API list of Schema Validation, click Change Action to the right of the API, and select an action.
- Default: Uses the global default action.
- Block: Blocks non-compliant requests and records block logs.
- Monitor: Allows non-compliant requests to pass and records logs.
- None: Takes no action and does not log.

Handle APIs without a schema

After uploading a schema, some APIs may remain unassociated. On the Schema Validation tab, click the number in the APIs Without a Schema column to view a list of these endpoints.

Endpoints without a schema are not validated, creating a potential security gap. An API might not be matched for two main reasons:

Omission from the schema: The API was accidentally left out of your schema file. Verify the API's path, host, and HTTP method in the list, then update your schema file and upload it again.
Non-standard API design: The discovered API does not follow standard RESTful practices and therefore does not match your schema's definitions. You may need to refactor the API. Common issues include:
- Non-standard path: For exmaple, using /user instead of the defined /users.
- Incorrect HTTP method: For exmaple, using GET for a destructive action like /users/delete/123 instead of DELETE.
- Status code abuse: For exmaple, always returning a 200 OK status, even for errors, and placing the real status code in the response body (e.g., { "status": "error", "code": 500 }).
- Confusing data structure: For example, placing a field in the wrong part of the request or response (e.g., defining an email field in the response schema when it should be in the request body).

Schema specifications

File format and size

Format: Schema files must be in .yml, .yaml, or .json format.
Size: The maximum file size is 58 KB. For larger schemas, use the .json format and compress it before uploading.

Schema content

Version

ESA API security architecture validation currently supports only OpenAPI Specification (OAS) v3.0.x.

Fields

Required fields

openapi: The OAS version string (e.g., 3.0.0).
info: Metadata about the API, including a version (e.g., 1.0.0).
paths: The host information where the API is served.
servers: The host information where the API is served:
- url: Only absolute URLs are supported, such as https://api.example.com.
- variables: Server variables are not supported and will be ignored during parsing.

Optional fields

schema: The data structure definition. The following types are supported:
- int32
- uint32
- int64
- uint64
- float
- double
- boolean
- email
reference: Uses $ref to point to a predefined object. External and relative references are not supported.
requestbody: Defines the request body. Only data with a content-type of application/json is supported.

Example

The following is an example of a .json schema file.

{
    "openapi": "3.0.0",
    "info": {
        "title": "example",
        "description": "example",
        "version": "1.0"
    },
    "servers": [
    {
      "url": "https://example1.aliyun.com",
      "description": "example1 url"
    },
    {
      "url": "https://example2.aliyun.com",
      "description": "example2 url"
    }
    ],
    "components": {
        "schemas": {
            "ParamsObject": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "value": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "value"
                ]
            }
        }
    },
    "paths": {
        "/example/{param1}": {
            "get": {
                "operationId": "getexampleById",
                "parameters": [
                    {
                        "name": "param1",
                        "in": "path",
                        "required": true,
                        "description": "id",
                        "schema": {
                            "type": "integer",
                            "format": "int32"
                        }
                    }
                ]
            }
        },
        "/api1": {
            "post": {
                "operationId": "post_api1",
                "summary": "post api1 request",
                "parameters": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ParamsObject"
                            }
                        }
                    }
                }
            },
            "get" :{
                "operationId": "get_api1",
                "summary": "get api1 request",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "format": "int32"
                        }
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        }
    }
}