Action schemas: what the check tests and how to fix it

Weight 1. Counts crawled pages whose top-level JSON-LD has potentialAction or is a SearchAction or OrderAction. 33 points a page, capped at 100.

Agent Protocols · Weight 1 in the w2agent Score

How common is it?

9% of 1223 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

For each page the audit crawled (the homepage plus up to nine more), it parses every <script type="application/ld+json"> block that is valid JSON. Blocks that do not parse are dropped silently. A page counts as having an action schema when at least one parsed top-level value is an object that either:

  • has a potentialAction member that is not undefined, whatever its contents, or
  • has "@type" equal to the exact string "SearchAction" or "OrderAction".

The score is the number of such pages times 33, capped at 100.

Pages with an actionScoreStatus
00Fail
133Pass
266Pass
399Pass
4 or more100Pass

So any single page is a pass, but a score of 33 means the weighted contribution is a third of full marks. The check does not validate the action. An empty "potentialAction": {} counts. It reads nothing else. These are not seen: an action inside an @graph array, a JSON-LD block whose top level is an array, a potentialAction written in microdata or RDFa, and any other action type such as ReserveAction or BuyAction used as the block's own @type.

Why it matters to agents

schema.org defines potentialAction as indicating "a potential Action, which describes an idealized action in which this thing would play an 'object' role", and SearchAction and OrderAction as types under Action. An EntryPoint with a urlTemplate (an RFC 6570 template) is how the vocabulary says a target is constructed. So the markup can state, in machine-readable form, how to search your site.

The evidence on use is thin. The most common reason sites carry a SearchAction is Google's sitelinks search box, and Google's documentation updates say that documentation was removed in November 2024 because the feature is no longer available. Google's guide to generative AI search says there is no special schema.org markup you need to add. No source fetched for this page says an AI assistant or browser agent reads potentialAction and executes it. For acting on a page, the experimental WebMCP proposal uses form attributes and script registration instead; see WebMCP declarative.

Treat this as inexpensive, harmless markup with an unproven audience, not as a lever.

How to fix it

Only if the action is real, such as a working search URL:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://example.com/",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://example.com/search?q={search_term_string}"
    }
  }
}
</script>
  • Put it in a top-level object, not inside @graph, so the audit sees it. A @graph page is valid JSON-LD but invisible here.
  • Add it to the homepage and any template that really supports the action. Four pages reach 100.
  • Make sure the URL works. Nothing in this check tests it.
  • Run the page through your validator of choice; schema.org validity checks that blocks have a schema.org context and a string @type.

Related: structured forms covers the HTML forms behind a search action, and schema.org for AI gives background.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →