Schema Validation

API スキーマは、対象エンドポイント、パスまたはクエリ変数の形式、HTTP メソッドなど、いくつかのリクエスト属性に基づいて、どの API リクエストが有効かを定義します。

Schema Validation は、受信リクエストをアップロードした OpenAPI スキーマと比較します。アップロードしたスキーマは、Schema Profile が期待するリクエスト構造を提供します。

アップロードしたプロファイルが利用可能になると、Cloudflare は 常時オンの検出 を生成します。違反の分析と緩和には cf.schema_validation.uploaded.violated を使います。

検出だけではトラフィックを緩和しません。カスタムルールでプロファイルを適用する前に、Profile Analysis で結果を確認してください。適用手順は Custom Rules でプロファイルを適用する を参照してください。

現行バージョンは Schema Validation 2.0 です。以前のバージョンについては、Classic Schema Validation を設定する を参照してください。

エンドポイントは、Web Assets > Operations にオペレーションとして存在する必要があります。ダッシュボードからアップロードすると、スキーマのオペレーションは自動で追加されます。

API または Terraform を使う場合は、スキーマのオペレーションを別途追加します。自動化の詳細は、API 構成 または Terraform を参照してください。

変更の反映には、オペレーション数に応じて数分かかることがあります。

アップロードしたスキーマを削除すると、そのプロファイル評価は停止します。関連するオペレーションは Web Assets のインベントリに残ります。

fallthrough ルールは、既知のオペレーションに一致しないリクエストに一致します。未識別のエンドポイントを保護するには、この WAF Custom Rule を使います。

独自のロジックを使う場合は、cf.api_gateway.fallthrough_detected を使います。ルールの範囲は、API のホスト名またはルートパスに絞ってください。

Cloudflare が現在受け付けるのは OpenAPI v3 スキーマ ↗ だけです。受け付けるファイル形式は YAML（.yml または .yaml）と JSON（.json）です。

ツールによって生成した OpenAPI スキーマは、Schema Validation に取り込むには具体性が足りないことがあります。OpenAPI 仕様に準拠しているかは、Swagger Editor ↗ などのサードパーティツールで確認してください。

Cloudflare API Shield の Schema Validation（インポート）と Schema Learning（エクスポート）は、OpenAPI Specification (OAS) v3.0 ↗ に依存します。

この対応には、OAS v3.0.x などのパッチバージョンも含まれます。OAS v3.1 は未対応で、OpenAPI 2.0 への対応拡大予定もありません。

現在、API Shield は API スキーマの一部機能に未対応です。対象は次のとおりです。すべてのレスポンス、外部参照、基本以外のパステンプレート、unique items。

API Shield を契約している Enterprise のお客様では、有効なスキーマのオペレーション合計は 10,000 が上限です。上限を引き上げる場合は、担当チームに連絡してください。

Schema Validation は、プランごとの最大サイズまでリクエストボディを検査します。この上限を超えるリクエストは、アップロードしたスキーマでは評価しません。

デフォルトのボディサイズ上限は次のとおりです。

リクエストログを使い、ボディサイズをプラン上限と比較します。

API Shield 未契約の Free、Pro、Business、Enterprise のお客様の上限は、プラン を参照してください。

OpenAPI 仕様では必須ではありませんが、Schema Validation では次のフィールドを必須とします。

• type ↗
  • すべてのスキーマに type の設定が必要です。Schema Validation が対応していない型の場合は、代わりに string を設定します。

• schema ↗
  • Schema Validation は、パラメーターの content フィールドに対応していません。詳細は、次の 検証対象および対応フィールドの注意 を参照してください。代わりに、すべての parameters オブジェクトに schema が必須です。

Schema Validation が現在対応している OpenAPI specification（OAS）のオブジェクトとフィールドの詳細です。

• url ↗
  • Schema Validation は相対 URL に対応していません。
• variables ↗
  • サーバー変数は検証しません。

• style ↗
  • 対応しているのはデフォルト値だけです。"simple"（path または header パラメーター）と "form"（query または cookie パラメーター）です。
• explode ↗
  • 対応しているのはデフォルト値だけです。true（form の場合）と false（simple の場合）です。
• content ↗
  • パラメーターの content フィールドには対応していません。代わりに schema フィールドを使います。
• type ↗
  • 現在、object 型のパラメーターは検証しません。

