Open Graph Generator
Contactez-nous
Back to Blog
JSON-LDTutorialWeb DevelopmentSEO

How to Create JSON-LD: Step-by-Step Developer Tutorial

Learn how to build and implement Schema.org JSON-LD structured data from scratch. Includes Next.js, Astro, WordPress, and Vanilla HTML examples.

SS
Sanjay Samanta•March 16, 2026
11 min read

Adding structured data to your website is one of the highest-ROI technical SEO optimizations you can perform. By embedding JSON-LD (JavaScript Object Notation for Linked Data) into your HTML pages, you explicitly tell search engines what your content represents, qualifying your site for high-converting Google Rich Snippets (star ratings, FAQ dropdowns, pricing badges, and breadcrumb trails).

In this step-by-step tutorial, you will learn how to create Schema.org JSON-LD from scratch, how to avoid syntax errors, and how to integrate dynamic schema into modern web frameworks using our JSON-LD Schema Generator and Schema Inspector.

Step 1: Choose the Right Schema.org Type

Before writing any JSON, determine the primary entity your webpage represents:

  • Articles & News: Article, BlogPosting, NewsArticle
  • Ecommerce Products: Product, Offer, AggregateRating
  • Company & Organizations: Organization, Corporation, LocalBusiness
  • Frequently Asked Questions: FAQPage
  • Software & Web Tools: SoftwareApplication, WebApplication
  • Navigation Hierarchy: BreadcrumbList

Browse comprehensive templates in our 10 Essential Schema.org JSON-LD Examples Guide.

Step 2: Structure Your JSON-LD Object

Every JSON-LD script requires two fundamental properties: @context and @type.

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "How to Create JSON-LD: Developer Tutorial",
  "description": "Step-by-step technical guide to writing and embedding Schema.org structured data.",
  "datePublished": "2026-03-16T08:00:00Z",
  "author": {
    "@type": "Person",
    "name": "Sanjay Samanta",
    "url": "https://opengraphgenerator.com/authors/sanjay-samanta/"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Open Graph Generator",
    "logo": {
      "@type": "ImageObject",
      "url": "https://opengraphgenerator.com/images/logo.png"
    }
  }
}

Step 3: Embed Inside an HTML <script> Tag

Wrap your JSON object inside a <script type="application/ld+json"> tag and place it inside the <head> section of your HTML document:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>How to Create JSON-LD: Developer Tutorial</title>
  <meta name="description" content="Learn how to write and embed Schema.org JSON-LD." />

  <!-- Structured Data JSON-LD -->
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "headline": "How to Create JSON-LD: Developer Tutorial",
    "datePublished": "2026-03-16",
    "author": {
      "@type": "Person",
      "name": "Sanjay Samanta"
    }
  }
  </script>
</head>
<body>
  <!-- Page Content -->
</body>
</html>

For guidelines on script placement, read Where to Put JSON-LD in HTML: Head vs Body.

Step 4: Multi-Framework Dynamic Implementation

1. Next.js App Router (layout.tsx / page.tsx)

import type { Metadata } from 'next';

export default function ArticlePage({ article }) {
  const schema = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: article.title,
    description: article.excerpt,
    datePublished: article.publishedAt,
    author: {
      '@type': 'Person',
      name: article.author,
    },
  };

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
      />
      <h1>{article.title}</h1>
      <p>{article.content}</p>
    </>
  );
}

2. Astro Static Pages

---
const { title, description, date, author } = Astro.props;

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

Step 5: Validate and Test Your Structured Data

Never deploy structured data without testing for syntax errors and missing required properties:

  1. Syntax Check: Use our Schema Inspector to validate JSON formatting and check for missing recommended fields.
  2. Translate Legacy Markup: Convert old Microdata into JSON-LD using our Schema Translator.
  3. Head Audit: Verify canonical headers and meta tag health with our Head Auditor.

Best Practices Checklist

  1. Always use "@context": "https://schema.org".
  2. Ensure dates are formatted in ISO 8601 (e.g. 2026-03-16T08:00:00Z).
  3. Use absolute URLs for all image and entity @id links.
  4. Pair with Open Graph: Complement search schema with rich social cards using our Open Graph Generator and Twitter Card Generator.
  5. AI Knowledge Protocol: Structure code repositories for AI coding agents with our Open Knowledge Format (OKF) Generator.

Generate clean, verified Schema.org JSON-LD scripts with our free JSON-LD Schema Generator!

Advanced Schema.org Entity Graph Architecture

In modern semantic search, search engines like Google and Bing evaluate websites not as disconnected pages, but as connected Knowledge Graphs. By linking entities using standardized @id Uniform Resource Identifiers inside a single @graph block, you provide unambiguous semantic relationships that elevate your domain’s E-E-A-T (Experience, Expertise, Authoritativeness, and Trustworthiness) authority signals.

