Structured Data (JSON-LD) Guide With Validation Steps

Open the source of almost any modern page and you may find a block of data that the visitor never sees. That block is how the site introduces itself to search engines. Who writes it, what should it contain, and what happens when it is wrong? This guide answers those questions around three common types: Organization, BreadcrumbList and Article.

The aim is practical. Keep one trustworthy source per template, match every property to something visible on the page, and validate in a fixed order with three tools. Nothing here promises a rich result; it only follows what the documentation says. The single checklist table near the end can be copied into your own process.

What Structured Data and JSON-LD Are

Structured data means labelling the information on a page with a shared vocabulary so that software can read it consistently. Instead of guessing from running text that a page is an article, written by a certain person and published on a certain date, a search engine reads those facts directly. The vocabulary is usually schema.org, and Google's introduction to structured data (Opens in a new tab) explains which result features this data can make a page eligible for.

JSON-LD is the format that carries those labels in a separate block inside the page. Rather than sprinkling attributes across your HTML tags, you keep everything in one place, which makes it easy to generate from a template and easy to maintain. Google recommends JSON-LD when your setup allows it, while Microdata and RDFa remain supported. As long as the markup is valid, Google treats the three formats as equally fine. Choosing a format is a maintenance decision, not a ranking decision.

Set the scope early. This article covers the general approach and three common types. Detailed Article and FAQ markup, product markup and breadcrumb architecture each have their own guides, so here they are linked rather than retold. Structured data is not a ranking switch. The documentation talks about eligibility, and we keep to that language.

• What it does: tells machines the type of a page and its key properties.
• What it does not do: lift rankings on its own or promise a rich result.
• Who needs it: anyone running a brand site, a blog, or category and product templates.

The Structure of JSON-LD: Context, Type and Property

A JSON-LD block rests on three ideas. The first is the context: a field, written as @context, that says which vocabulary the block uses. With schema.org it points to that vocabulary. The second is the type: @type states what the described thing is, for example Organization, BreadcrumbList or Article. The third is the set of properties that belong to that type, such as a name, an address, a date or an author.

Property values can be plain text, numbers or another nested entity. The author of an Article, for instance, is an entity of its own, a Person whose name and profile address are properties of that inner entity. Nesting lets you define a fact once and reference it where needed, which lowers the chance of contradictions.

Read a block in a fixed order. Find the type first, then open the matching Google documentation page and read its property list, and only then map each property to something on your page. One caution: some types have required properties and some do not. The Organization and Article pages list no required properties at all, only recommended ones. BreadcrumbList does need the list itself and the position of each item. Do not invent fields because they feel right; a property missing from the documentation adds nothing.

This guide deliberately shows no code samples; it describes the structure through lists and a table. When you write the real block in your template, take Google's own examples and the schema.org type pages as the reference.

1. Decide which type fits the page.
2. Note the required and recommended properties from Google's page for that type.
3. Mark whether each property has a visible counterpart on the page.
4. Leave out any property without a visible counterpart.

Organization Markup: Clarifying Brand Information

Organization markup introduces the entity behind the site: its name, contact details, logo and official profiles. Google's Organization documentation lists no required properties. Name, alternate name, description, URL, logo, sameAs, address and contact point appear as recommended properties. What matters is not how many are filled in but whether each one is accurate and consistent with what is visible.

The documentation is clear about placement: put the information on your home page or on a single organization page such as an about page. You do not need it on every page. Pick the most specific schema.org subtype that fits, such as an online-store subtype for a shop rather than a generic business type, or a local business subtype for a physical location.

For the logo, Google lists several conditions: at least 112x112 pixels, a crawlable and indexable image URL, a format supported by Google Images, and a design that looks right on a white background. Check these against the real logo shown on your site and do not point to a different image.

Clear brand data is only one piece of how a search engine comes to understand you as an entity. How to build consistent naming and topical associations across channels is covered in our guide to entity SEO. The Organization block is the machine-readable side of that work, and it should agree with how the brand describes itself everywhere else.

• Write the official name the same way your visible branding shows it.
• Enter an address or phone number only if you publish it on the page.
• List in sameAs only the profiles the brand actually owns.

BreadcrumbList: Describing the Navigation Path

BreadcrumbList describes where a page sits in the site hierarchy. According to Google's documentation, the list holds at least two items. Each item has a position, which is an integer starting at 1, plus a visible name and an address. The address may be left out on the last item, in which case Google uses the address of the page that contains the markup. The root domain and the current page do not need their own entries.

The key principle in the documentation is that breadcrumbs should reflect a typical user path, not necessarily the raw URL structure. If a product lives in two categories and also in a campaign, mark up the path you actually show visitors. The visible trail and the markup must never contradict each other.

