Ruleset format
Top-level fields
| Field | Meaning |
|---|---|
rulesetId |
Stable identifier matching [a-z0-9][a-z0-9.-]*, at most 200 characters. custom and IDs starting with custom- identify operator custom rules. |
version |
Release version. Rulesets published through Clearplane Cloud use the UTC publication minute, yyyy_MM_dd_HH_mm, so a version states how fresh the rules are. Operator-authored custom rulesets may use that form or a semantic version. Engine compatibility is carried separately by minimumClearplaneVersion. |
schemaVersion |
1. |
kind |
Baseline, Application or Exclusion. |
minimumClearplaneVersion |
Earliest compatible product version; it must cover every feature used. |
releasedAt |
Release timestamp with a UTC offset. |
provenance |
source, license and optional sourceUri. |
profiles |
The standard and management rule selections; empty for Exclusion rulesets. |
rules |
Rules to evaluate; empty for Exclusion rulesets. |
lists, lexicons, detectors |
Reusable data and token detectors belonging to this ruleset. |
exclusions |
Target exclusions, allowed only in Exclusion rulesets. |
integrityTests |
Embedded test vectors checked before a release is accepted. |
JSON rules
Use camelCase property names and enum names such as RequestMetadata, never numeric enum values. Unknown properties and duplicate properties reject the document. A release whose schemaVersion or minimumClearplaneVersion is newer than this Clearplane supports is reported as needing a newer Clearplane rather than as invalid.
Custom drafts omit rulesetId, version, schemaVersion, kind, minimumClearplaneVersion and releasedAt. Clearplane sets them when you publish, and a draft that contains any of them is rejected with ManagedProperty. The maximum JSON nesting depth is 64. A signed envelope is limited to 16 MiB; its decoded payload is also bounded. Custom draft JSON is limited to 16 MiB of UTF-8. Compiler collection and text limits can reject a smaller document.
Signed delivery envelope
Cloud releases wrap the exact payload bytes in an envelope with formatVersion 1, algorithm ES512, signingKeyId, the UTC signedAt, contentHashSha256, payloadBase64 and signatureBase64. The P-521 signature binds the signing timestamp and payload. An envelope with a newer formatVersion is reported as needing a newer Clearplane. signedAt is separate from the payload’s releasedAt; Core checks it against the trusted key’s validity window. See Cloud ruleset updates for rotation and revocation.
The live Cloud manifest uses formatVersion: 3. Each entry carries contentHashSha256, signedEnvelopeSizeBytes, the release’s releasedAt, a release-notes summary, an optional HTTP or HTTPS notes link, compiledSizeBytes and the measurementRuntime that measured it. Core ignores unknown manifest fields, rejects duplicate properties and skips invalid entries. Earlier manifest versions are unsupported.
Profiles
A ruleset with rules requires both standard and management, with distinct names. Each profile has an id, positive revision, name, positive requestBodyInspectionLimitBytes, ruleIds and limits. A policy’s request body inspection limit is clamped to its profile’s requestBodyInspectionLimitBytes. Omitted body inspection and work limits use the engine defaults in Facts and limits. A route’s profile choice applies to every participating ruleset. Profiles contain no score threshold.
Exclusion rulesets require empty profiles and rules arrays. They refer to rules in another ruleset and apply only through route opt-in.
Rules
A rule has a positive id and revision, a message of at most 500 characters, a description of at most 2,000 characters and a lowercase identifier category, such as sql-injection. Rule identity is the pair of ruleset ID and rule ID, so custom rules can use small positive IDs.
severity sets the rule's score: Critical 5, Error 4, Warning 3 or Notice 2. paranoiaLevel is 1–4 and defaults to 1. action defaults to Score; a Challenge rule still declares a severity but contributes zero at runtime. See Scoring and integrity tests.
inspectionStage is RequestMetadata, RequestBody, WebSocketMessage or Response. A rule has 1–16 conditions; their targets must belong to that stage. tags label rules for review and exclusions. diagnosticMetadata carries bounded descriptive key/value pairs.
Rule provenance includes kind, source and license. Original records original work. OwaspCrsAdapted also requires sourceVersion, sourceRuleId and sourceUri. PublishedTechniqueDerived requires sourceUri.
A complete custom ruleset
This compact adaptation of the editor’s starter ruleset scores a query value containing <script, ignoring case. Both profiles use default work limits. The two integrity vectors check a matching and a clean query. It is a syntax example, not a replacement for an XSS ruleset. It shows the published document; in a draft, leave out the six fields Clearplane manages.
{
"rulesetId": "custom",
"version": "1.0.0",
"schemaVersion": 1,
"kind": "Application",
"minimumClearplaneVersion": "1.0.0-alpha9",
"releasedAt": "2026-09-12T00:00:00+00:00",
"provenance": {
"source": "Operator",
"license": "Proprietary"
},
"profiles": [
{
"id": "standard",
"revision": 1,
"name": "Standard",
"ruleIds": [
1
],
"limits": {}
},
{
"id": "management",
"revision": 1,
"name": "Management",
"ruleIds": [
1
],
"limits": {}
}
],
"rules": [
{
"id": 1,
"revision": 1,
"message": "Custom inspection example",
"description": "A small example for the WAF rule language reference.",
"category": "custom",
"severity": "Critical",
"paranoiaLevel": 1,
"action": "Score",
"provenance": {
"kind": "Original",
"source": "Operator",
"license": "Proprietary"
},
"inspectionStage": "RequestMetadata",
"conditions": [
{
"targets": [
{
"target": "QueryValue"
}
],
"operator": {
"kind": "Contains",
"value": "<script"
},
"transformations": [
"Lowercase"
]
}
]
}
],
"integrityTests": [
{
"id": "script-query",
"profileId": "standard",
"fields": [
{
"target": "QueryValue",
"name": "q",
"value": "<SCRIPT>alert(1)</SCRIPT>"
}
],
"expectedMatchedRuleIds": [
1
]
},
{
"id": "clean-query",
"profileId": "management",
"fields": [
{
"target": "QueryValue",
"name": "q",
"value": "hello"
}
],
"expectedMatchedRuleIds": []
}
]
}