XooCode(){

SearchAction

SearchAction is an Action subtype representing a search. On its own it is abstract, but embedded inside a WebSite entity via potentialAction, it declares the site's internal search. Google used it for the sitelinks search box, a search field under a site's listing, until it retired that feature in November 2024. This is the most widely implemented Action type in structured data.

The type hierarchy is Thing → Action → SearchAction. SearchAction has 1 property of its own: query (the search text). But the real implementation is on the target property (inherited from Action), which uses an EntryPoint with a URL template containing a {search_term_string} placeholder. Google replaces the placeholder with the user's query.

Full example of schema.org/WebSite json-ld markup

The markup is verified as valid with Rich Results Test from Google.

Highlight legend:Required by GoogleRecommendedOptional
schema.org/WebSite
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "@id": "https://xoocode.com#website",
  "name": "XooCode",
  "url": "https://xoocode.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://xoocode.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}
</script>

The WebSite + potentialAction pattern

The standard placement is as a potentialAction on a WebSite entity on the homepage. The WebSite needs @type, url, and name. The SearchAction needs target with a URL template and query-input declaring the parameter name. This three-part structure (WebSite, SearchAction, target) is the pattern consumers expect.

target and query-input

target is the search URL template: https://xoocode.com/search?q={search_term_string}. The {search_term_string} placeholder is replaced by Google with the user's query. query-input declares the parameter: "required name=search_term_string". The "required" keyword means the search box must have a value before submitting. The name must match the placeholder in the URL template.

When it works and when it does not

Your site needs a working search page at the target URL, and the markup belongs on the homepage, where site-level structured data lives.

Minimal valid version

The smallest markup that still produces a valid WebSite entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/WebSite (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "XooCode",
  "url": "https://xoocode.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://xoocode.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}
</script>

Google rich results this unlocks

Markup matching this example makes your page eligible for the following Google Search rich results. The primary target drives the required / recommended property classification in the advanced code block above.

  • Sitelinks search box (retired by Google in 2024)primary
    Google docs

Common WebSite mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

  1. 01

    target as a plain URL string

    Wrong
    "target": "https://xoocode.com/search?q={search_term_string}"
    Right
    "target": { "@type": "EntryPoint", "urlTemplate": "https://xoocode.com/search?q={search_term_string}" }

    Google's current documentation requires target to be an EntryPoint object with urlTemplate. A plain string used to work but is deprecated. Use the EntryPoint structure to be safe.

  2. 02

    Placeholder name mismatch

    Wrong
    "urlTemplate": "https://xoocode.com/search?q={query}"
"query-input": "required name=search_term_string"
    Right
    The placeholder in urlTemplate must match the name in query-input

    The placeholder {search_term_string} in the URL template must exactly match the name declared in query-input. If one says {query} and the other says name=search_term_string, Google cannot wire them together. Use the same name in both places.

  3. 03

    SearchAction on an interior page instead of the homepage

    Wrong
    WebSite + SearchAction markup on /about or /blog
    Right
    Place it only on the homepage (/)

    The homepage is the canonical source for site-level structured data, so WebSite + SearchAction belongs there, not repeated on interior pages.

  4. 04

    SearchAction without a WebSite wrapper

    Wrong
    Standalone SearchAction block with no WebSite parent
    Right
    SearchAction must be a potentialAction inside a WebSite entity

    Google does not read SearchAction as a standalone block. It must be nested inside a WebSite's potentialAction. Without the WebSite wrapper, Google has no site to attach the search box to.

Schema properties in this example

SearchActionWebSitepotentialActiontargetEntryPointurlTemplatequery-inputnameurl

Also mentioned in 5 other examples

WebSite also appears in InteractionCounter, PropertyValueSpecification, SearchAction, WebContent, and WebSite. See the full WebSite schema page for every reference.

About the example data

The xoocode.com site search, embedded in the WebSite entity on the homepage. The target URL sends queries to the search results page. This is a standalone deep-dive on SearchAction; the WebSite example shows it in the broader WebSite context.

Comments

Loading comments...

Leave a comment