How to design the trail in the first place, including category depth and internal linking, is the subject of our article on site architecture and breadcrumbs. This guide covers only the markup side: design the path first, then mark it up, never the other way round.

What to check

• Does the list contain two or more items?
• Do positions start at 1 and increase in order?
• Is the visible breadcrumb the same path as the marked-up one?
• Is any old data-vocabulary.org markup left? Google's page says it no longer qualifies for rich results.

Article Markup: Post, Author and Date Information

Article markup describes a news story, blog post or similar piece. In Google's Article documentation there are no required properties; you add the ones that apply. The recommended properties it lists are the author, the date published, the date modified, the headline and an image.

The author details deserve attention. Add every author shown on the page as a separate author entry and do not join several names into one field. Use Person for people and Organization for organizations. The name field should contain the name only, without job titles, honorifics, phrases like "posted by", or the publisher's name. A web address that identifies the author is added alongside.

Dates follow ISO 8601, and including time zone information is recommended; without it Google falls back to the time zone Googlebot uses. Keep the headline concise, because long titles may be truncated on some devices. The image should represent the article and be served from a crawlable address; a logo or a caption does not count.

For the depth that belongs to the article type and the status of FAQ markup, see our dedicated Article and FAQ schema guide. We do not repeat it here. The point of this section is which Article fields you can safely fill in a general template.

Matching the Markup to What Is Visible on the Page

The most commonly misunderstood rule in Google's structured data documentation is this: do not mark up information that users cannot see on the page, even if the information is accurate. Markup is a machine-readable summary of visible content. It is not a channel for introducing claims the page never shows.

In practice, every property must pair with a visible part of the page. If the author appears by name, the markup can include it. If the publication date is not shown, putting the date only into the markup breaks the match. Likewise, adding a phone number to an Organization block when no phone number appears anywhere on the site is inappropriate.

Authorship is where this matching matters most. The author block and the visible author box must name the same person in the same way. How to build a credible author page and support the author's identity with real evidence is covered in our guide to author pages and E-E-A-T. Markup simply declares what that page already establishes; it cannot create credibility.

Ask the matching question in this order: is this property visible to a visitor, and if so, with the same value? If the answer is no, remove the property or fix the page first. Consider a hypothetical blog template where the author name appears under the headline but the publication date exists only in the source code. The right fix is to show the date on the page or drop it from the markup; there is no third option.

• Visible and matching: mark it up.
• Visible but with a different value: reconcile the two first.
• Not visible at all: leave it out.

Adding JSON-LD to a Page: By Hand, by Template and by Plugin

There are three ways to add JSON-LD to a page, and each has a different maintenance cost. Writing by hand is fast for one page but breeds inconsistency as pages multiply. Generating from a template pulls facts from one source in your system: organization details from a settings page, author and dates from the content record, breadcrumbs from the navigation data. A plugin shortens setup, but you still have to validate what it outputs.

The guiding principle in a template is a single source of truth. If the organization name is typed by hand in three places, the copies drift apart as soon as one changes. Generate the markup from the same variable that renders the visible text, and the two stay aligned automatically.

Distributing structured data by page type is a separate job in e-commerce. Property selection and price information for shop pages are covered in our product schema guide, and the workflow described here adapts to that case as well.

Choosing a method

• One page that rarely changes: write by hand, then validate.
• Many similar pages: generate from the template with one source.
• Need a fast start: use a plugin, then check the output page by page.

Whichever route you take, confirm that the block really appears in the page source. In some setups the markup only exists after a script runs, so test the rendered version too.

Validation: Rich Results Test, Schema Validator and Search Console

Validation uses three tools in a set order. The first is the Rich Results Test, which Google's documentation describes as an easy and useful tool for validating structured data. You give it a URL or a code snippet and it shows the types it detected and any errors. The second is the Schema Markup Validator (Opens in a new tab), which checks syntax against schema.org regardless of Google's rich result requirements. They do not measure the same thing: one checks eligibility for Google features, the other checks conformance to the vocabulary.

The third tool is Search Console. URL Inspection confirms that Google can reach the page and has found the structured data, and the status reports group invalid items after launch. The breadcrumb documentation spells out a sequence: fix critical errors with the test, then use URL Inspection after publishing to make sure robots.txt, a noindex tag or a login requirement is not blocking the page, submit a sitemap, and check the status report once the page is indexed.

Reading that report and interpreting changes per page is covered in our Search Console performance report guide. Remember that green results in a test tool say nothing about ranking or about whether a rich result will appear; they only show technical validity.

1. Clear critical errors in the Rich Results Test while the page is a draft.
2. Run the Schema Markup Validator separately for syntax.
3. After publishing, confirm Google's view with URL Inspection.
4. Review the status report at regular intervals.

