JSON-LD Schema Markup for Developers: A Practical Guide

Structured data helps search engines understand what a page is about, not just which words appear on it. Google recommends JSON-LD as the format for it, and it is also the easiest to maintain because it lives in a single script block, separate from your HTML.

In this guide you will learn how JSON-LD works, how to write the three most useful schema types, and how to validate them before shipping.

What is JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) describes entities on a page using the schema.org vocabulary. It sits inside a <script type="application/ld+json"> tag, usually in the <head>, though it works in the <body> too.

Two keys appear in almost every block:

@context: tells parsers you are using schema.org
@type: defines what the entity is (Article, Organization, and so on)

1. Organization schema

Use this on your homepage or about page to describe your business.

The sameAs property links your official profiles, which helps search engines connect your brand across the web.

2. Article schema

Use this on blog posts and news content.

Keep headline, datePublished, and author consistent with what is actually visible on the page. Markup that does not match visible content can be ignored or flagged.

3. BreadcrumbList schema

Use this to describe your site hierarchy.

Generating JSON-LD dynamically

If your site is built with a framework, generate the object in code and inject it once per page. A simple Node.js example:

const articleSchema = (post) => ({ "@context": "https://schema.org", "@type": "Article", headline: post.title, datePublished: post.publishedAt, dateModified: post.updatedAt, author: { "@type": "Person", name: post.author } });

const jsonLd = JSON.stringify(articleSchema(post)); // Output inside:

Always build the object and serialize it with JSON.stringify. Hand-concatenating strings is a common source of broken JSON, especially with quotes in titles.

How to validate

Before publishing, test every template:

Rich Results Test (Google): checks eligibility for rich results
Schema Markup Validator (validator.schema.org): checks general schema.org syntax
Search Console: the Enhancements reports show errors at scale after deployment

Common mistakes

Marking up content that is not on the page. Structured data must reflect visible content.
Invalid JSON. A trailing comma or unescaped quote invalidates the whole block.
Assuming schema guarantees rich results. It makes a page eligible; it does not force a display.
Using outdated types. For example, FAQ rich results are now limited to a small set of well-known government and health sites, so check current Google documentation before adding them.
Duplicating conflicting blocks. If a plugin and your theme both output Organization schema, remove one.

Quick checklist

[ ] Use JSON-LD, one clear entity per block
[ ] Match markup to visible page content
[ ] Generate with JSON.stringify in code
[ ] Validate in both testing tools
[ ] Monitor Search Console after release

Final thoughts

Structured data is a small amount of code with a real payoff in how clearly search engines read your pages. Start with Organization, Article, and BreadcrumbList, validate each template, and expand only when you have a genuine use case.

Have a schema problem you are stuck on? Share it in the comments and I will take a look.

If you want a second pair of eyes on your markup, we regularly review structured data setups at EverGrow Digital Solutions as part of technical SEO audits.

Command Palette