No SiteLinksSearchBox schema

What Is This Issue

The homepage WebSite schema is present but missing the SearchAction property, preventing Google from displaying a Sitelinks Search Box beneath the homepage result for branded queries.

Without SearchAction in WebSite schema:

Google won’t display a Sitelinks Search Box under your homepage result
Users can’t search your site directly from Google search results
Branded search results won’t have the enhanced search functionality
You’ll miss an opportunity to improve user experience from search

A proper SearchAction should be nested inside WebSite schema and include: potentialAction with @type (SearchAction), target with urlTemplate containing {search_term_string}, and query-input.

Why Is This Important

SearchAction in WebSite schema is important for user experience:

Sitelinks Search Box: Enables users to search your site directly from Google search results
Branded search enhancement: Improves the appearance of branded search results
User convenience: Users can search your site without navigating to it first
Click-through rates: Enhanced search results may improve CTR
AI search readiness: AI engines understand your site has search functionality

Important: Only implement this if your site actually has functional internal search. Don’t add SearchAction if your site doesn’t have search capability.

Resolving this issue improves your SEO health score by enhancing branded search results for users.

How XeoPix Detects This

XeoPix follows these logical steps to detect missing SearchAction:

Check homepage only: The crawler specifically examines the homepage (index page) of the website
Find WebSite schema: The crawler looks for WebSite schema on the homepage
Check for SearchAction: The crawler verifies if the WebSite schema has:
- potentialAction property
- potentialAction.@type set to SearchAction
Validate SearchAction completeness: If SearchAction is found, the crawler checks for:
- target property with urlTemplate containing {search_term_string}
- query-input property
Check if site has search: The crawler also verifies if the site actually has internal search functionality
Trigger conditions: The issue is flagged when:
- WebSite schema exists but potentialAction with SearchAction is missing
- Site has internal search but SearchAction is not declared
- SearchAction exists but urlTemplate doesn’t contain {search_term_string}

How To Fix

Ensure WebSite schema exists: Make sure your homepage has WebSite schema (see issue-58.md)

Add SearchAction to WebSite schema on your homepage:


{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://www.example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://www.example.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Use the correct URL template:
- WordPress: /?s={search_term_string}
- Shopify: /search?q={search_term_string}
- Custom: Use your site’s actual search URL pattern
Test the search URL: Make sure the search URL returns real results
Only implement if your site has functional internal search - Don’t add this if you don’t have search functionality
Validate with Google’s Rich Results Test

What We Store

Storage Level

Page Level — This issue is evaluated for each individual URL that contains structured data.

Database Table / Prisma Model

PageStructuredData

Stored Fields

Field	Type	Description
schemaType	SchemaType	The type of schema (e.g., Organization, Person)
schemaFormat	SchemaFormat	The format of the schema (JSON-LD, Microdata, RDFa)
schemaIdentifier	String?	Unique identifier for the schema
rawJson	Json?	The raw JSON-LD or structured data content
schemaErrors	Json?	Array of validation errors found in the schema
isValidSchema	Boolean?	Whether the schema is valid according to validation
missingFields	Json?	Array of required fields that are missing

Detection Dependencies

The following data sources are required to evaluate this issue:
HTML Document — The crawler parses the HTML to find structured data (JSON-LD, Microdata, RDFa)
Structured Data Validation — The extracted schema is validated against Schema.org definitions
Schema Parser — JSON-LD scripts, Microdata attributes, and RDFa markup are parsed

Examples

Example 1: Missing SearchAction in WebSite Schema

Problematic state (WebSite without SearchAction):


{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://www.example.com"
}

Missing potentialAction with SearchAction

Corrected state:


{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://www.example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://www.example.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Example 2: SearchAction for WordPress Site

Corrected state (WordPress):


{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://www.example-wordpress.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://www.example-wordpress.com/?s={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Example 3: SearchAction for Shopify Store

Corrected state (Shopify):


{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://store.myshopify.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://store.myshopify.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/structuredDataRichResults/issue-234-sitelinkssearchbox-schema.test.js

Purpose

Validates that the crawler correctly validates WebSite schemas with SearchAction for SiteLinksSearchBox and does not report false positives when the schema is properly formed.

Tested Function

runStructuredDataRichResults()

Issue Information

Issue Number: 234
Issue Code: sitelinkssearchbox_schema_missing
Toggle Group: structuredDataRichResults

Test Scenarios

Positive Test Cases

WebSite schema with SearchAction: Page has a WebSite schema with a potentialAction of type SearchAction — no issue reported.

Negative Test Cases

None — the test only validates that valid schemas pass.

Boundary Cases

None.

Edge Cases

Empty HTML: <html></html> — no crash.

Expected Outcome

Pass

Issue should not be reported when a WebSite schema with a SearchAction potentialAction is present.

Fail

No negative test cases are defined.

Validation

Correct pass-through of valid SiteLinksSearchBox schemas
Graceful handling of empty HTML

xeopix-crawling-v2/toggleGroups/structuredDataRichResults.js
xeopix-crawling-v2/issueCodes.js
xeopix-crawling-v2/utils/context.js
xeopix-crawling-v2/utils/issues.js
xeopix-crawling-v2/utils/schema.js

Coverage Summary

Covers valid SiteLinksSearchBox schema detection
Covers empty HTML resilience

References

Schema.org — SearchAction — Schema.org
Google — Sitelinks Searchbox — Google Search Central