Cloudflare Docs
Ruleset Engine
Cloudflare Docs
Ruleset Engine
GitHub icon
Visit Ruleset Engine on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Ruleset Engine
  3. Rulesets API
  4. JSON object

JSON object

​​ Ruleset object

A fully populated ruleset object has the following JSON structure.


{
  "id": "6a359df138c442b385d20140d4d96919",
  "name": "Example Ruleset",
  "description": "Description of Example Ruleset",
  "kind": "custom",
  "version": "2",
  "phase": "http_request_firewall_custom",
  "rules": [
    {
      "id": "fdb0dd271f3f40b19679cc5d91396024",
      "version": "2",
      "action": "block",
      "expression": "cf.zone.name eq \"example.com\" ",
      "last_updated": "2022-07-20T10:44:29.124515Z"
    }
  ],
  "last_updated": "2022-07-20T10:44:29.124515Z"

}

​​ Properties

The table lists the properties of a ruleset object.

Property Description Value Notes
id Represents the unique Cloudflare-generated identifier for a given version of a ruleset. 32-character UUIDv4 string Unique, read-only
name A human-readable name for the ruleset. String The name is immutable. You cannot change the name over the lifetime of the ruleset.
description Optional description for the ruleset. String You can change the description over the lifetime of the ruleset.
kind The kind of ruleset the JSON object represents.

There are four kinds of rulesets:

  • root
  • zone
  • managed
  • custom

kind is immutable.
version The version of the ruleset. Integer value starting at 1 and incremented by 1 each time the ruleset is modified Read-only
phase The phase to which the ruleset belongs. String phase is immutable.
rules A list of rules to include in the ruleset. Array of JSON objects (refer to rule JSON object)
last_updated The time (UTC) when the ruleset was last updated. ISO 8601 timestamp in the format YYYY-MM-DDThh:mm:ss.TZD Read-only

​​ Rule object structure and properties

A fully populated rule JSON object has the following structure:


{
  "id": "fdb0dd271f3f40b19679cc5d91396024",
  "version": "2",
  "action": "block",
  "categories": ["wordpress"],
  "expression": "cf.zone.name eq \"example.com\"",
  "last_updated": "2022-07-20T10:44:29.124515Z",
  "enabled": true

}

The JSON object properties for a rule are defined as follows:

Property Description Value Notes
id Represents the unique Cloudflare-generated identifier for a given version of a rule. 32-character UUIDv4 string Unique, read-only
version The version of the rule. Integer value starting at 1 and incremented by 1 each time the ruleset is modified Read-only. Changing the order of a rule in a ruleset does not change its version.
action Defines what happens when there’s a match for the rule expression. String The available actions depend on the phase where the rule's ruleset is executed.
categories Tags associated with the current rule. You can define overrides that affect rules with a given tag. Array of strings Read-only. Only available in WAF Managed Rules.
expression Criteria defining when there is a match for the current rule. String The fields and functions you can use in a rule expression depend on the phase where the rule's ruleset is executed.
last_updated The time (UTC) when the rule was last updated. ISO 8601 timestamp in the format YYYY-MM-DDThh:mm:ss.TZD Read-only
enabled When set to true, the current rule is enabled. Boolean