Practical structured data guide
JSON-LD Schema Markup Guide for Practical SEO
JSON-LD helps search engines understand what a page is, who published it, how it fits into your site, and which facts are worth using in supported search features.
The useful goal is not to add every schema type you can find. The useful goal is accurate structured data that matches the visible page, validates cleanly, and stays in sync when the content changes.
The useful short version
Use JSON-LD when you can describe the page with honest, visible facts: title, description, author, publication date, breadcrumbs, product details, video data, or clear question-and-answer content. Do not add schema to promise features Google no longer shows or to mark up content users cannot see.
Table of Content
What JSON-LD actually does
JSON-LD is a machine-readable block of structured data. It normally sits in a script tag in the head or body of the page and describes entities with schema.org vocabulary. Search engines use it as a clarity layer on top of the visible content.
Parser clarity
Meaning
It turns page facts into named entities and properties, such as Article, author, datePublished, BreadcrumbList, or SoftwareApplication.
Search feature
Eligibility
It can make a page eligible for supported rich results, but Google still decides what to show based on quality, policy, query, and feature availability.
Site graph
Consistency
It gives your CMS or Blazor app one structured place to reuse the same canonical URL, language, title, dates, images, and publisher data.
Not a shortcut
Limit
It does not repair weak content, fake reviews, hidden FAQ answers, outdated dates, or pages that do not match the structured data.
Choose schema by the job of the page
The easiest way to avoid spammy or duplicate structured data is to ask what the page is trying to do. Add the smallest schema set that describes that job accurately.
Content
Article / BlogPosting
- Use it for
- Guides, tutorials, reviews, news-like posts, and long-form explainers.
- Add when
- The page has a clear headline, author or publisher, publish date, modified date, canonical URL, and image.
- Avoid when
- The page is mostly a tool UI, product listing, category page, or thin landing page.
Navigation
BreadcrumbList
- Use it for
- Almost every page below the homepage.
- Add when
- Users can understand where the page sits in the site hierarchy.
- Avoid when
- The breadcrumb path disagrees with internal links, canonical URLs, or visible navigation.
Site identity
WebPage / WebSite / Organization
- Use it for
- Homepage, hubs, about pages, and pages where publisher identity matters.
- Add when
- You want a stable entity graph that connects the page, site, publisher, and language.
- Avoid when
- You are adding WebSite markup only to chase the old sitelinks search box display.
Product or app
Product / SoftwareApplication
- Use it for
- Tools, apps, SaaS pages, extensions, downloadable software, or real product pages.
- Add when
- Visible page content includes name, description, OS or category, price, offers, and ratings when you mark them up.
- Avoid when
- Ratings, price, availability, or reviews are not visible to users on the page.
Questions
FAQPage
- Use it for
- Visible question-and-answer sections that genuinely help users understand the topic.
- Add when
- The Q&A content is useful on the page even if Google does not show FAQ rich results.
- Avoid when
- You add generic Q&A only to take up search space or repeat the same answer across many pages.
Media
VideoObject / ImageObject
- Use it for
- Pages with an important embedded video, tutorial video, or crawlable image asset.
- Add when
- The media is central to the page and has title, description, thumbnail, upload date, and a stable URL.
- Avoid when
- The media is decorative, hidden, blocked, or not relevant to the main page purpose.
Implementation checklist that prevents most mistakes
Good JSON-LD is boring in the best way: consistent, generated from trusted fields, easy to validate, and hard to forget when a page changes.
Pick one main page entity
Decide whether the page is mainly an article, product, app, video, FAQ, collection, or generic web page. Secondary schema should support that main entity.
Match visible content
Every marked-up claim should be visible or clearly inferable on the page: title, author, dates, price, rating, Q&A, breadcrumbs, and images.
Use stable @id values
Give important entities stable IDs such as the canonical URL plus #article, #webpage, #organization, or #faq. This helps parsers connect graph pieces.
Generate from shared metadata
Reuse the same source fields that create title tags, meta descriptions, canonical URLs, Open Graph images, language tags, and last-modified dates.
Keep dates honest
Only change dateModified when meaningful page content changed. Do not refresh dates automatically just to look newer in search results.
Make images crawlable
Use absolute image URLs, suitable dimensions, and files that are not blocked by robots, authentication, or lazy-loading-only rendering.
Render early
In Blazor and other JavaScript apps, prefer prerendered or server-rendered JSON-LD so crawlers see it in the initial HTML response.
Validate and monitor
Run the Rich Results Test before publishing, check Schema Markup Validator for syntax, and watch Search Console after indexing.
A clean JSON-LD pattern for Blazor pages
For Blazor, the safest pattern is to build schema from page metadata during initialization or prerendering, serialize it once, and render the application/ld+json script where crawlers can see it in the initial HTML.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"@id": "https://example.com/en/json-ld-schema-guide/#article",
"headline": "JSON-LD Schema Markup Guide for Practical SEO",
"description": "A practical guide to choosing, generating, and validating structured data.",
"image": "https://example.com/images/json-ld-guide.png",
"datePublished": "2026-03-28T10:00:00+00:00",
"dateModified": "2026-05-31T10:00:00+00:00",
"author": {
"@type": "Organization",
"name": "Example Publisher"
},
"publisher": {
"@type": "Organization",
"name": "Example Publisher",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png"
}
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://example.com/en/json-ld-schema-guide/"
}
}
</script>private MarkupString BuildJsonLd(PageMetaData meta)
{
var pageUrl = BuildPageUrl(meta);
var schema = new Dictionary<string, object?>
{
["@context"] = "https://schema.org",
["@type"] = "Article",
["@id"] = $"{pageUrl}#article",
["headline"] = meta.Title,
["description"] = meta.Description,
["url"] = pageUrl,
["datePublished"] = meta.Published?.ToString("O"),
["dateModified"] = meta.Modified?.ToString("O"),
["inLanguage"] = CS.Culture
};
var json = JsonSerializer.Serialize(schema, new JsonSerializerOptions
{
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
});
return new MarkupString($"<script type=\"application/ld+json\">{json}</script>");
}Validate JSON-LD before you rely on it
Validation has two different jobs. The Schema Markup Validator checks whether the vocabulary and JSON-LD syntax are understandable. Google's Rich Results Test checks whether Google recognizes the page as eligible for supported rich result types.
Google eligibility
Rich Results Test
Checks whether Google can read the page and whether detected structured data is eligible for supported rich result types.
Open Rich Results TestVocabulary
Schema Markup Validator
Checks general schema.org structure and JSON-LD syntax, including types, properties, nested entities, and malformed JSON.
Open Schema Markup ValidatorAfter publishing
Search Console
Use URL Inspection and Enhancement reports to spot crawl, indexing, and structured data issues after Google has processed the page.
Read Google structured data docsCommon JSON-LD mistakes that hurt trust
Most schema problems are not complex technical bugs. They are mismatches between what the markup says and what the user or crawler can verify on the page.
Marking up hidden or missing content
If users cannot see the answer, review, offer, image, or author claim, do not put it in structured data. This is the fastest way to lose trust.
Adding FAQPage to everything
FAQ schema can still describe visible Q&A, but it should not be a copy-paste block across every article. Use it only when the Q&A improves the page.
Conflicting duplicate scripts
Multiple Article blocks with different headlines, dates, or URLs make the page harder to interpret. One clear graph is better than three partial ones.
Wrong canonical or @id
Schema URLs should match the canonical page, culture URL, and hreflang setup. Mixed language URLs create duplicate-content and entity confusion.
Fake freshness
Do not bump dateModified for template edits, tracking changes, or schema-only updates. Use the date for real content changes.
Client-only late rendering
If JSON-LD appears only after a delayed client render, crawlers may miss it. Prefer server rendering or prerendering for important pages.
Practical schema recipes by page type
You rarely need a giant graph. These combinations cover the pages most small sites, blogs, tools, and review projects actually publish.
Guide article
Article + BreadcrumbList + WebPage
- Use Article for headline, author, publisher, image, dates, and section names.
- Use BreadcrumbList for the visible site path.
- Use WebPage or @id references to connect the page and article entity.
Tool page
SoftwareApplication + WebPage + BreadcrumbList
- Use SoftwareApplication only if the page is about a real app or tool.
- Include operating system, category, price or offer details only when visible.
- Avoid review or rating markup unless the page shows real review data.
Review page
Review / Product only when the page supports it
- Mark up the reviewed item, author, date, and rating only when the page clearly shows them.
- Keep affiliate links and commercial context transparent.
- Use the same score in schema and visible content.
Question page
FAQPage only for useful visible Q&A
- Make each answer helpful by itself, not just a keyword variant.
- Do not hide answers behind blocked UI that crawlers cannot access.
- Do not expect FAQ rich results as the main SEO benefit.
Sources checked
Research sources for this guide
The guidance above is based on official Google Search Central and schema.org documentation, then turned into a practical JSON-LD checklist.
JSON-LD schema markup FAQ
Is JSON-LD schema markup a ranking factor?
JSON-LD itself is not a magic ranking switch. It helps search engines understand eligible content and can support rich result eligibility, but rankings still depend on content quality, relevance, crawlability, links, and many other signals.
Where should JSON-LD go on a page?
A script tag in the head is usually easiest to manage, but Google can also read JSON-LD in the body. The important part is that the markup is present in the rendered page and matches visible content.
Should I still use FAQPage schema?
Use FAQPage only when the page has genuinely useful visible questions and answers. Do not rely on it for extra Google result space, because FAQ rich result display has been heavily reduced and deprecated for most regular sites.
Can one page have multiple JSON-LD blocks?
Yes. A normal article page can have Article, BreadcrumbList, and WebPage data. Keep the blocks consistent, avoid duplicate conflicting entities, and use stable @id values to connect related pieces.
Is JSON-LD better than Microdata?
For most modern sites, yes. Google supports JSON-LD, Microdata, and RDFa, but JSON-LD is usually easier to maintain because it does not require schema attributes inside visual HTML templates.
How often should I validate structured data?
Validate whenever you change templates, metadata fields, schema helpers, URLs, language routing, image generation, review data, or FAQ sections. Also check Search Console after important pages are indexed.