ADR 0010: Unified Structured Data (Schema.org / JSON-LD) and AI Engine Optimization (AEO/GEO)

Status

Accepted

Date

2026-09-23

Context

As search behaviors evolve towards AI-augmented search engines (Perplexity, ChatGPT Search, Claude, and Google AI Overviews) alongside traditional algorithmic rankings, plain HTML metadata is no longer sufficient. Search and retrieval models require disambiguated, machine-readable knowledge graph entities to accurately index, cite, and present rich results (Breadcrumbs, Rich FAQ snippets, Product/Offer details, and Organization credibility).

Prior to this decision, marketing apps across the ecosystem lacked:

1. Canonical URL resolution with multi-lingual alternate tags (hreflang for ar-SA, en-US, and x-default), risking duplicate content penalties.
2. Type-safe, Schema.org-compliant JSON-LD structured data on landing pages, FAQs, and blog articles.
3. Permissive crawler access rules for verified AI search bots in robots.ts.
4. Dynamic lastModified timestamps in XML sitemaps aligned with Content Collections.

Decision

1. Type-Safe Schema Engine (JsonLd.tsx): Implement a lightweight, zero-overhead structured data engine in modules/shared/components/JsonLd.tsx that outputs Schema.org JSON-LD scripts for:

   • Organization (holding & project brand entity)
   • WebSite (search and language properties)
   • SoftwareApplication (category, supported platforms, pricing offers)
   • FAQPage (dynamic extraction from localized FAQ dictionary items)
   • BreadcrumbList (hierarchical navigational chains)
   • BlogPosting / Article (authorship, publication, modified dates, images)

2. Standardized SEO Metadata Factory (seo.ts): Introduce createMetadata in modules/shared/lib/seo.ts to automatically generate:

   • Consistent canonical URLs
   • Bi-directional hreflang alternate links
   • Complete OpenGraph (og:*) and Twitter Card (twitter:card: summary_large_image) payloads
   • Googlebot search directives (max-snippet: -1, max-image-preview: large, max-video-preview: -1)

3. Crawl & Discovery Optimization:

   • Explicitly permit reputable AI retrieval bots (GPTBot, ChatGPT-User, ClaudeBot, PerplexityBot, Google-Extended) in robots.ts.
   • Bind dynamic article date values to lastmod entries in sitemap.ts.

Consequences

• Positive:
  • Automated Rich Snippet eligibility across Google GCC and international search.
  • Higher probability of inclusion and direct citation in AI Overview answers.
  • Clean separation of SEO concerns with 100% test coverage and type safety.
  • Zero duplicate-content penalties across Arabic and English localized routes.
• Negative / Maintenance:
  • Changes to route hierarchies require keeping BreadcrumbList schemas synchronized.