---
description: Supply Schema Profiles through uploaded OpenAPI schemas.
title: Schema validation
image: https://developers.cloudflare.com/api-shield/security/schema-validation/og.png?v=79e7231a72607932
---

[Skip to content](#main-content)

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/api-shield/llms.txt  
> Use this file to discover all available pages before exploring further.

# Schema validation

Last updated Oct 5, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/api-shield/security/schema-validation/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/)

Note

Schema Validation is the uploaded source for a Schema Profile. For the shared detection and mitigation model, refer to [Application Profiles](https://developers.cloudflare.com/waf/detections/application-profiles/).

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](https://developers.cloudflare.com/waf/detections/application-profiles/analyze-profile-detections/) before [enforcing the profile with Custom Rules](https://developers.cloudflare.com/waf/detections/application-profiles/enforce-profiles-with-custom-rules/).

Schema Validation 2.0 is the current version. For previous-version reference, refer to [Configure Classic Schema Validation](https://developers.cloudflare.com/api-shield/reference/classic-schema-validation/).

## Configure an uploaded schema

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](https://developers.cloudflare.com/api-shield/security/schema-validation/api/) or [Terraform](https://developers.cloudflare.com/api-shield/reference/terraform/#manage-schema-validation).

### Upload a schema

1. In the Cloudflare dashboard, go to the **Web Assets** page. [Go to **Web assets** ↗](https://dash.cloudflare.com/?to=/:account/:zone/security/web-assets)
2. Go to the **Schema validation** tab.
3. Select **Add validation**.
4. Upload an OpenAPI schema file.
5. Select **Add schema and endpoints**.

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.

### Manage uploaded schemas

1. In the Cloudflare dashboard, go to the **Web Assets** page. [Go to **Web assets** ↗](https://dash.cloudflare.com/?to=/:account/:zone/security/web-assets)
2. Go to the **Schema validation** tab.
3. Select **Schema settings**.
4. Filter by **API abuse**.
5. Under **Schema validation** > **Active schemas**, review uploaded schemas.
6. From the schema overflow menu, download or delete the schema.

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

### Add a fallthrough rule

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.

1. In the Cloudflare dashboard, go to the **Security rules** page. [Go to **Security rules** ↗](https://dash.cloudflare.com/?to=/:account/:zone/security/security-rules)
2. Select **Templates**.
3. Find `Mitigate API requests to unidentified endpoints` and select **Preview template**.
4. Enter a descriptive rule name.
5. Choose the intended hostnames and rule action.
6. Select **Save as draft** or **Deploy**.

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

---

## Specifications

Cloudflare accepts [OpenAPI v3.0 schemas ↗︎](https://spec.openapis.org/oas/v3.0.3.html). 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 ↗︎](https://swagger.io/tools/swagger-editor/) to ensure that schemas are compliant to the OpenAPI specification.

---

## Limitations

Cloudflare API Shield's Schema validation (importing) and [Schema learning](https://developers.cloudflare.com/api-shield/management-and-monitoring/endpoint-management/schema-learning/) (exporting) capabilities rely on [OpenAPI Specification (OAS) v3.0 ↗︎](https://spec.openapis.org/oas/v3.0.3) 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.

Note

Cloudflare recommends using a third-party tool like [Swagger Editor ↗︎](https://editor.swagger.io/) to ensure that all schemas are fully compliant with the OAS v3.0 specification before upload.

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](https://developers.cloudflare.com/api-shield/). To raise this limit, contact your account team.

### Body size for validation

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:

| Plan | Default body size limit |
| --- | --- |
| Free | 1 KiB |
| Pro | 8 KiB |
| Business | 8 KiB |
| Enterprise | 128 KiB |

Note

This limit is separate from the [WAF maximum body inspection size](https://developers.cloudflare.com/waf/managed-rules/#maximum-body-size), which controls how much of the request payload the WAF scans. Increasing one does not affect the other.

#### Identify requests exceeding the body size limit

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](https://developers.cloudflare.com/api-shield/plans/).

### Required fields

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

#### `schema`

- [`type` ↗︎](https://spec.openapis.org/oas/v3.0.3#schema-object)
  - 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.

#### `parameter`

- [`schema` ↗︎](https://spec.openapis.org/oas/v3.0.3#schema-object)
  - Schema validation does not support the content field in parameters. For more details, refer to the [notes on validated and supported fields](#notes-on-validated-and-supported-fields) below. Instead, a schema is strictly required on all parameters objects.

### Notes on validated and supported fields

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

#### `servers`

- [`url` ↗︎](https://spec.openapis.org/oas/v3.0.3#server-object)
  - Schema validation does not support relative URLs.
- [`variables` ↗︎](https://spec.openapis.org/oas/v3.0.3#server-variable-object)
  - Server variables are not validated.

#### `parameter`

- [`style` ↗︎](https://spec.openapis.org/oas/v3.0.3#parameter-object)
  - Only the default values are supported: `"simple"` (path or header parameters) and `"form"` (query or cookie parameters).
- [`explode` ↗︎](https://spec.openapis.org/oas/v3.0.3#parameter-object)
  - Only the default values are supported: `true` (for form) and `false` (for simple).
- [`content` ↗︎](https://spec.openapis.org/oas/v3.0.3#parameter-object)
  - The content field is not supported in parameters. Use the schema field instead.
- [`type` ↗︎](https://spec.openapis.org/oas/v3.0.3#parameter-object)
  - Cloudflare currently does not validate object type parameters.

#### `reference`

- [`$ref` ↗︎](https://spec.openapis.org/oas/v3.0.3#reference-object)
  - 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 ↗︎](https://redocly.com/docs/cli/commands/bundle), to convert it to a single-file schema.

#### `requestBody`

- `content`
  - [Request Body Object ↗︎](https://spec.openapis.org/oas/v3.0.3#request-body-object)
  - [Media Type Object ↗︎](https://spec.openapis.org/oas/v3.0.3#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.

#### `parameter/schema`

- `anyOf`
  - [Parameter Object ↗︎](https://spec.openapis.org/oas/v3.0.3#parameter-object)
  - [Schema Object ↗︎](https://spec.openapis.org/oas/v3.0.3#schema-object)
    - `anyOf` schemas are currently not supported in parameter schemas.

#### `schema`

- [`format` ↗︎](https://spec.openapis.org/oas/v3.0.3#schema-object)
  - 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` ↗︎](https://spec.openapis.org/oas/v3.0.3#schema-object)
  - Patterns follow the [syntax documented for version 1 of the Rust `regex` crate ↗︎](https://docs.rs/regex/1/regex/#syntax). Unsupported constructs include look-around and backreferences. Invalid or unsupported patterns cause the schema upload to fail.
- [`uniqueItems` ↗︎](https://spec.openapis.org/oas/v3.0.3#schema-object)
  - This field is currently not validated by Schema validation.

---

## Body inspection

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 ↗︎](https://mimesniff.spec.whatwg.org/) at your origin.

### Form-urlencoded bodies

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.

---

## Troubleshooting

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

### Resolve a `OneOf` constraint violation

A `OneOf` constraint error means a request violated its uploaded profile. Its body did not match exactly one [`oneOf` ↗︎](https://swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not/) 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.

---

## Availability

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.

Was this helpful?

YesNo

## On this page

[![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/api-shield/security/schema-validation/#page","headline":"Schema validation","description":"Supply Schema Profiles through uploaded OpenAPI schemas.","url":"https://developers.cloudflare.com/api-shield/security/schema-validation/","inLanguage":"en","image":"https://developers.cloudflare.com/api-shield/security/schema-validation/og.png?v=79e7231a72607932","dateModified":"2026-10-05","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```