Add Schema.org JSON‑LD structured data to Aspire docs for AI search discoverability

[BethMassi]

Add Schema.org JSON‑LD structured data to Aspire docs (high‑impact, minimal scope)

Summary

Aspire docs currently expose rich, high‑quality content for humans and tooling (CLI, MCP), but do not expose structured, machine‑readable metadata at the web layer (Schema.org / JSON‑LD). This is important in order to surface our brand in AI searches. Search is shifting from surfacing a SERP with blue links to AI Overviews, generative answers, and chat‑style summaries that collate content in addition to links.

To get our content to appear in this model, our site has to be understood as entities — singular, unique things or concepts, such as a person, place, or event — and the relationships between them, not just strings of text.​

This issue proposes adding a small, high‑impact set of JSON‑LD schemas to Aspire docs pages to improve:

• Search engine understanding
• AI / LLM grounding from web crawl
• Future rich results (FAQ, articles)
• Long‑term discoverability without relying on proprietary ingestion

This change is additive, invisible to users, and does not affect rendering.

---

Goals

• ✅ Add Schema.org JSON‑LD using recommended practices
• ✅ Keep scope intentionally small for the first iteration
• ✅ Align with Aspire’s existing content model
• ✅ Make future expansion straightforward (events, APIs, tutorials)

Non‑goals

• No SEO tuning or ranking guarantees
• No Microdata or RDFa
• No attempt to mark up every page type initially

---

Proposed page‑type → Schema.org mapping

✅ Phase 1 (high‑impact, minimal)

Aspire page type	Example URLs	Schema.org type	Notes
Concept docs	/docs/aspire/what-is-aspire	TechArticle	Core explanatory content
Guides / How‑to	/docs/get-started	TechArticle (or HowTo later)	Start with TechArticle
Reference docs	/docs/reference/...	TechArticle	Avoid over‑specific schemas
FAQ pages	/docs/faq (we need one)	FAQPage	High impact for search + AI
What’s New	/docs/whats-new	TechArticle	Treated as curated release summary
Release notes	/docs/releases/...	TechArticle + SoftwareApplication	Establish versioned releases

🚫 Deferred (future issues)

Page type	Reason deferred
Events (Aspire Conf)	Next year March 2027
API docs	Requires stable per‑API modeling
Blog posts	Live outside /docs (look into automating this with WP)

---

JSON‑LD format requirements

• Use JSON‑LD only
• Inject via <script type="application/ld+json">
• One primary schema per page
• Generated at build time (not client‑side JS)
• Must not block rendering

---

JSON‑LD examples (ready to implement)

1. TechArticle (default for most docs pages)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "What is Aspire?",
  "description": "Aspire is an agent-ready, code-first tool for composing, debugging, and deploying any distributed app, no matter programming language, stack, or cloud.",
  "author": {
    "@type": "Organization",
    "name": "Aspire"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Aspire",
    "url": "https://aspire.dev"
  },
  "url": "https://aspire.dev/docs/aspire/what-is-aspire",
  "inLanguage": "en",
  "about": {
    "@type": "SoftwareApplication",
    "name": "Aspire"
  }
}
</script>
``