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": "ruleset-id",
  "name": "Example Ruleset",
  "description": "Description of Example Ruleset",
  "kind": "custom",
  "version": "2",
  "phase": "http_request_firewall_custom",
  "rules": [
    {
      "id": "rule-id",
      "version": "2",
      "action": "block",
      "expression": "cf.zone.name eq \"example.com\" ",
      "last_updated": "2020-07-20T10:44:29.124515Z"
    }
  ],
  "last_updated": "2020-07-20T10:44:29.124515Z"

}

​​ Properties

The table lists the properties of a ruleset object.

PropertyDescriptionValueNotes
idRepresents the unique Cloudflare-generated identifier for a given version of a ruleset.32-character UUIDv4 stringUnique, read-only
nameA human-readable name for the ruleset.StringThe name is immutable. You cannot change the name over the lifetime of the ruleset.
descriptionOptional description for the ruleset.StringYou can change the description over the lifetime of the ruleset.
kindThe kind of ruleset the JSON object represents.

There are four kinds of rulesets:

  • root
  • zone
  • managed
  • custom
kind is immutable.
versionThe version of the ruleset.Integer value starting at 1 and incremented by 1 each time the ruleset is modifiedRead-only
phaseThe phase to which the ruleset belongs.Stringphase is immutable.
rulesA list of rules to include in the ruleset.Array of JSON objects (refer to rule JSON object)
last_updatedThe time (UTC) when the ruleset was last updated.ISO 8601 timestamp in the format YYYY-MM-DDThh:mm:ss.TZDRead-only

​​ Rule object structure and properties

A fully populated rule JSON object has the following structure:

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

}

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

PropertyDescriptionValueNotes
idRepresents the unique Cloudflare-generated identifier for a given version of a rule.32-character UUIDv4 stringUnique, read-only
versionThe version of the rule.Integer value starting at 1 and incremented by 1 each time the ruleset is modifiedRead-only. Changing the order of a rule in a ruleset does not change its version.
actionDefines what happens when there’s a match for the rule expression.StringThe available actions depend on the phase where the rule's ruleset is executed.
categoriesTags associated with the current rule. You can define overrides that affect rules with a given tag.Array of stringsRead-only. Only available in WAF Managed Rules.
expressionCriteria defining when there is a match for the current rule.StringThe fields and functions you can use in a rule expression depend on the phase where the rule's ruleset is executed.
last_updatedThe time (UTC) when the rule was last updated.ISO 8601 timestamp in the format YYYY-MM-DDThh:mm:ss.TZDRead-only
enabledWhen set to true, the current rule is enabled.Boolean