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 saved 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.

Multiple uploaded schemas can be active at the same time. When a new schema contains an operation that is already covered by an active schema, the new schema replaces the validation definition for that operation only. Operations that are not included in the new schema continue to use their existing validation definitions.

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 saved operations. Requests that match candidate operations also match the fallthrough rule. 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 accepts OpenAPI v3.0 schemas ↗︎. OpenAPI v3.1 uploads can succeed when they use v3.0-compatible semantics. OpenAPI v3.1-only semantics are not supported. 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 OpenAPI Specification (OAS) v3.0 ↗︎ semantics.

This support includes all patch versions, such as OAS v3.0.x. Cloudflare processes compatible OAS v3.1 uploads with v3.0 semantics, but does not support v3.1-only semantics. OpenAPI 2.0 is not supported.

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 structurally inspects request bodies up to a plan-specific maximum size. For an operation with an applicable body schema, an oversized body produces a Schema Validation body-size violation.

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.

Schema Validation requires the following fields in the listed contexts. It can infer some parameter schema types as described in this section.

• type ↗︎
  • Parameter schemas require a supported type unless Schema Validation can infer one from items, properties, single-type enum values, or unambiguous composition branches. 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 ↗︎
  • Local component references, such as #/components/schemas/Pet, are supported. External references and other relative references are not supported. Before uploading a schema with unsupported references, use an OpenAPI bundling tool, such as the Redocly CLI bundle command ↗︎, to convert it to a single-file schema.

• content
  • Request Body Object ↗︎
  • Media Type Object ↗︎
    • Schema Validation can validate application/json and compatible application/x-www-form-urlencoded documents. If a schema allows other content types, Schema Validation accepts those requests without body 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
• pattern ↗︎
  • Patterns follow the syntax documented for version 1 of the Rust regex crate ↗︎. Unsupported constructs include look-around and backreferences. Invalid or unsupported patterns cause the schema upload to fail.
• uniqueItems ↗︎
  • This field is currently not validated by Schema validation.

API Shield validates incoming request bodies against matching body schemas. Schema Validation supports application/json and compatible application/x-www-form-urlencoded bodies.

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

• */*
• application/*
• application/json
• application/x-www-form-urlencoded

Wildcard media ranges can permit other content types without validating their body structure. For example, application/* permits application/xml, but Schema Validation does not structurally validate the XML body. Keep media ranges as specific as possible and disable MIME sniffing ↗︎ at your origin.

To validate a form body, define application/x-www-form-urlencoded explicitly. Its top-level schema must be an object. Properties can be primitives or flat arrays of primitives. Cloudflare does not apply a form body schema that contains nested objects, nested arrays, byte or binary formats, or nondefault encoding directives.

Form field names and values must decode to valid UTF-8. Repeat a key to supply array values. A scalar key can appear only once, while one occurrence is valid for an array. A form body can contain up to 8,192 key-value pairs. Additional pairs produce a body violation.

For validated JSON and form requests, charset is optional and is the only accepted media type parameter. If present, its value must be utf-8. A charset parameter in the uploaded schema does not require requests to include it.

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.