How to Add JSON-LD

If you failed the Structured Data check in our Agent Scanner, your site is missing JSON-LD context.

What is JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) is a standard way to tell machines exactly what your content is.

While humans see a page and know “This is a documentation guide,” AI agents just see text. JSON-LD explicitly tells them:

“This is a technical article.”
“This is a software library.”
“These are the prerequisites.”

The “Cheat Code” Snippet

For a developer documentation site, you should add a WebSite or TechArticle schema to your global <head>.

Option 1: The Global Site Schema (Easiest)

Add this to your main layout file (e.g., inside <head> in src/layouts/Layout.astro or index.html).

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "AgentRetrofit",
  "url": "https://agentretrofit.dev",
  "description": "The Agent Integration Library for legacy systems.",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://agentretrofit.dev/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}
</script>

Option 2: Dynamic Article Schema (Best for Guides)

If you are using Astro, you can make this dynamic for every guide page.

In src/layouts/DocsLayout.astro (or similar):

---
const { title, description } = Astro.props;
const jsonLd = {
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": title,
  "description": description,
  "image": "https://agentretrofit.dev/og-image.png",
  "author": {
    "@type": "Organization",
    "name": "AgentRetrofit"
  }
};
---

<head>
  <script type="application/ld+json" set:html={JSON.stringify(jsonLd)} />
</head>

Validate Your Fix

Deploy your changes.
Run the Agent Scanner again.
The “Structured Data” check will turn Green ✅.