<!-- Full Enterprise Knowledge Graph in JSON-LD -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://opengraphgenerator.com/#organization",
      "name": "Open Graph Generator",
      "url": "https://opengraphgenerator.com/",
      "logo": {
        "@type": "ImageObject",
        "@id": "https://opengraphgenerator.com/#logo",
        "url": "https://opengraphgenerator.com/images/logo.png",
        "width": 512,
        "height": 512,
        "caption": "Open Graph Generator Logo"
      },
      "sameAs": [
        "https://twitter.com/OpenGraphGen",
        "https://github.com/sanjaysamanta/opengraphgenerator",
        "https://linkedin.com/company/open-graph-generator"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://opengraphgenerator.com/#website",
      "url": "https://opengraphgenerator.com/",
      "name": "Open Graph Generator",
      "description": "Free developer tools to generate, preview, and audit Open Graph, Twitter Cards, and Schema.org JSON-LD tags.",
      "publisher": {
        "@id": "https://opengraphgenerator.com/#organization"
      },
      "inLanguage": "en-US"
    },
    {
      "@type": "Person",
      "@id": "https://opengraphgenerator.com/authors/sanjay-samanta/#author",
      "name": "Sanjay Samanta",
      "jobTitle": "Principal Software Architect",
      "worksFor": {
        "@id": "https://opengraphgenerator.com/#organization"
      },
      "sameAs": [
        "https://github.com/sanjaysamanta",
        "https://twitter.com/sanjaysamanta"
      ]
    },
    {
      "@type": "WebPage",
      "@id": "https://opengraphgenerator.com/#webpage",
      "url": "https://opengraphgenerator.com/",
      "name": "Technical SEO & Social Graph Toolkit",
      "isPartOf": {
        "@id": "https://opengraphgenerator.com/#website"
      },
      "about": {
        "@id": "https://opengraphgenerator.com/#organization"
      },
      "breadcrumb": {
        "@id": "https://opengraphgenerator.com/#breadcrumb"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://opengraphgenerator.com/#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://opengraphgenerator.com/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Tools",
          "item": "https://opengraphgenerator.com/tools/"
        }
      ]
    }
  ]
}
</script>

Dynamic Server-Side Integration Across Modern Frameworks

1. Next.js App Router Dynamic Schema Component

// components/JsonLd.tsx
interface JsonLdProps {
  data: Record<string, any>;
}

export function JsonLd({ data }: JsonLdProps) {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{
        __html: JSON.stringify(data).replace(/</g, '\u003c'), // XSS Protection
      }}
    />
  );
}

// app/blog/[slug]/page.tsx
export default async function BlogPostPage({ params }) {
  const post = await fetchPost(params.slug);

  const articleSchema = {
    '@context': 'https://schema.org',
    '@type': 'BlogPosting',
    headline: post.title,
    description: post.excerpt,
    datePublished: post.publishedAt,
    dateModified: post.updatedAt,
    author: {
      '@type': 'Person',
      name: post.authorName,
      url: `https://example.com/authors/${post.authorSlug}/`,
    },
    publisher: {
      '@type': 'Organization',
      name: 'Open Graph Generator',
      logo: 'https://opengraphgenerator.com/images/logo.png',
    },
  };

  return (
    <>
      <JsonLd data={articleSchema} />
      <article>
        <h1>{post.title}</h1>
        <div>{post.content}</div>
      </article>
    </>
  );
}

2. Astro Layout with Set:html Sanitization

---
interface Props {
  schema: Record<string, any>;
}

const { schema } = Astro.props;
---
<head>
  <script type="application/ld+json" set:html={JSON.stringify(schema)} />
</head>

Common Schema.org Mistakes & Debugging Checklist

Validation Failure Root Cause Developer Fix
Unescaped Quotes in JSON Raw " inside headline or description strings Sanitize with JSON.stringify() or escape internal quotes (\").
Invalid Date Formats Using human dates (e.g. March 24, 2026) Use ISO 8601 timestamps: 2026-03-24T08:00:00Z.
Missing Image Dimensions Single image URL without dimensions Provide high-res multi-ratio images (16x9, 4x3, 1x1).
Broken Currency Formats $49.99 with dollar symbol in price field Use numeric string "price": "49.99" with "priceCurrency": "USD".
Mixed Microdata & JSON-LD Duplicated entity declarations causing conflicts Remove legacy Microdata attributes using Schema Translator.

The AI Search Engine Revolution: Sourcing Answers with Structured Data

As search behavior shifts toward AI-powered answer engines (ChatGPT Search, Perplexity AI, Claude Search, Google AI Overviews), the role of structured data has expanded from visual Rich Snippets to Knowledge Ingestion:

  • AI crawlers use Schema.org JSON-LD to verify factual attributes (pricing, software requirements, authors, release dates) with 100% precision.
  • Clear semantic graphs reduce AI hallucinations and increase the probability of your domain being cited as a primary source.
  • Learn more in our dedicated guide on Meta Tags for AI Search Engines (ChatGPT & Perplexity).

For software engineering repositories, explore how structured codebase context is maintained for AI coding agents using our Open Knowledge Format (OKF) Generator and read the OKF Developer Guide.

Verification & Tool Ecosystem

  1. Scaffold Structured Data: Build verified markup with our JSON-LD Schema Generator.
  2. Inspect Live URLs: Test live pages for syntax errors and missing fields with our Schema Inspector.
  3. Format Translation: Convert Microdata and RDFa into JSON-LD with our Schema Translator.
  4. Social Sharing Synergy: Pair your schema with high-CTR social preview cards using our Open Graph Generator and Twitter Card Generator.

Build, test, and validate production-ready JSON-LD schema with our free JSON-LD Schema Generator today!

More Articles
Advertisement

Related Articles

application/ld+json Explained: MIME Types, Syntax, and Search Engines

11 min read

Does Open Graph Help SEO?

6 min read

How to Validate JSON-LD: Tools, Debugging, and Rich Result Tests

11 min read