Api Security Rate Policy Structure

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akamai-api-security/refs/heads/main/json-structure/api-security-rate-policy-structure.json",
  "name": "rate-policy",
  "description": "Contains details about a rate policy.",
  "type": "object",
  "properties": {
    "additionalMatchOptions": {
      "description": "The list of additional match conditions.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "positiveMatch": {
            "description": "Whether the condition should trigger on a match (`true`) or a lack of match (`false`).",
            "type": "boolean"
          },
          "type": {
            "description": "The match condition type. The `RequestHeaderCondition` listed here is deprecated. Specify `RequestHeaderCondition` as an `atomicCondition` to match on request headers. See [Export match condition type values](https://techdocs.akamai.com/application-security/reference/cndval).",
            "enum": [
              "IpAddressCondition",
              "NetworkListCondition",
              "RequestHeaderCondition",
              "RequestMethodCondition",
              "ResponseHeaderCondition",
              "ResponseStatusCondition",
              "UserAgentCondition",
              "AsNumberCondition"
            ],
            "type": "string"
          },
          "values": {
            "description": "The list of values that trigger the condition on match.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "type",
          "positiveMatch",
          "values"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "apiSelectors": {
      "description": "The API endpoints to match in incoming requests. This only applies to the `api` `matchType`.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "apiDefinitionId": {
            "description": "Uniquely identifies each API endpoint.",
            "type": "int32"
          },
          "definedResources": {
            "description": "When `true`, match on any resource explicitly added to your API definition without including a `resourceId`. When `false`, you'll need to pass a `resourceId`.",
            "type": "boolean"
          },
          "resourceIds": {
            "description": "The unique identifiers of the endpoint's resources.",
            "items": {
              "type": "int32"
            },
            "type": "array"
          },
          "undefinedResources": {
            "description": "When `true`, match on any resource you have not explicitly added to your API definition without including a `resourceId`.  When `false`, you'll need to pass a `resourceId`.",
            "type": "boolean"
          }
        },
        "required": [
          "apiDefinitionId"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "averageThreshold": {
      "description": "The allowed hits per second during any two-minute interval.",
      "minimum": 1,
      "type": "int32"
    },
    "bodyParameters": {
      "description": "The list of body parameters to match on.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "name": {
            "description": "The name you assign to a body parameter.",
            "type": "string"
          },
          "positiveMatch": {
            "description": "Whether the condition should trigger on a match (`true`) or a lack of match (`false`).",
            "type": "boolean"
          },
          "valueInRange": {
            "description": "Whether to match a value inside or outside a range. The range format is `min:max` \u2014 for example, `2:4`.",
            "type": "boolean"
          },
          "values": {
            "description": "The body parameter values.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "name",
          "values",
          "positiveMatch"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "burstThreshold": {
      "description": "The allowed hits per second during any five-second interval.",
      "minimum": 1,
      "type": "int32"
    },
    "burstWindow": {
      "description": "The time span for the `burstThreshold` interval. For existing rate policies, analyze your traffic in Alert mode before you reduce the measure window from 5 seconds. [Learn more about thresholds here](https://techdocs.akamai.com/kona-site-defender/docs/rate-thresholds).",
      "maximum": 5,
      "minimum": 1,
      "type": "int32"
    },
    "clientIdentifier": {
      "description": "The client identifier you want to use to identify and track request senders. The value is required only for WAF type, and `api-key` is supported only for API match criteria. Using `ip-useragent` is typically more specific than using `ip` alone when trying to identify a client. Tracking by `cookie:value` applies to requests per individual session, even if the IP address changes.",
      "enum": [
        "api-key",
        "ip-useragent",
        "ip",
        "cookie:value"
      ],
      "type": "string"
    },
    "condition": {
      "additionalProperties": false,
      "description": "Contains information about the criteria that trigger the rate policy.",
      "properties": {
        "atomicConditions": {
          "description": "The conditions that trigger the rate policy. Specify one or more request headers, TLS fingerprints, or client reputation categories.",
          "items": {
            "oneOf": [
              {
                "additionalProperties": false,
                "description": "Collects data needed for condition matches on request headers.",
                "properties": {
                  "className": {
                    "description": "The type of condition. The `RequestHeaderCondition` type checks for a header from the requesting client and determines if it matches a provided header. This subtype supports the `?` wildcard to match any single character and the `*` wildcard to match any sequence of 0 or more characters. You can also match on case sensitivity.",
                    "enum": [
                      "RequestHeaderCondition"
                    ],
                    "type": "string"
                  },
                  "name": {
                    "description": "A header name. Use `name` to check whether the specified header exists.",
                    "items": {
                      "minLength": 1,
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array",
                    "uniqueItems": true
                  },
                  "nameWildcard": {
                    "description": "Whether to interpret `?` and `*` as wildcards.",
                    "type": "boolean"
                  },
                  "positiveMatch": {
                    "description": "Whether the condition triggers on a match or lack of match.",
                    "type": "boolean"
                  },
                  "value": {
                    "description": "A list of unique header values. Use both `value` and `name` to check whether the requesting client\u2019s header matches a provided header.",
                    "items": {
                      "minLength": 1,
                      "type": "string"
                    },
                    "nullable": true,
                    "type": "array",
                    "uniqueItems": true
                  },
                  "valueCase": {
                    "description": "Whether to consider the case sensitivity of the provided header values.",
                    "type": "boolean"
                  },
                  "valueWildcard": {
                    "description": "Whether to interpret `?` and `*` as wildcards.",
                    "type": "boolean"
                  }
                },
                "required": [
                  "className",
                  "name"
                ],
                "name": "RequestHeaderCondition",
                "type": "object",
                "x-akamai": {
                  "file-path": "schemas/request-header-condition-2.yaml"
                }
              },
              {
                "additionalProperties": false,
                "description": "Collects data needed for condition matches on TLS fingerprints.",
                "properties": {
                  "className": {
                    "description": "The type of condition. In this case, `TlsFingerprintCondition`.",
                    "enum": [
                      "TlsFingerprintCondition"
                    ],
                    "type": "string"
                  },
                  "positiveMatch": {
                    "description": "Whether the condition triggers on a match or lack of match.",
                    "type": "boolean"
                  },
                  "value": {
                    "description": "A list of unique TLS fingerprints.",
                    "items": {
                      "minLength": 1,
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array",
                    "uniqueItems": true
                  }
                },
                "required": [
                  "className",
                  "value"
                ],
                "name": "TlsFingerprintCondition",
                "type": "object",
                "x-akamai": {
                  "file-path": "schemas/tls-fingerprint-condition.yaml"
                }
              },
              {
                "additionalProperties": false,
                "description": "Collects data needed for condition matches on Client Reputation.",
                "properties": {
                  "className": {
                    "description": "The type of condition. In this case, `ClientReputationCondition`.",
                    "enum": [
                      "ClientReputationCondition"
                    ],
                    "type": "string"
                  },
                  "name": {
                    "description": "Identifies the reputation category. Web scrapers (`WEBSCRP`) crawl sites and collect data like hotel rates, product prices, store locations, and more. DoS attackers (`DOSATCK`) are web clients or botnets that use automated tools to launch volumetric Denial of Service (DoS) attacks. Web attackers (`WEBATCK`) target websites and web apps with techniques like SQL injection, remote file inclusion, or cross-site scripting. Scanning tools (`SCANTL`) probe web apps for vulnerabilities during an attack's reconnaissance phase.",
                    "items": {
                      "enum": [
                        "WEBSCRP",
                        "DOSATCK",
                        "WEBATCK",
                        "SCANTL"
                      ],
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array",
                    "uniqueItems": true
                  },
                  "positiveMatch": {
                    "description": "Whether the condition triggers on a match or lack of match.",
                    "type": "boolean"
                  },
                  "sharedIpHandling": {
                    "description": "Identifies the IP sharing. Either `NON_SHARED`, `SHARED_ONLY`, `BOTH`.",
                    "enum": [
                      "NON_SHARED",
                      "SHARED_ONLY",
                      "BOTH"
                    ],
                    "type": "string"
                  },
                  "value": {
                    "description": "Threshold value that causes the trigger.",
                    "maximum": 10,
                    "minimum": 1,
                    "type": "double"
                  }
                },
                "required": [
                  "className",
                  "name",
                  "value",
                  "sharedIpHandling"
                ],
                "name": "ClientReputationCondition",
                "type": "object",
                "x-akamai": {
                  "file-path": "schemas/client-reputation-condition.yaml"
                }
              }
            ]
          },
          "minItems": 1,
          "type": "array"
        },
        "positiveMatch": {
          "description": "Whether the condition should trigger on a match (`true`) or a lack of match (`false`).",
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "counterType": {
      "default": "per_edge",
      "description": "The rate policy counter type. Either `per_edge` for rate limiting to work per edge node, or `region_aggregated` for rate limiting to work using aggregated rate accounting across multiple edge nodes.",
      "enum": [
        "per_edge",
        "region_aggregated"
      ],
      "type": "string"
    },
    "createDate": {
      "description": "__Read-only__ The time stamp when you created the rate policy.",
      "example": "2016-07-22 18:57:08.0",
      "readOnly": true,
      "type": "datetime"
    },
    "description": {
      "description": "Descriptive text you provide about a policy.",
      "type": "string"
    },
    "evaluation": {
      "additionalProperties": false,
      "description": "Contains details about rate policy evaluation.",
      "properties": {
        "averageThreshold": {
          "description": "The allowed hits per second during any two-minute interval during evaluation.",
          "minimum": 1,
          "type": "int32"
        },
        "burstThreshold": {
          "description": "The allowed hits per second during any five-second interval during evaluation.",
          "minimum": 1,
          "type": "int32"
        },
        "burstWindow": {
          "description": "__Read-only__ The time span for the `burstThreshold` interval used during evaluation. This value is always set to the `burstWindow` specified by the main rate policy.",
          "readOnly": true,
          "type": "int32"
        },
        "counterType": {
          "default": "region_aggregated",
          "description": "The evaluation rate policy counter type. Either `per_edge` for rate limiting to work per edge node, or `region_aggregated` for rate limiting to work using aggregated rate accounting across multiple edge nodes.",
          "enum": [
            "per_edge",
            "region_aggregated"
          ],
          "type": "string"
        },
        "endDate": {
          "description": "__Read-only__ The time stamp when evaluation ends.",
          "readOnly": true,
          "type": "datetime"
        },
        "evaluationId": {
          "description": "__Read-only__ Uniquely identifies an evaluation.",
          "readOnly": true,
          "type": "int32"
        },
        "evaluationStatus": {
          "description": "__Read-only__ Reflects evaluation status, either `in_progress`, `pending_activation`, or `completed`.",
          "enum": [
            "in_progress",
            "pending_activation",
            "completed"
          ],
          "readOnly": true,
          "type": "string"
        },
        "startDate": {
          "description": "__Read-only__ The time stamp when evaluation starts.",
          "readOnly": true,
          "type": "datetime"
        },
        "version": {
          "description": "__Read-only__ Evaluation version.",
          "readOnly": true,
          "type": "int32"
        }
      },
      "required": [
        "averageThreshold",
        "burstThreshold"
      ],
      "type": "object"
    },
    "fileExtensions": {
      "additionalProperties": false,
      "description": "Contains the file extension match criteria.",
      "properties": {
        "positiveMatch": {
          "description": "Whether the condition should trigger on a match (`true`) or a lack of match (`false`).",
          "type": "boolean"
        },
        "values": {
          "description": "The file extensions to match on.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "positiveMatch",
        "values"
      ],
      "type": "object"
    },
    "hostnames": {
      "description": "__Deprecated__. The hostnames to match. This array member is deprecated. Use the `hosts` object instead.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "hosts": {
      "additionalProperties": false,
      "description": "The hostnames to match, and whether to trigger on a match or absence of match.",
      "properties": {
        "positiveMatch": {
          "default": true,
          "description": "When `true`, triggers on hostnames that match any hostnames in this array. When `false`, triggers on hostnames that don't match any in this array.",
          "type": "boolean"
        },
        "values": {
          "description": "The hostnames you choose to match, or specifically not match.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "positiveMatch",
        "values"
      ],
      "type": "object"
    },
    "id": {
      "description": "__Read-only__ Uniquely identifies each rate policy.",
      "readOnly": true,
      "type": "int32"
    },
    "matchType": {
      "description": "The match type in a rate policy. Either `path` to match website paths or `api` to match API paths.",
      "enum": [
        "path",
        "api"
      ],
      "type": "string"
    },
    "name": {
      "description": "The name you assign to a rate policy.",
      "type": "string"
    },
    "path": {
      "additionalProperties": false,
      "description": "Contains details about the path match criteria.",
      "properties": {
        "positiveMatch": {
          "description": "Whether the condition should trigger on a match (`true`) or a lack of match (`false`).",
          "type": "boolean"
        },
        "values": {
          "description": "The list of paths to match on.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "positiveMatch",
        "values"
      ],
      "type": "object"
    },
    "pathMatchType": {
      "description": "The type of paths to match in incoming requests. Either `AllRequests` to match an empty path or any path that ends in a trailing slash (`/`), `TopLevel` to match top-level hostnames only, or `Custom` to match a specific path or path component. This applies only when the corresponding `matchType` member is `path`.",
      "enum": [
        "AllRequests",
        "TopLevel",
        "Custom"
      ],
      "type": "string"
    },
    "pathUriPositiveMatch": {
      "description": "Whether the condition should trigger on a match (`true`) or a lack of match (`false`).",
      "type": "boolean"
    },
    "queryParameters": {
      "description": "The list of query parameter objects to match on.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "name": {
            "description": "The query parameter name.",
            "type": "string"
          },
          "positiveMatch": {
            "description": "Whether the condition should trigger on a match (`true`) or a lack of match (`false`).",
            "type": "boolean"
          },
          "valueInRange": {
            "description": "Whether to match a value inside or outside a range. The range format is `min:max` \u2014 for example, `2:4`.",
            "type": "boolean"
          },
          "values": {
            "description": "The list of query parameter values.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "name",
          "values",
          "positiveMatch"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "requestType": {
      "description": "The type of requests to count towards the rate policy's thresholds. Either `ClientRequest` to count client requests to edge servers, `ClientResponse` to count edge responses to the client, `ForwardResponse` to count origin responses to the client, or `ForwardRequest` to count edge requests to your origin.",
      "enum": [
        "ClientRequest",
        "ClientResponse",
        "ForwardResponse",
        "ForwardRequest"
      ],
      "type": "string"
    },
    "sameActionOnIpv6": {
      "description": "Whether to apply the same action to the IPv6 traffic as to the IPv4 traffic.",
      "type": "boolean"
    },
    "type": {
      "description": "The rate policy type. Either `WAF` for Web Application Firewall, or `BOTMAN` for Bot Manager.",
      "enum": [
        "WAF",
        "BOTMAN"
      ],
      "type": "string"
    },
    "updateDate": {
      "description": "__Read-only__ The ISO 8601 timestamp when you last updated the rate policy.",
      "example": "2017-02-22 00:05:41.0",
      "readOnly": true,
      "type": "datetime"
    },
    "useXForwardForHeaders": {
      "description": "Whether to check the contents of the `X-Forwarded-For` header in incoming requests.",
      "type": "boolean"
    },
    "used": {
      "description": "__Read-only__ Whether you're currently using the rate policy.",
      "readOnly": true,
      "type": "boolean"
    }
  },
  "required": [
    "matchType",
    "type",
    "name",
    "averageThreshold",
    "burstThreshold",
    "clientIdentifier",
    "requestType",
    "sameActionOnIpv6",
    "pathMatchType"
  ],
  "additionalProperties": false
}