Skip to main content

Lists

Lists let you define named sets of values and reference them with the {{list.<key>}} syntax, avoiding duplicated IPs, paths, and other values across rules. Lists can be defined in two places:

  • In the tenant config (tenant.json) — scoped to that tenant
  • In a shared common config (common.json) — available to all tenants

If a list with the same key exists in both files, the tenant-level list takes precedence.

View Schema Definition

Defining Lists​

Lists are defined in the top-level lists object. Each key maps to an array of strings.

tenant.json — lists scoped to this tenantJSON
{
"tenant_id": "my-app",
"lists": {
  "blocked_ips": ["192.0.2.0/24", "198.51.100.0/24"],
  "api_paths": ["/api/v1/*", "/api/v2/*"],
  "bot_agents": ["curl/7*", "python-requests*"]
},
"delivery_config": { ... },
"security_config": { ... }
}
common.json — lists shared across all tenantsJSON
{
"lists": {
  "monitoring_paths": ["/health", "/status", "/metrics"],
  "corporate_ips": ["198.51.100.0/24", "203.0.113.0/24"],
  "trusted_asns": ["12345", "67890"]
}
}

Both files use the same lists structure. Any list defined in either file can be referenced with {{list.<key>}} from any tenant config.

Referencing Lists​

Use {{list.<key>}} anywhere a match condition or security exception accepts values. The syntax is the same regardless of whether the list is defined in tenant.json or common.json.

In Delivery Match Conditions​

tenant.jsonJSON
{
"lists": {
  "blocked_ips": ["192.0.2.0/24", "198.51.100.0/24"],
  "api_paths": ["/api/v1/*", "/api/v2/*"]
},
"delivery_config": {
  "version": "1.0",
  "onClientRequest": {
    "features": {
      "respondWith": {
        "rules": [{
          "matchAll": { "ipv4": "{{list.blocked_ips}}" },
          "args": { "status": 403, "body": "Forbidden" }
        }]
      },
      "caching": {
        "rules": [{
          "matchAll": { "paths": "{{list.api_paths}}" },
          "args": { "ttl_seconds": 60 }
        }]
      }
    }
  }
}
}

In Security Exceptions​

tenant.jsonJSON
{
"security_config": {
  "deny_groups": ["SQL-INJECTION-ANOMALY", "REP"],
  "exceptions": {
    "SQL-INJECTION-ANOMALY": {
      "paths": ["{{list.monitoring_paths}}", "/internal/metrics"],
      "v4_ips": ["{{list.corporate_ips}}", "203.0.113.50"]
    },
    "REP": {
      "asn": ["{{list.trusted_asns}}", "55555"]
    }
  }
}
}

List references and inline values can be mixed in the same array — the list entries are expanded and merged with the inline values at runtime. Standalone references (e.g., "v4_ips": "{{list.corporate_ips}}") also work when no inline values are needed.

Mixing with Inline Values​

List references can be combined with inline values in the same array. The list entries are expanded and merged with the inline values.

JSON
{
"matchAll": {
  "ipv4": ["{{list.blocked_ips}}", "203.0.113.0/24"],
  "reqheader": { "User-Agent": "{{list.bot_agents}}" }
}
}

Common Config Setup​

The common config file must be named common.json and hosted alongside your tenant configs. To enable it, set the Property Manager variable PMUSER_TENANT_COMMON to "true". When enabled, the EdgeWorker fetches common.json alongside the tenant config, making shared lists available for {{list.*}} references. If both files define a list with the same name, the tenant-level list takes precedence — common lists are never merged with tenant lists.

Override Behavior​

When a tenant defines a list with the same key as one in common.json, the tenant-level list takes precedence. This lets individual tenants customize shared values without affecting other tenants.

common.json — organization defaultJSON
{
"lists": {
  "trusted_ips": ["198.51.100.0/24"]
}
}
tenant.json — overrides the shared listJSON
{
"lists": {
  "trusted_ips": ["203.0.113.0/24", "198.51.100.50"]
},
"security_config": {
  "deny_groups": ["SQL-INJECTION-ANOMALY"],
  "exceptions": {
    "SQL-INJECTION-ANOMALY": {
      "v4_ips": "{{list.trusted_ips}}"
    }
  }
}
}

Here, {{list.trusted_ips}} resolves to ["203.0.113.0/24", "198.51.100.50"] — the tenant's values, not the common config's.

Quick Reference​

BehaviorDescription
Defined intenant.json (per-tenant) and/or common.json (shared across tenants)
Single ref"{{list.name}}" — field value is replaced by the list entries
Mixed array["{{list.name}}", "/inline"] — list entries expanded and merged with inline values
OverrideTenant-level list wins when both tenant.json and common.json define the same key
Missing listResolves to an empty array — no match / no exception applied
Works inMatch condition values, security exception fields (paths, v4_ips, v6_ips, asn)
Enable common configSet PMUSER_TENANT_COMMON to "true" in Property Manager