Structured Signals Specification

Machine-readable markup embedded in your pages that tells AI search engines what your content is — its type, properties, and relationships — using a shared vocabulary from schema.org.

Format preference

The Analyzer recognizes three structured data formats: JSON-LD, microdata, and RDFa. JSON-LD is the preferred format. It is injected as a <script type="application/ld+json"> block in the page <head> or <body> and does not require modifying existing HTML attributes.

Microdata and RDFa are accepted alternatives. They embed structured data directly in HTML attributes (itemscope, itemtype, itemprop for microdata; typeof, property, vocab for RDFa). Both formats are detected by the Analyzer but produce a warn status rather than pass because JSON-LD is more reliably parsed by AI crawlers.

Why JSON-LD is preferred

JSON-LD is decoupled from your HTML structure. You can add, update, or remove it without touching the visible markup. It is also the format recommended by Google and supported by all major AI search engines.

Schema types

GEO AI packages generate three primary schema.org types. The Analyzer detects any valid JSON-LD regardless of type, but these three cover the most common site categories.

Type	Use case	Key fields
WebSite	Any site — provides a site-level identity signal	name, url, description, potentialAction
Product	E-commerce product pages	name, description, offers, image, sku
Article	Blog posts, news articles, documentation	headline, author, datePublished, publisher

Other schema.org types — Organization, BreadcrumbList, FAQPage, and so on — are valid and detected by the Analyzer. Use whichever types best describe your content.

WebSite example

A WebSite block provides a site-level identity signal. Include it on every page, or at minimum on the homepage. The potentialAction field adds a sitelinks search box to Google results and helps AI engines understand that your site has a search feature.

index.html (JSON-LD)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Example Site",
  "url": "https://example.com",
  "description": "Example Site helps developers build faster with modern tooling.",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://example.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}
</script>

Product example

A Product block with an Offer object gives AI search engines the price, availability, and currency of a product. This enables AI engines to answer pricing questions and include your product in comparison results.

product-page.html (JSON-LD)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Widget Pro",
  "description": "Professional-grade widget for modern development teams.",
  "image": "https://example.com/images/widget-pro.jpg",
  "sku": "WGT-PRO-001",
  "brand": {
    "@type": "Brand",
    "name": "Example Site"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/products/widget-pro",
    "priceCurrency": "USD",
    "price": "29.99",
    "availability": "https://schema.org/InStock",
    "seller": {
      "@type": "Organization",
      "name": "Example Site"
    }
  }
}
</script>

Availability values

Use the full schema.org URL for availability: https://schema.org/InStock, https://schema.org/OutOfStock, or https://schema.org/PreOrder. Shorthand values like InStock are accepted by some parsers but not all.

Article example

An Article block with a publisher object helps AI engines attribute content correctly and include it in topic-based answers. The datePublished and dateModified fields help AI engines assess content freshness.

blog-post.html (JSON-LD)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Getting Started with Widget Pro",
  "description": "How to set up Widget Pro in a fresh project in five minutes.",
  "image": "https://example.com/images/getting-started.jpg",
  "datePublished": "2024-11-01T09:00:00Z",
  "dateModified": "2024-12-15T14:30:00Z",
  "author": {
    "@type": "Person",
    "name": "Jane Smith",
    "url": "https://example.com/authors/jane-smith"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Example Site",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/images/logo.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://example.com/blog/getting-started"
  }
}
</script>

Sitemap fallback

When no structured data markup is present on the homepage, the Analyzer checks for a valid sitemap.xml at {origin}/sitemap.xml. A valid sitemap is an XML document containing a <urlset> or <sitemapindex> element served with an XML-compatible content type.

A valid sitemap produces a warn status rather than fail. It signals that the site has a discoverable URL inventory, but it does not provide the semantic richness of structured data markup. The Analyzer will recommend adding JSON-LD in addition to the sitemap.

Sitemap is a fallback, not a substitute

A sitemap tells AI crawlers which URLs exist. Structured data tells them what those URLs contain. Sites that rely only on a sitemap will score lower than sites with JSON-LD because AI engines have less context to work with when generating answers.

Analyzer checks

The checkStructuredSignals function scans the homepage HTML for structured data and fetches {origin}/sitemap.xml as a fallback signal:

Condition	Status	Recommendation code
At least one valid JSON-LD block found	pass	—
No JSON-LD, but microdata or RDFa attributes present	warn	ADD_JSONLD
No structured data markup, but valid `sitemap.xml` found	warn	ADD_STRUCTURED_DATA
No structured data and no valid `sitemap.xml`	fail	ADD_STRUCTURED_DATA, ADD_SITEMAP
JSON-LD blocks present but contain invalid JSON	pass (with issues)	FIX_INVALID_JSONLD

Invalid JSON-LD blocks are counted separately. If at least one valid block exists alongside invalid ones, the status is still pass, but the FIX_INVALID_JSONLD recommendation is added to the report.

Common mistakes

Invalid JSON in the script block. A missing comma, trailing comma, or unescaped quote inside a JSON-LD block causes a parse error. The Analyzer counts the block as invalid and emits FIX_INVALID_JSONLD. Validate your JSON-LD with Google's Rich Results Test before deploying.
Using microdata or RDFa instead of JSON-LD. Both formats are detected, but they produce a warn rather than pass. Migrating to JSON-LD is the fastest way to move from warn to pass on this category.
Structured data only on inner pages, not the homepage. The Analyzer checks the homepage HTML. If your product or article JSON-LD is only on product and blog pages, the homepage check will return warn or fail. Add at least a WebSite block to the homepage.
Injecting JSON-LD only via JavaScript. The Analyzer fetches raw HTML before client-side rendering. JSON-LD added by React, Vue, or other frameworks after hydration is not visible to the checker. Use server-side rendering or a <script> tag in the static HTML output.
Mismatched @type and fields. Using a Product type without an offers field, or an Article type without a publisher, produces valid JSON-LD that passes the Analyzer but generates low-quality structured data. AI engines use these fields to answer specific questions — missing them reduces the value of the markup.

PreviousCrawler Rules NextScoring