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 triggers Google's sitelinks search box: the search field that appears directly under a site's listing in search results. 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

Google only reads SearchAction when it appears as a potentialAction on a WebSite entity placed 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 what triggers the sitelinks search box.

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

The sitelinks search box only appears for navigational queries where Google is confident the user is looking for a specific site. It does not appear for every site or every query. Your site needs a working search page at the target URL, and the markup must be on the homepage. Placing it on interior pages has no effect.

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.

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 (/)

    Google only reads the WebSite + SearchAction for the sitelinks search box from the homepage. Placing it on interior pages has no effect. The homepage is the canonical source for site-level structured data.

  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

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