Skip to main content

Release 1.12.0

Release Date: May 7, 2026

info

This release introduces list references — named lists of values that can be defined once and referenced across match conditions using {"{{list.<key>}}"} syntax. Lists can be defined locally in a tenant config or shared across tenants via a common config file.

New Features -> Top-Level Configuration​

Lists​

A new top-level lists property lets you define named lists of string values and reference them in any match condition. This avoids duplicating the same values across multiple rules and makes it easy to update them in one place.

Properties:

  • lists: An object where each key is a list name and the value is an array of strings
  • Lists are optional — existing configs without lists continue to work unchanged
{
  "lists": {
    "blocked_ips": ["192.0.2.0/24", "198.51.100.0/24"],
    "api_paths": ["/api/v1/*", "/api/v2/*"],
    "bot_agents": ["python-requests/2.28", "curl/7.88"]
  },
  "delivery_config": { ... }
}

View Schema Definition

New Features -> Match Conditions​

List References in Match Values​

All match conditions now accept {{list.<key>}} references wherever string values or arrays are used. When the EdgeWorker evaluates a rule, each list reference is expanded to the array of values defined in lists.

List references work in three contexts:

Standalone string — the entire match value is a list reference:

{
  "matchAll": {
    "ipv4": "{{list.blocked_ips}}"
  }
}

Mixed array — list references and inline values in the same array, merged at evaluation time:

{
  "matchAll": {
    "ipv4": ["{{list.blocked_ips}}", "203.0.113.0/24"],
    "paths": ["{{list.api_paths}}", "/health"]
  }
}

Header/query objects — list references as values in header or query parameter maps:

{
  "matchAll": {
    "reqheader": {
      "User-Agent": "{{list.bot_agents}}"
    }
  }
}

List references are supported in all match condition types: paths, IP addresses, headers, query parameters, geographic conditions, cookies, extensions, ASN, and more. Both positive and negated forms (e.g., ipv4 and !ipv4) support list references.

If a referenced list key does not exist, the reference resolves to an empty array and the condition will not match.

Example: List Reference Match

New Features -> Common Configuration​

Shared Lists via Common Config​

Lists can also be defined in a shared common config file (common.json) that is fetched alongside each tenant's config. This lets you maintain organization-wide lists (e.g., blocked IPs, known bot user agents) in one place and share them across all tenants.

How it works:

  1. Enable common config by setting PMUSER_TENANT_COMMON to "true" in Property Manager
  2. Create a common.json file with a lists property, stored alongside tenant configs
  3. Reference common lists in tenant configs using the same {{list.<key>}} syntax

Precedence: When both the tenant config and common config define a list with the same key, the local tenant list takes precedence. This allows tenants to override shared lists when needed.

Failure handling: By default, if common.json is unavailable (404, 500, or timeout), execution stops (fail closed) and PMUSER_COMMON_CODE is set with the error code. Property Manager can use this variable to serve a custom error page.

To continue processing when common config fails (fail open), set PMUSER_FAIL_OPEN to "true" in Property Manager. In fail-open mode, list references that depend on common lists resolve to empty arrays, and local tenant lists still work.

Common config errors are always recorded in PMUSER_COMMON_CODE (separate from PMUSER_TENANT_CODE), regardless of fail-open/fail-closed mode.

info

Common config requires the PMUSER_TENANT_COMMON PM variable to be set to "true". Contact your Akamai team for help enabling this in your Property Manager configuration.

PM Variables:

  • PMUSER_TENANT_COMMON: Set to "true" to enable common config fetching (case-insensitive; accepts "true" or "t")
  • PMUSER_COMMON_KEY_OVERRIDE: Override the common config filename (defaults to "common")
  • PMUSER_FAIL_OPEN: Set to "true" to continue processing when common config fails (default: fail closed)
  • PMUSER_COMMON_CODE: Set automatically when common config fetch fails (e.g., API:Err:404, API:Err:500)

Schema Changes​

  • Added lists top-level property — object with string array values for named list definitions
  • Added {{list.<key>}} pattern as a valid match value across all match conditions
  • Added three shared schema definitions (match_value_string, match_value_paths, match_value_header) for list reference validation
  • Refactored all match condition value schemas to use $ref references to shared definitions (no user-facing behavior change — existing configs remain valid)
  • Added {{list.<key>}} support to query_exists and !query_exists conditions

Migration Guide​

info

All changes are backward compatible. No breaking changes were introduced.

1. Consider Using Lists for Repeated Values​

If your tenant config repeats the same IP ranges, paths, or header values across multiple rules, extract them into named lists:

// Before — values repeated in multiple rules
{
  "delivery_config": {
    "version": "1.0",
    "onClientRequest": {
      "features": {
        "respondWith": {
          "rules": [{
            "matchAll": { "ipv4": ["192.0.2.0/24", "198.51.100.0/24"] },
            "args": { "status": 403 }
          }]
        },
        "caching": {
          "rules": [{
            "matchAll": { "ipv4": ["192.0.2.0/24", "198.51.100.0/24"] },
            "args": { "ttl_seconds": 0, "no_store": true }
          }]
        }
      }
    }
  }
}

// After — values defined once, referenced everywhere
{
  "lists": {
    "blocked_ips": ["192.0.2.0/24", "198.51.100.0/24"]
  },
  "delivery_config": {
    "version": "1.0",
    "onClientRequest": {
      "features": {
        "respondWith": {
          "rules": [{
            "matchAll": { "ipv4": "{{list.blocked_ips}}" },
            "args": { "status": 403 }
          }]
        },
        "caching": {
          "rules": [{
            "matchAll": { "ipv4": "{{list.blocked_ips}}" },
            "args": { "ttl_seconds": 0, "no_store": true }
          }]
        }
      }
    }
  }
}

2. Explore Common Config for Multi-Tenant Deployments​

If you manage multiple tenants that share the same blocked IPs, bot lists, or path patterns, consider using a common config to maintain those lists centrally.

Resources​

note

Questions or feedback? Please refer to the documentation or contact support.