DEV Community

Cover image for Simple Alternative Method to Pass ARD Manifest Validation in Google PageSpeed Insights & Lighthouse
Raddito
Raddito

Posted on Edited on

Simple Alternative Method to Pass ARD Manifest Validation in Google PageSpeed Insights & Lighthouse

If you've recently tested your website using Google PageSpeed Insights or Lighthouse, you may have noticed a new check under the Agentic Browsing category called β€œARD manifest is valid.”

Here's a quick way to satisfy this validation using a minimal JSON file, without installing plugins or configuring complex agentic services.

βœ… How to implement it

Step 1: Log in to your website's hosting control panel (cPanel, DirectAdmin, or similar).

Step 2: Open File Manager and navigate to your website's document root, typically:

public_html/

Step 3: Look for a folder named:

.well-known

If this folder doesn't exist, create a new folder with exactly that name, including the dot (.) at the beginning.

πŸ’‘ Tip: Enable β€œShow Hidden Files” in File Manager if you cannot see the .well-known folder.

Step 4: Inside the .well-known folder, create a file named:

ard.json

Your final file path should look like this:

public_html/.well-known/ard.json

Step 5: Open the file and paste the following JSON:

{
  "entries": []
}
Enter fullscreen mode Exit fullscreen mode

Save the file.

Step 6: Open the following URL in your browser:

https://yourdomain.com/.well-known/ard.json

Replace yourdomain.com with your actual domain.

You should see the JSON content without a 404, 403, or other error.

Step 7: Run your website through PageSpeed Insights or Lighthouse again and check the ARD manifest validation result.

βœ… When should you use this method?

This simple approach is suitable when:

  • Your website does not currently publish any AI-agent tools, MCP servers, A2A agents, or other agentic resources.
  • You want to provide a minimal, structurally valid ARD manifest.
  • You're testing or experimenting with Lighthouse's Agentic Browsing audit.
  • You manage a regular blog, portfolio, business website, or informational website without agentic services.

The empty entries array is allowed by the current ARD manifest schema and can pass Lighthouse's validation.

❌ When should you NOT use this method?

Avoid this shortcut when:

  • Your website already provides actual AI-agent capabilities that should be discoverable.
  • You already have a properly configured ARD manifest.
  • You are developing an MCP server, A2A agent, agentic API, or agent discovery platform.
  • Your objective is to make real resources discoverable by AI agents.

For these cases, you should create a proper ARD manifest with resource identifiers, names, media types, endpoints, and relevant discovery information.

An empty manifest does not advertise any resources. It only provides a valid manifest structure.

⚠️ When might this method NOT work?

Even with correct JSON, validation may fail or the audit may not recognize your file if:

  • The file is uploaded to the wrong document root.
  • The .well-known directory is inaccessible or blocked by hosting security rules.
  • The file returns HTTP 403, 404, 500, or another unsuccessful response.
  • A CDN, firewall, or security plugin prevents Lighthouse from fetching it.
  • Your website advertises another ARD manifest URL containing invalid JSON, which Lighthouse checks first.
  • Your Lighthouse version is older and only searches the legacy ai-catalog.json location.
  • A future specification or validation update changes the accepted structure.

If your website uses a custom document root or a different hosting architecture, place the file wherever it becomes publicly accessible at /.well-known/ard.json.

πŸ” Technical context: What is ARD?

ARD stands for Agentic Resource Discovery.

Google announced the ARD specification on June 17, 2026, to help AI agents and registries discover and verify capabilities published across the web.

ARD can describe resources such as MCP servers, A2A agents, agent skills, and other tools or services.

An ARD manifest is normally published at:

/.well-known/ard.json

The ARD v0.91 specification, dated August 26, 2026, requires a top-level entries array but does not require that array to contain any entries.

Lighthouse support:

  • Lighthouse 13.5.0: Introduced the ARD schema audit, initially using the older ai-catalog.json discovery location.
  • Lighthouse 13.6.0 (October 27, 2026): Updated the audit to ARD v0.91, supporting ard.json and rel="ard" while retaining legacy compatibility.

This explains why an empty entries array can pass schema validation: it is a valid array containing zero resource declarations.

The historical details and discovery paths are documented in the Lighthouse 13.6.0 release notes, the ARD specification, and Google's ARD announcement.

πŸ’‘ Important clarification

Passing the ARD manifest audit does not mean:

  • Your website is fully AI-agent-ready.
  • AI agents can automatically interact with your website.
  • Your website will rank higher in Google Search.
  • Your overall PageSpeed performance score will increase.

Also, if no ARD manifest is published or advertised, Lighthouse may simply mark the audit as Not Applicable, which is not necessarily an error.

This method is useful for basic manifest validation, not as a substitute for actual agentic resource discovery.

Sometimes, a two-line JSON file is enough to satisfy a technical validation check. Just understand what you're validating! πŸš€

Top comments (0)