Cloudflare.SchemaValidation reference

OperationSetting

Source: src/Cloudflare/SchemaValidation/OperationSetting.ts

A per-operation schema validation override (/zones/{zone_id}/schema_validation/settings/operations/{operation_id}) — pins a mitigation action for a single API Shield operation, superseding the zone-level default just for that operation.

The override is keyed by the operation’s UUID; deleting the resource clears the override so the operation falls back to the zone default. Deleting the underlying API Shield operation cascades the override away.

OperationSetting: Overriding an operation

Block non-conforming requests on one operation

const op = yield* Cloudflare.ApiShield.Operation("GetUser", {
  zoneId: zone.zoneId,
  method: "GET",
  host: "api.example.com",
  endpoint: "/users/{id}",
});

yield* Cloudflare.SchemaValidation.OperationSetting("BlockGetUser", {
  zoneId: zone.zoneId,
  operationId: op.operationId,
  mitigationAction: "block",
});

Exempt an operation from validation

yield* Cloudflare.SchemaValidation.OperationSetting("SkipWebhook", {
  zoneId: zone.zoneId,
  operationId: webhookOp.operationId,
  mitigationAction: "none",
});

SchemaValidationSchema

Source: src/Cloudflare/SchemaValidation/Schema.ts

An OpenAPI v3 schema uploaded to a zone for API Shield schema validation (/zones/{zone_id}/schema_validation/schemas).

Uploading a schema registers the endpoints it describes as API Shield operations (a server-side side effect — deleting the schema does not delete those operations). The schema body is immutable: changing source uploads a new schema and deletes the old one (replacement). Only the validationEnabled flag is mutable in place.

SchemaValidationSchema: Uploading a Schema

Upload an OpenAPI v3 schema

const schema = yield* Cloudflare.SchemaValidation.SchemaValidationSchema("ApiSchema", {
  zoneId: zone.zoneId,
  source: JSON.stringify({
    openapi: "3.0.0",
    info: { title: "my-api", version: "1.0.0" },
    servers: [{ url: "https://api.example.com" }],
    paths: {
      "/users": {
        get: {
          operationId: "listUsers",
          responses: { "200": { description: "ok" } },
        },
      },
    },
  }),
});

Upload a schema without enabling validation

const schema = yield* Cloudflare.SchemaValidation.SchemaValidationSchema("DraftSchema", {
  zoneId: zone.zoneId,
  source: openApiDocument,
  validationEnabled: false,
});

SchemaValidationSchema: Toggling validation

// Enabling (false → true) patches the schema in place. Disabling an
// enabled schema is rejected by Cloudflare, so `true` → `false` (like a
// `source` change) replaces the schema instead.
yield* Cloudflare.SchemaValidation.SchemaValidationSchema("DraftSchema", {
  zoneId: zone.zoneId,
  source: openApiDocument,
  validationEnabled: true,
});

Settings

Source: src/Cloudflare/SchemaValidation/Settings.ts

Zone-level schema validation settings (/zones/{zone_id}/schema_validation/settings) — the default mitigation action applied to requests that do not conform to an enabled schema, plus an optional zone-wide kill switch.

The settings are a zone singleton: they always exist (Cloudflare default is none), so this resource never creates or deletes anything physical. Reconcile PUTs the desired state when the observed state differs; destroy restores the values the zone had before Alchemy first managed them.

The log action is plan-gated (API Shield entitlement) on some zones — setting it there fails with the typed UnentitledMitigationAction error.

Settings: Managing the zone default

yield* Cloudflare.SchemaValidation.Settings("Validation", {
  zoneId: zone.zoneId,
  validationDefaultMitigationAction: "block",
});

Settings: Kill switch

yield* Cloudflare.SchemaValidation.Settings("Validation", {
  zoneId: zone.zoneId,
  validationDefaultMitigationAction: "block",
  // overrides every schema and per-operation setting:
  validationOverrideMitigationAction: "none",
});