Schema.org JSON-LD: The Developer’s Guide to Rich Results

Structured data is how you speak Google’s language. By embedding JSON-LD scripts in your pages, you tell search engines exactly what your content represents — and in return, you earn rich results: star ratings, FAQ dropdowns, recipe cards, event listings, and more.

What Is JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) is the preferred format for adding structured data to web pages. Unlike Microdata or RDFa, JSON-LD lives in a <script> tag in the <head> — completely separated from your HTML markup.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Schema.org JSON-LD Guide",
  "author": {
    "@type": "Person",
    "name": "Sanjay Samanta"
  },
  "datePublished": "2026-04-28",
  "publisher": {
    "@type": "Organization",
    "name": "Open Graph Generator"
  }
}
</script>

Most Impactful Schema Types

1. Article / BlogPosting

Unlocks article-specific search features like “Top Stories” and author attribution.

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Your Article Title",
  "description": "Brief summary",
  "image": "https://example.com/image.jpg",
  "author": {
    "@type": "Person",
    "name": "Author Name"
  },
  "datePublished": "2026-04-28",
  "dateModified": "2026-04-28"
}

2. FAQPage

Renders expandable FAQ dropdowns directly in search results — one of the highest-impact schema types for organic CTR.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What are Open Graph tags?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Open Graph tags are HTML meta elements that control how URLs appear when shared on social media."
      }
    }
  ]
}

3. HowTo

Perfect for tutorial and guide pages. Renders step-by-step instructions with optional images.

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Add Open Graph Tags",
  "step": [
    {
      "@type": "HowToStep",
      "name": "Add meta tags to <head>",
      "text": "Insert the required og:title, og:type, og:url, and og:image tags."
    },
    {
      "@type": "HowToStep",
      "name": "Test with a debugger",
      "text": "Use the Facebook Sharing Debugger to verify your tags render correctly."
    }
  ]
}

4. SoftwareApplication

For tool pages like ours — earns rating stars and application info in search results.

{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Open Graph Generator",
  "applicationCategory": "DeveloperApplication",
  "operatingSystem": "Web",
  "offers": {
    "@type": "Offer",
    "price": "0",
    "priceCurrency": "USD"
  }
}

Validation Tools

Always validate your JSON-LD before deploying:

Google Rich Results Test — search.google.com/test/rich-results
Schema.org Validator — validator.schema.org
Google Search Console — monitors structured data errors across your entire site

Common Mistakes

Missing Required Properties

Each schema type has required fields. For Article, you need at minimum: headline, author, datePublished, and image.

Invalid Nesting

Don’t nest types that shouldn’t be nested. For example, FAQPage questions must be in the mainEntity array, not scattered across the document.

Mismatched Content

Google explicitly warns against structured data that doesn’t match visible page content. If your JSON-LD says the article is about “React Hooks” but the page content is about “CSS Grid”, you risk a manual penalty.

Multiple Conflicting Scripts

It’s fine to have multiple JSON-LD scripts on one page (e.g., Article + BreadcrumbList), but they should describe different aspects of the page, not contradict each other.

Implementation in Astro

In Astro, add JSON-LD to your layout’s <head> using a dynamic script:

---
const schema = {
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": title,
  "author": { "@type": "Person", "name": author },
  "datePublished": publishDate,
};
---
<script type="application/ld+json" set:html={JSON.stringify(schema)} />

Conclusion

JSON-LD structured data is a competitive advantage that most sites leave on the table. Start with Article or FAQPage schemas — they’re the easiest to implement and have the highest impact on search visibility. Combine them with proper Open Graph tags for a complete metadata strategy.