Common Mistakes and Uses That Can Count as Spam

The most frequent mistake is cutting markup loose from the page: a rating that is not displayed, an FAQ that visitors cannot see, an address that does not exist. These are more than technical slips, because they can look deceptive. Google's documentation says markup seen as outside its guidelines may lead to a manual action, so additions made on the theory that it surely helps carry avoidable risk.

A second group is purely technical: a missing required property, positions in the wrong order, a date in an invalid format, a logo address that cannot be crawled, or two conflicting Organization blocks on one page. Test tools catch these and they are usually quick to fix.

A third group is maintenance drift. The template changed, a field disappeared from the visible page, yet the markup keeps carrying the old value. These mismatches tend to be noticed months later.

Uses that can count as spam

• Marking up customer ratings or reviews that the page does not display.
• Putting another organization's details into your own Organization block.
• Choosing a type unrelated to the content of the page.
• Copying the same block to every page without a reason.

When you find an error, ask where it comes from: the template, the data or a plugin. Patching single pages by hand without fixing the source reproduces the same problem.

Maintenance: Revalidating After a Template Change

Structured data is not something you write once and forget. Every template change should come with a fresh look at the markup, much like a release note. A theme update, a plugin version, a move to a multilingual setup or a navigation redesign can each change what the block outputs.

Set up a simple routine. After each template change, run one representative page of each type, say an article, a category page and the home page, through the validators. Fix any difference before it goes live. It also makes sense to include the markup check inside a broader technical review, and our technical SEO audit checklist can serve as that frame.

On multilingual sites each language version must match its own visible text. The English page carries an English headline in its markup and the Turkish page a Turkish one; an untranslated field breaks the match with the visible content.

• Revalidate the three representative pages after any template change.
• Look into a sudden rise in invalid items in the status report.
• Update the settings page when organization details such as name, address or logo change.
• Review author records regularly as people join or leave.

Example Template: JSON-LD Implementation and Validation Checklist

The table below combines the implementation and validation steps for a hypothetical company blog template. The values are illustrative only; adapt each row to your own pages.

Apply the rows in order and check the "visible counterpart" column on the live page by eye. If a row has no visible counterpart, that property stays out of the block.

Imagine a small company blog whose organization name was typed by hand in both the settings page and the template, and whose logo changed in the latest version. Following the table, the fix is to make the settings page the only source and then revalidate the home page. The same logic applies to author and date fields.

Frequently Asked Questions

What is JSON-LD and why is it preferred?

JSON-LD is a format that places structured data in a self-contained block on the page, so machines can read what the page is about without touching the visible HTML. Google recommends JSON-LD when your setup allows it and calls it the easiest format to implement and maintain. Microdata and RDFa also work if the markup is valid.

Does structured data raise rankings?

Not by itself. According to Google's documentation, markup helps its systems understand a page and can make the page eligible for certain rich result features when the requirements are met. Eligibility is not a promise of display or of a higher position. Content quality and page experience still decide rankings.

Should Organization markup appear on every page?

No. Google's Organization documentation says you do not need to include the information on every page. The home page or a single organization page, such as an about page, is enough. The documentation also lists no required properties, only recommended ones, and the values should agree with what visitors can see.

How do I validate BreadcrumbList markup?

Run the page or the code through the Rich Results Test or the Schema Markup Validator and fix critical errors first. After publishing, use URL Inspection to confirm Google can reach the page and that robots.txt, noindex or a login does not block it. Once indexed, watch the matching Search Console status report.

Should I add JSON-LD by hand or with a plugin?

It depends on your team and templates. Code generated from one source in the template follows page data automatically. A plugin is quick to install, but you still need to check its output. Writing by hand suits a single page that rarely changes; on duplicated pages, small errors pile up.

Do structured data errors penalize my site?

There is no automatic penalty for technical errors, but invalid markup can cost you rich result eligibility. Google's breadcrumb documentation warns that markup seen as outside its guidelines may trigger a manual action. Avoid marking up anything invisible or misleading, and fix plain technical errors when the reports show them.

Conclusion and Next Step

Your decision point is simple: does the markup carry real, visible facts about the page, or does it carry a claim nobody can see? The first is a small maintenance task, the second is a risk to remove. Follow the order in this guide: choose the type, map every property to its visible counterpart, validate with three tools, and recheck whenever a template changes.

Clean markup pairs well with a steady flow of useful content. Once brand data, author profiles and breadcrumbs are in order, the next job is publishing articles that help readers. If you want help sharing that workload, look at the order flow on the content writing page: you choose the service, add it to the cart, pay, follow the seller's approval and the delivery notice, and use the dispute route if something goes wrong.