JSON-LD Schema Guide: Boost Your SEO with Structured Data
Structured data is the bridge between your content and Google's ability to understand it. JSON-LD is the format Google recommends, and mastering it unlocks rich results — the visually enhanced search listings with stars, prices, FAQs, and more that dramatically outperform plain blue links. This guide explains JSON-LD from the ground up: how it works, how to write it correctly, what properties matter most, and how to use a free generator to produce valid markup in minutes.
JSON-LD Explained: The Format Google Recommends
JSON-LD stands for JavaScript Object Notation for Linked Data. It is a method of encoding structured data using the familiar JSON syntax, extended with a context declaration that links property names to their definitions in a shared vocabulary — in this case, Schema.org. A JSON-LD block always begins with two special properties: @context and @type. The @context is almost always set to https://schema.org — this tells the parser that the property names used in this block follow Schema.org definitions. The @type tells Google what kind of thing you are describing: an Article, a Product, a Person, a LocalBusiness, and so on. Every other property in the block is a key-value pair that describes a specific attribute of that thing. For an Article, you might have headline, author, datePublished, and image. For a Product, you would have name, description, offers, and aggregateRating. The entire block sits inside a script tag with the attribute type set to application/ld+json. This tells the browser not to execute it as JavaScript. Search engine crawlers specifically look for this tag pattern when indexing your page. JSON-LD has a major advantage over other structured data formats: it is completely independent of your HTML markup. You do not need to add attributes to your existing HTML elements or restructure your page. The JSON-LD block can go anywhere in the document — head or body — and it will not affect your visual layout. This makes it far easier to add, update, and test compared to Microdata or RDFa, which require annotating existing HTML elements. Google's own documentation and implementation guides use JSON-LD exclusively in their examples. If you are starting fresh with schema markup in 2026, JSON-LD is the only format worth using.
Core JSON-LD Properties You Need to Know
Understanding the most frequently used properties helps you produce richer, more useful markup. While Schema.org defines hundreds of properties, a small core set covers the vast majority of real-world implementations. name is the primary label for almost every schema type — the product name, business name, article headline (though for Article the correct property is headline, not name), or person's full name. It is nearly always required. description is a plain-text summary of the entity. Keep it concise and accurate. For products this becomes the snippet Google may use in Shopping results. For events it appears in event rich results. url points to the canonical page for the entity. Always use the full absolute URL including https://. image is used extensively. Google requires images for many rich result types. Always provide an absolute URL. For Article and Product, using an ImageObject instead of a plain URL lets you specify width and height, which Google may use for image selection. datePublished and dateModified apply to Article, BlogPosting, and related types. Use ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS+00:00. Accurate dates help Google categorize your content in news and freshness-sensitive queries. author takes a Person or Organization object. For a blog post, this would be a Person with name and url properties. For a company-authored piece, use Organization with name and url. offers is the property that enables Product schema to show pricing in search results. It wraps a nested Offer object containing price, priceCurrency, and availability. aggregateRating wraps a nested AggregateRating object with ratingValue, reviewCount, and bestRating. This is what produces star ratings in search results. address inside a LocalBusiness schema takes a PostalAddress object with streetAddress, addressLocality, addressRegion, postalCode, and addressCountry. All five fields are recommended for local search reliability.
Common JSON-LD Mistakes and How to Avoid Them
Valid JSON-LD syntax is required for Google to process your markup correctly. Even small errors silently prevent your schema from being used. Here are the most common mistakes and how to fix them. Missing or incorrect @context. Every JSON-LD block must start with @context set to https://schema.org. Using http:// instead of https:// or omitting the property entirely will cause validation failures. Using relative URLs instead of absolute URLs. Properties like url, image, and sameAs must always contain the full URL including the protocol. Writing /blog/my-article instead of https://example.com/blog/my-article is a frequent source of errors. Mismatched @type values. Do not use a custom or misspelled type name. Schema.org type names are case-sensitive and must match exactly: Article not article, LocalBusiness not Local-Business, FAQPage not FaqPage. Incorrect date format for datePublished. Google expects ISO 8601 dates. Writing May 1, 2026 instead of 2026-05-01 will fail validation. Nesting objects where strings are expected, or vice versa. For example, author must be a Person or Organization object, not a plain string like Jane Smith. Conversely, name and headline are plain strings, not objects. Fabricating data. Google's guidelines explicitly prohibit adding schema markup for content that does not appear on the page. Adding five-star reviews in Product schema when your page shows no reviews, or listing business hours that differ from your actual hours, can result in a manual action against your entire domain. Empty required properties. Some schema types have required properties that Google checks. FAQ schema requires at least two Question items in the mainEntity array. HowTo schema requires at least one step. Leaving these empty produces a validation warning that may prevent rich result eligibility. Use the Schema Generator tool to produce syntactically correct JSON-LD, then always validate with Google's Rich Results Test before publishing.
Nested Schema: Combining Types for Maximum Coverage
One of the most powerful but underused aspects of JSON-LD is nesting: embedding one schema type inside another to provide richer descriptions. Understanding how nested schema works opens up a wide range of additional rich result opportunities. The most common nesting pattern is author inside Article. Instead of providing just a string name, you wrap it in a Person type with its own url, jobTitle, and sameAs properties pointing to the author's social profiles. This helps Google build a knowledge entity for the author, which can lead to authorship recognition in AI Overviews and citation features. Product schema often nests multiple related types: an offers array containing Offer objects, each with pricing details; an aggregateRating containing an AggregateRating object; and a review array containing Review objects with their own author sub-objects. Each layer of nesting adds more structured information that Google can use. Organization schema can nest ContactPoint objects to specify customer support phone numbers by contact type, and PostalAddress objects for each physical location. A multi-location business can even nest multiple PostalAddress objects within a single Organization block. BreadcrumbList is almost always nested: the itemListElement property holds an array of ListItem objects, each with position (an integer) and item (an object with id and name). The nesting depth here can reflect your full URL hierarchy. When combining multiple top-level schema types on one page, each type gets its own separate script tag. Avoid putting multiple @type values in a single block unless the Schema.org specification explicitly supports it — the safest approach is one type per script tag. The Schema Generator tool handles all nesting automatically. When you select a schema type and fill in the form, sub-objects like Offer, Person, and PostalAddress are generated correctly nested without you needing to manage the structure manually.
Frequently Asked Questions
- What is the difference between JSON-LD, Microdata, and RDFa?
- All three are methods for adding structured data to web pages, but they differ in how the markup is written. Microdata and RDFa add attributes directly to HTML elements, tightly coupling your structured data to your page markup. JSON-LD is written as a separate script block, completely independent of your HTML. Google recommends JSON-LD because it is easier to write, test, update, and maintain. Microdata and RDFa are still supported but require more effort to implement correctly and are harder to debug. For any new implementation in 2026, use JSON-LD.
- How many JSON-LD blocks can I add to one page?
- There is no enforced limit. You can add multiple JSON-LD script tags to a single page, each describing a different entity or schema type. A typical well-structured page might include Article schema, BreadcrumbList schema, and FAQ schema as three separate blocks. Google processes each block independently. The practical limit is accuracy — only add schema types that genuinely reflect content present on the page. Adding irrelevant schema types to boost visibility is against Google's guidelines and can trigger a manual penalty.
- Does Google guarantee rich results if my JSON-LD is valid?
- No. Valid JSON-LD makes you eligible for rich results, but Google decides whether to display them based on additional factors: page quality, content relevance, user experience signals, and whether Google determines the rich result improves the search experience for that query. For some schema types like FAQ, eligibility is fairly consistent for well-structured pages. For others like Recipe or Product, Google is more selective. The best approach is to implement valid schema, monitor Search Console for enhancement reports, and focus on overall page quality.