Understand JSON cache files

POM Cache stores progressive archive responses as real .json files. The directory layout separates sites, locales, archive configurations, and batches so one public URL resolves to one deterministic file.

Base directory

With the default Cache Location, the JSON tree begins at:

wp-content/cache/pom-cache-json/

Static HTML uses a different sibling directory:

wp-content/cache/pom-cache/

Changing POM Cache → Advanced → Storage → Cache Location moves the base cache location for both systems, while their pom-cache and pom-cache-json subdirectories remain separate.

Site namespace

The next directory identifies the current site's public home:

pom-cache-json/example.com/

For a subdirectory installation, the site path becomes additional safe path segments:

pom-cache-json/example.com/shop/

This namespace is why a current-site purge does not intentionally traverse another site's tree. Domain-mapped sites use the host from that site's configured home URL.

Standard progressive archive path

A standard archive batch follows this pattern:

archive/<post-type>/<context-hash>/page-<page>-ppp-<items>.json

For example:

wp-content/cache/pom-cache-json/example.com/
└── archive/
    └── product/
        └── 8c31c19b2e8d/
            ├── page-1-ppp-12.json
            ├── page-2-ppp-12.json
            └── page-3-ppp-12.json

The exact hash is generated from the archive context. It prevents a response created for one template or archive configuration from being mistaken for another.

The page filename records both the requested page and the expected items per page. If the current archive settings no longer match those values, POM Theme does not accept the path as a valid cache hit.

Split-by-term path

An archive that loads separate taxonomy groups adds the taxonomy and term slug:

archive/<post-type>/<context-hash>/<taxonomy>/<term-slug>/page-<page>-ppp-<items>.json

Example:

archive/dish/42b5d8/menu-section/starters/page-2-ppp-8.json

These segments let different term sections maintain independent batches. A normal automatic post or term invalidation still clears the complete current-site JSON tree because one edit may affect several sections and contexts.

Locale prefix

When the public archive URL uses a locale prefix, the same prefix appears before archive:

es/archive/product/<context-hash>/page-2-ppp-12.json

This keeps localized HTML fragments and navigation data from sharing one file across languages.

The unprefixed locale has no extra locale directory. The prefix comes from the current public language URL, not from a manually chosen folder name.

Public URL and stored path

The public route:

/es/pom-json/archive/product/<context-hash>/page-2-ppp-12.json

maps to a cache-relative path:

es/archive/product/<context-hash>/page-2-ppp-12.json

and, with the default location, to a file similar to:

wp-content/cache/pom-cache-json/example.com/es/archive/product/<context-hash>/page-2-ppp-12.json

The optional REST-shaped route resolves to the same cache-relative structure. The public route prefix itself is not stored as a directory.

Path and content safeguards

POM Cache accepts only normalized paths that:

• end in .json;
• contain letters, digits, underscores, hyphens, periods, and forward-slash separators;
• contain no backslashes, null bytes, .., duplicate slashes, or empty path segments;
• remain below the current site's JSON directory.

It also refuses empty responses, invalid JSON, unreadable files, and files larger than Maximum JSON file size.

Writes are completed through a temporary file and then moved into place. Visitors should therefore see either the previous complete file or the new complete file, not a partially written response.

Do not edit cache files

Treat the JSON tree as disposable output. Manual edits can be overwritten and may create content that no longer matches the context encoded in the URL.

To change what an archive returns:

1. Update the source post, term, translation, or template setting;
2. Clear the affected JSON cache;
3. Request the archive batch again;
4. Verify the regenerated response.

Use Progressive JSON Cache Contents to monitor the number and aggregate size of current-site .json files. See Monitor JSON cache size for a storage plan and Clear the JSON cache manually for the supported deletion control.