• $ref ↗
  • 外部参照または相対参照には対応していません。

• content
  • Request Body Object ↗
  • Media Type Object ↗
    • Schema Validation は application/json ドキュメントを検証できます。スキーマが他のコンテンツタイプを許可している場合、それらのリクエストは検証なしで受け入れます。

• anyOf
  • Parameter Object ↗
  • Schema Object ↗
    • パラメータースキーマの anyOf スキーマには、現在対応していません。

• format ↗
  • 検証する形式:
    • date-time
    • time
    • date
    • email
    • hostname
    • ipv4
    • ipv6
    • uri
    • uri-reference
    • iri
    • iri-reference
    • int32
    • int64
    • float
    • double
    • password
    • uuid
    • byte
    • uint64
• uniqueItems ↗
  • このフィールドは、現在 Schema Validation では検証しません。

API Shield は、アップロードしたスキーマに含まれるボディ仕様を識別し、受信 API リクエストのデータがそれに従っているかを検証できます。

Schema Validation が現在対応しているのは、content-type が application/json のリクエストです。

OpenAPI 仕様では、リクエストボディのスキーマはメディアレンジ（application/*、application/xml、application/json など）に関連付けられます。

Cloudflare が受信リクエストを検証するとき、リクエストの content-type が OpenAPI で指定したメディアレンジと一致するかを確認します。

たとえば、OpenAPI ファイルがリクエストボディの content マップで application/* を指定している場合、Cloudflare は application/xml と application/json のリクエストを受け入れます。ただし、指定したスキーマで検証するのは application/json のボディだけです。

メディアレンジは、個別のメディアタイプに設定して、できるだけ狭くすることを推奨します。1 つの API エンドポイントで複数の content-type を扱う必要がある場合は、ワイルドカードのメディアレンジを使えます。

オリジンが MIME sniffing ↗ を行う設定の場合も注意が必要です。たとえば、JSON ボディを持つリクエストが意図的に application/malicious の content-type を付け、Cloudflare が application/* のメディアレンジを許可している場合、JSON ボディの内容は検証されずにオリジンへ渡されます。一方、オリジンが content-type を無視し、試しにデシリアライズするか MIME タイプをスニフすると、スキーマのボディ検証を通過したと誤って判断して JSON ボディをデシリアライズする可能性があります。

そのため、同じエンドポイントで application/json と application/xml の両方が必要な場合は、application/* を使えます。Cloudflare は、content-type が application/json のリクエストボディに対して指定したスキーマを検証します。content-type が application/xml（および application/* に一致するその他）のリクエストは通過します。オリジンでは content-type のスニッフィングを無効にすることを、引き続き強く推奨します。

Cloudflare が OpenAPI のリクエストボディ content マップで受け付けるメディアレンジは次のとおりです。

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

メディアレンジでは charset パラメーターの強制も設定できます。この場合、Cloudflare が受け付けるのは値が utf-8 の静的な charset パラメーターだけです。設定した場合、リクエストの content-type にもこの charset が必要です。

このセクションでは、Schema Validation 利用時によくある問題を扱います。

OneOf 制約エラーは、リクエストがアップロードしたプロファイルに違反したことを意味します。ボディが oneOf ↗ オプションのちょうど 1 つに一致しませんでした。

リクエストが無効になった理由は、次のいずれかです。

• 一致ゼロ: ペイロードが、利用可能なサブスキーマのどれにも正しく一致しませんでした。discriminator フィールドは設定されているが、その型に必要な他のフィールドが欠けている場合によく起きます。
• 複数一致: ペイロードが曖昧で、複数のサブスキーマに一致しました。汎用的なスキーマで起きます（たとえば、ペイロードに email と phone の両方がある場合、email と phone の両方のスキーマ定義に一致し、「ちょうど 1 つ」の規則に違反することがあります）。

修正するには、サンプリングしたリクエストをスキーマ定義と比較します。必須フィールドの欠落や、競合する型への一致が原因のことがあります。

API Security をご利用のお客様は、Schema Learning と Schema Validation を通じて Schema Profile にすでにアクセスできます。Cloudflare は、API Security を持たない招待制の Enterprise のお客様向けにクローズドベータを開始しています。関心がある場合は、担当チームに連絡してください。クローズドベータへのアクセスは、将来のプラン提供や価格を約束するものではありません。