No WebSite schema with SearchAction

What Is This Issue

WebSite schema is missing from your homepage. WebSite schema defines your website as a named entity, enabling Google’s Sitelinks Search Box and helping search engines understand your site’s identity.

Without WebSite schema:

Your site won’t have a Sitelinks Search Box in search results
Google can’t properly identify your site as a distinct entity
Your site’s identity is weaker in the Knowledge Graph
AI search engines have less context about your website

A proper WebSite schema should include: @type (WebSite), name, url, @id (canonical site URL), description, and optionally potentialAction (for Sitelinks Search Box).

Why Is This Important

WebSite schema is important for site identity and search experience:

Sitelinks Search Box: Enables users to search your site directly from Google search results
Entity recognition: Helps Google understand your website as a distinct entity
Knowledge Graph: Strengthens your site’s presence in Google’s Knowledge Graph
AI search readiness: Provides AI engines with clear context about your website
Brand consistency: Ensures your site name appears consistently in search results

Resolving this issue improves your SEO health score by establishing your website as a recognized entity in search engines.

How XeoPix Detects This

XeoPix follows these logical steps to detect missing WebSite schema:

Check homepage only: The crawler specifically examines the homepage (index page) of the website
Extract structured data: The crawler looks for JSON-LD, Microdata, or RDFa blocks on the homepage
Check for WebSite schema: The crawler verifies if any schema block has:
- @type set to WebSite
- Required properties: name, url
Validate schema completeness: If WebSite schema is found, the crawler checks for:
- Proper @id property (canonical site URL)
- description property
- potentialAction for Sitelinks Search Box (optional but recommended)
Trigger conditions: The issue is flagged when:
- Homepage doesn’t have WebSite schema
- WebSite schema exists but is missing name property
- WebSite schema exists but is missing url property

How To Fix

Add WebSite JSON-LD structured data to your homepage <head>:


{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "@id": "https://www.example.com/#website",
  "name": "Your Website Name",
  "url": "https://www.example.com",
  "description": "Description of your website",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://www.example.com/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}

Include recommended properties:
- @id: Use a consistent anchor (e.g., https://www.example.com/#website)
- name: Your website name as you want it to appear in search
- url: Your website’s canonical URL
- description: Brief description of your website
For Sitelinks Search Box, add potentialAction with SearchAction type
Make it referenceable: Other schemas (Article, BreadcrumbList) can reference this via isPartOf
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 WebSite Schema on Homepage

Problematic state:


<!-- Homepage without WebSite schema -->
<html>
  <head>
    <title>Example Corp - Home</title>
  </head>
  <body>
    <h1>Welcome to Example Corp</h1>
    <p>Your trusted partner for digital solutions.</p>
  </body>
</html>

Corrected state:


<!-- Homepage with WebSite schema -->
<html>
  <head>
    <title>Example Corp - Home</title>
    <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "WebSite",
        "@id": "https://www.example.com/#website",
        "name": "Example Corp",
        "url": "https://www.example.com",
        "description": "Your trusted partner for digital solutions."
      }
    </script>
  </head>
  <body>
    <h1>Welcome to Example Corp</h1>
    <p>Your trusted partner for digital solutions.</p>
  </body>
</html>

Corrected state (with SearchAction):


{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "@id": "https://www.example.com/#website",
  "name": "Example Corp",
  "url": "https://www.example.com",
  "description": "Your trusted partner for digital solutions.",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://www.example.com/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}

Example 3: Incomplete WebSite Schema

Problematic state:


{
  "@context": "https://schema.org",
  "@type": "WebSite"
}

Missing required properties: name, url

Corrected state:


{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "@id": "https://www.example.com/#website",
  "name": "Example Corp",
  "url": "https://www.example.com",
  "description": "Your trusted partner for digital solutions."
}

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/structuredDataRichResults/issue-58-website-schema-searchaction.test.js

Purpose

Validates that the crawler correctly detects when the homepage is missing a WebSite schema with SearchAction or lacks a SiteLinksSearchBox schema.

Tested Function

runStructuredDataRichResults()

Issue Information

Issue Number: 58
Issue Code: website_schema_searchaction
Toggle Group: structuredDataRichResults

Test Scenarios

Positive Test Cases

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

Negative Test Cases

Search functionality without schema: Homepage has a search input and button but no WebSite schema — issue is reported with status website-searchaction-missing.
WebSite schema without SearchAction: WebSite schema exists but lacks potentialAction/SearchAction — SiteLinksSearchBox issue is reported instead.
Likely homepage without schema: Page has a title “Home” and navigation but no schema — issue is reported with detectionHints.isLikelyHomepage set to true.

Boundary Cases

None.

Edge Cases

Empty HTML: <html></html> — no issue reported, no crash.

Expected Outcome

Pass

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

Fail

Issue should be reported when the page is a likely homepage or has search functionality but lacks a WebSite schema with SearchAction. The details.status is website-searchaction-missing.

Validation

Correct issue detection when search functionality exists without schema
Correct issue detection when WebSite schema lacks SearchAction
Detection hints (isLikelyHomepage) populated correctly
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 presence of WebSite schema with SearchAction
Covers presence of SiteLinksSearchBox schema
Covers detection of search functionality without schema
Covers homepage detection heuristics
Covers empty HTML resilience

References

Google: Sitelinks Search Box — Google Search Central
Schema.org: WebSite — Schema.org
Google: Rich Results Test — Google Search Central