Understand JSON cache response headers

The JSON Cache-Control header setting controls how browsers and shared HTTP caches may reuse a progressive archive response after they receive it. It does not decide how long POM Cache keeps the .json file on disk.

Default policy

Open Settings → POM Cache → General → Progressive JSON runtime. The default value is:

public, max-age=30, s-maxage=30, must-revalidate

Its directives mean:

The short default limits downstream staleness while still absorbing bursts of identical archive requests.

Which paths use the setting

PHP early static delivery reads the current setting on each request and sends it directly.

The recommended Apache block embeds the value in the generated text:

Header set Cache-Control "..." env=POM_JSON_CACHE

After you copy that block into .htaccess or a virtual-host configuration, it becomes independent text. Saving a new value in WordPress does not edit the installed Apache configuration. Recopy or update the server block and validate it.

The WordPress-generated response can be affected by the theme, REST API, server, or another caching layer. Inspect the final response instead of assuming every delivery path inherited the same header.

HTTP freshness versus origin-file lifetime

These are separate clocks:

Cache-Control freshness
→ how long a browser/CDN may reuse its copy

POM Cache file lifetime
→ until an automatic or manual origin purge removes it

Setting max-age=0 does not delete the origin file. Setting one day does not make POM Cache remove the file after a day. POM Cache has no age-based JSON expiration.

When content changes, clear the origin JSON through an enabled invalidation or the manual tool. If a CDN already holds the old response, follow the CDN's invalidation or revalidation plan as well.

Choose a policy

Keep the default while validating the site. Change it only with a clear freshness model.

Examples:

Short browser and shared freshness:

public, max-age=30, s-maxage=30, must-revalidate

No fresh reuse without revalidation:

public, max-age=0, s-maxage=0, must-revalidate

Different browser and CDN windows:

public, max-age=30, s-maxage=300, must-revalidate

The final example lets a compatible shared cache reuse the response longer than a browser. Use it only when your invalidation process covers the public JSON paths and your content freshness allows up to that edge window.

Avoid private for a response you expect a CDN to share. Avoid a long immutable policy for archive batches whose posts, terms, prices, or translations can change at a stable URL.

Input safety

POM Cache removes line breaks and double quotes and normalizes whitespace before PHP sends this setting. An empty result falls back to the default policy.

This validation prevents malformed header lines, but it does not decide whether a custom directive combination is appropriate for your CDN. Confirm syntax and behavior with the relevant cache provider.

Compression is a separate concern

PHP early delivery also sends:

Vary: Accept-Encoding

That permits separate encoded variants downstream. POM Cache does not create Brotli or Gzip JSON files; the web server or CDN can compress the response in transit. Read Configure Brotli at CloudFront for that boundary.

Verify a change

1. Save the new JSON Cache-Control header;
2. Clear browser and CDN test state or use a controlled uncached request;
3. Request a known JSON file through PHP early serving;
4. Inspect the final Cache-Control and Vary headers;
5. If Apache delivery is enabled, update its copied rule and repeat;
6. Request through the CDN and inspect both freshness and cache-status headers;
7. Change source content, clear the origin JSON, and verify the public edge does not retain unacceptable stale content.

Do not use a cache-busting query parameter to test POM Cache static delivery: JSON requests with a query string intentionally bypass the static file route. Use the CDN's approved bypass or diagnostic method instead.