Schema validation

The API schema defines which API requests are valid based on several request properties like target endpoint, path or query variable format, and HTTP method.

Schema Validation compares incoming requests with an uploaded OpenAPI schema. The uploaded schema supplies expected request structure for a Schema Profile.

After the uploaded profile becomes available, Cloudflare generates an always-on detection. Use cf.schema_validation.uploaded.violated to analyze and mitigate violations.

The detection does not mitigate traffic by itself. Review results in Profile Analysis before enforcing the profile with Custom Rules.

Schema Validation 2.0 is the current version. For previous-version reference, refer to Configure Classic Schema Validation.

Endpoints must exist as operations in Web Assets > Operations. Uploading through the dashboard adds schema operations automatically.

When using the API or Terraform, add schema operations separately. For automation details, refer to API configuration or Terraform.

Changes may take several minutes, depending on the operation count.

Deleting an uploaded schema stops its profile evaluation. Associated operations remain in the Web Assets inventory.

A fallthrough rule matches requests that do not match known operations. Use this WAF Custom Rule to protect against unidentified endpoints.

For custom logic, use cf.api_gateway.fallthrough_detected. Scope the rule to your API hostname or root path.

Cloudflare currently only accepts OpenAPI v3 schemas ↗. The accepted file formats are YAML (.yml or .yaml file extension) and JSON (.json file extension).

OpenAPI schemas generated by different tooling may not be specific enough to import to Schema validation. Use a third-party tool such as Swagger Editor ↗ to ensure that schemas are compliant to the OpenAPI specification.

Cloudflare API Shield's Schema validation (importing) and Schema learning (exporting) capabilities rely on the OpenAPI Specification (OAS) v3.0 ↗.

This support includes all patch versions, such as OAS v3.0.x. OAS v3.1 is not supported, and there are no plans to expand support for OpenAPI 2.0.

Currently, API Shield does not support some features of API schemas, including the following: all responses, external references, non-basic path templating, or unique items.

There is a limit of 10,000 total operations for enabled schemas for Enterprise customers subscribed to API Shield. To raise this limit, contact your account team.

Schema Validation inspects request bodies up to a plan-specific maximum size. Requests exceeding this limit are not evaluated against the uploaded schema.

The default body size limits are:

Use request logs to compare body sizes with your plan limit.

For limits on Free, Pro, Business, or Enterprise customers not subscribed to API Shield, refer to Plans.

Although not strictly required by the OpenAPI specification, Schema validation strictly requires these fields.

• type ↗
  • All schemas require a type to be set. If the specific type is not supported by Schema validation, set the type to string instead.

• schema ↗
  • Schema validation does not support the content field in parameters. For more details, refer to the notes on validated and supported fields below. Instead, a schema is strictly required on all parameters objects.

Refer to the information below for more details on Schema validation's current support for various OpenAPI specification (OAS) objects and fields.

• url ↗
  • Schema validation does not support relative URLs.
• variables ↗
  • Server variables are not validated.

• style ↗
  • Only the default values are supported: "simple" (path or header parameters) and "form" (query or cookie parameters).
• explode ↗
  • Only the default values are supported: true (for form) and false (for simple).
• content ↗
  • The content field is not supported in parameters. Use the schema field instead.
• type ↗
  • Cloudflare currently does not validate object type parameters.

• $ref ↗
  • External or relative references are not supported.

• content
  • Request Body Object ↗
  • Media Type Object ↗
    • Schema validation is able to validate application/json documents. If a given schema allows other content types, Schema validation will accept those requests without validation.

• anyOf
  • Parameter Object ↗
  • Schema Object ↗
    • anyOf schemas are currently not supported in parameter schemas.

• format ↗
  • Validated formats:
    • date-time
    • time
    • date
    • email
    • hostname
    • ipv4
    • ipv6
    • uri
    • uri-reference
    • iri
    • iri-reference
    • int32
    • int64
    • float
    • double
    • password
    • uuid
    • byte
    • uint64
• uniqueItems ↗
  • This field is currently not validated by Schema validation.

API Shield has the ability to identify body specifications contained in uploaded schemas and validate that the data of incoming API requests adheres to them.

Schema validation currently supports validating requests with content-type application/json.

Within the OpenAPI specification, request body schemas are associated to media-ranges (such as application/*, application/xml or application/json).

When Cloudflare validates incoming requests, Cloudflare checks that the request's content-type matches the OpenAPI-specified media-range.

For example, when the OpenAPI file specifies application/* as part of the request body content map, Cloudflare will accept requests with the content-types application/xml and application/json. However, only application/json bodies will be validated with the supplied schema.

Cloudflare recommends keeping the media-ranges as tight as possible by setting them to an individual media-type. If you need to support multiple content-types on an API endpoint, you can utilize wildcard media-ranges.

Care should also be taken if the origin is configured to perform MIME sniffing ↗. For example, when a request carrying a JSON body is deliberately carrying an application/malicious content-type and Cloudflare was configured to allow application/* media-ranges, the request would be passed along to the origin without validating the JSON body contents. However, an origin that ignores the content-type and either trial deserializes or sniffs the MIME type may deserialize the JSON body with a wrong assumption of having passed schema body validation.

As such, if you need to support application/json and application/xml on the same endpoint, you can use application/*. Cloudflare will validate the provided schema for request bodies where the content-type is set to application/json. Requests with content-type application/xml (and others matching application/*) will be let through. It is still strongly advised to disable content-type sniffing on your origin.

Cloudflare allows specifying the following media-ranges in the OpenAPI request body content map:

• */*
• application/*
• application/json.

Media-ranges can also be configured to enforce a charset parameter. For this, Cloudflare only accepts the charset parameter with a static value of utf-8 as part of the media-range specification and when configured, we will similarly require the request's content-type to carry this charset.

This section addresses common issues you may encounter when using schema validation.

A OneOf constraint error means a request violated its uploaded profile. Its body did not match exactly one oneOf ↗ option.

The request was invalid for one of two reasons:

• Matches Zero: The payload did not correctly match any of the available subschemas. This is common when a discriminator field is set, but the payload is missing other required fields for that type.
• Matches Multiple: The payload was ambiguous and matched more than one subschema. This happens with generic schemas (for example, if a payload includes both an email and a phone field, it might match both an email and a phone schema definition, violating the "exactly one" rule).

To fix this, compare the sampled request with its schema definition. The request may omit required fields or match conflicting types.

Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing.