Practical guide to structured data
Practical JSON-LD Schema Markup Guide for SEO
JSON-LD helps search engines grasp what a page is, who published it, its place in your site, and which facts support search features.
The goal is not to add every schema type but to provide accurate structured data that matches visible content, validates cleanly, and stays updated with content changes.
The useful short version
Use JSON-LD to describe honest, visible facts like title, description, author, publication date, breadcrumbs, product details, video data, or clear Q&A. Avoid marking up content users cannot see or features Google no longer displays.
Contents
What JSON-LD actually does
JSON-LD is a machine-readable block of structured data, usually placed in a script tag in the head or body, describing entities with schema.org vocabulary. Search engines use it to clarify visible content.
Parser clarity
Meaning
It converts page facts into named entities and properties like Article, author, datePublished, BreadcrumbList, or SoftwareApplication.
Search feature
Eligibility
It can qualify a page for rich results, but Google decides what to display based on quality, policy, query, and feature availability.
Site graph
Consistency
It provides your CMS or Blazor app a single structured source to reuse canonical URL, language, title, dates, images, and publisher data.
No shortcuts
Limit
It does not fix poor content, fake reviews, hidden FAQ answers, outdated dates, or mismatched structured data.
Select schema based on the page’s purpose
The simplest way to avoid spammy or duplicate structured data is to identify the page’s purpose and add the minimal schema set that accurately describes it.
Content
Article / BlogPosting
- Use it for
- Guides, tutorials, reviews, news-style posts, and detailed explainers.
- Add when
- The page features a clear headline, author or publisher, publish date, modified date, canonical URL, and image.
- Avoid when
- The page is primarily a tool UI, product listing, category page, or thin landing page.
Navigation
BreadcrumbList
- Use it for
- Nearly every page beneath the homepage.
- Add when
- Users can see where the page fits within the site hierarchy.
- Avoid when
- The breadcrumb path conflicts 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 is important.
- Add when
- You need a stable entity graph linking the page, site, publisher, and language.
- Avoid when
- You are adding WebSite markup solely to pursue the outdated sitelinks search box display.
Product or app
Product / SoftwareApplication
- Use it for
- Tools, apps, SaaS pages, extensions, downloadable software, or genuine product pages.
- Add when
- Visible page content includes name, description, OS or category, price, offers, and ratings when marked up.
- Avoid when
- Ratings, price, availability, or reviews are not visible to users on the page.
Questions
FAQPage
- Use it for
- Visible Q&A sections that genuinely assist users in understanding the topic.
- Add when
- The Q&A content is helpful on the page even if Google does not display FAQ rich results.
- Avoid when
- You add generic Q&A merely to occupy search space or duplicate the same answer across multiple pages.
Media
VideoObject / ImageObject
- Use it for
- Pages featuring key embedded videos, tutorial videos, or crawlable image assets.
- Add when
- The media is central to the page and includes title, description, thumbnail, upload date, and a stable URL.
- Avoid when
- The media is decorative, hidden, blocked, or irrelevant to the main page purpose.
Implementation checklist to avoid common errors
Good JSON-LD is reliably consistent: generated from trusted fields, easy to validate, and updated alongside page changes.
Select one primary page entity
Determine if the page is primarily an article, product, app, video, FAQ, collection, or generic web page. Secondary schema should complement the main entity.
Align with visible content
All marked-up claims must be visible or clearly deducible on the page: title, author, dates, price, rating, Q&A, breadcrumbs, and images.
Use stable @id values
Assign stable IDs to key entities like the canonical URL plus #article, #webpage, #organization, or #faq to help parsers link graph components.
Generate from shared metadata
Reuse the same source fields that generate title tags, meta descriptions, canonical URLs, Open Graph images, language tags, and last-modified dates.
Maintain accurate dates
Update dateModified only for significant content changes. Avoid automatic date refreshes just to appear newer in search results.
Make images accessible to crawlers
Use absolute image URLs with appropriate dimensions, ensuring files aren’t blocked by robots, authentication, or lazy-loading-only rendering.
Render early
In Blazor and similar JavaScript apps, prefer prerendered or server-rendered JSON-LD so crawlers can access it in the initial HTML.
Validate and monitor
Run the Rich Results Test before publishing, verify syntax with Schema Markup Validator, and monitor Search Console after indexing.
A clear JSON-LD pattern for Blazor pages
For Blazor, the safest approach is to generate schema from page metadata during initialisation or prerendering, serialize once, and render the application/ld+json script in the initial HTML for crawlers.
<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 relying on it
Validation serves two purposes: Schema Markup Validator checks vocabulary and JSON-LD syntax, while Google’s Rich Results Test verifies eligibility for supported rich result types.
Google eligibility
Rich Results Test
Checks if Google can read the page and if the structured data qualifies for supported rich result types.
Open Rich Results TestVocabulary
Schema Markup Validator
Verifies 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 identify crawl, indexing, and structured data issues after Google processes the page.
Read Google structured data documentationFrequent JSON-LD errors that damage trust
Most schema issues are not complex technical errors but discrepancies between markup and what users or crawlers can verify on the page.
Marking hidden or absent content
If users cannot see answers, reviews, offers, images, or author claims, do not include them in structured data. This quickly erodes trust.
Adding FAQPage everywhere
FAQ schema can describe visible Q&A but should not be copied across all articles. Use only when it enhances the page.
Conflicting duplicate scripts
Multiple Article blocks with differing headlines, dates, or URLs complicate interpretation. One clear graph is preferable to several partial ones.
Incorrect canonical or @id
Schema URLs must match the canonical page, culture URL, and hreflang setup. Mixed-language URLs cause duplicate content and entity confusion.
False freshness
Only update dateModified for significant content changes, not for template edits, tracking, or schema-only updates.
Client-only delayed rendering
If JSON-LD loads only after delayed client rendering, crawlers might miss it. Prefer server or prerendering for key pages.
Practical schema examples by page type
You seldom require a large graph. These combinations cover most pages published by small sites, blogs, tools, and review projects.
Guide article
Article + BreadcrumbList + WebPage
- Use Article schema for headline, author, publisher, image, dates, and section names.
- Use BreadcrumbList for the visible site navigation path.
- Use WebPage or @id references to link the page and article entity.
Tool page
SoftwareApplication + WebPage + BreadcrumbList
- Use SoftwareApplication only if the page concerns a genuine app or tool.
- Include operating system, category, price, or offer details only if visible.
- Avoid review or rating markup unless genuine review data is displayed on the page.
Review page
Review/Product only if the page supports it
- Mark up reviewed items, authors, dates, and ratings only if clearly visible on the page.
- Maintain transparency for affiliate links and commercial context.
- Ensure the score in schema matches the visible content.
Question page
FAQPage only for genuinely helpful visible Q&A
- Ensure each answer is independently helpful, not merely a keyword variation.
- Avoid hiding answers behind UI elements inaccessible to crawlers.
- Do not rely on FAQ rich results as the primary SEO advantage.
Sources checked
Research sources for this guide
The above guidance is based on official Google Search Central and schema.org documentation, converted into a practical JSON-LD checklist.
FAQs
Is JSON-LD schema markup a ranking factor?
JSON-LD is not a magic ranking tool. It aids search engines in understanding eligible content and rich result eligibility, but rankings depend on quality, relevance, crawlability, links, and more.
Where should JSON-LD be placed on a page?
A script tag in the head is generally easiest to handle, though Google can also read JSON-LD in the body. Crucially, the markup must be present in the rendered page and correspond with visible content.
Should I still use FAQPage schema?
Use FAQPage only for genuinely useful visible questions and answers. Do not depend on it for extra Google result space, as FAQ rich results have been largely reduced and deprecated for most sites.
Can a single page contain multiple JSON-LD blocks?
Yes. A typical article page can include Article, BreadcrumbList, and WebPage data. Keep blocks consistent, avoid duplicate conflicting entities, and use stable @id values to link related parts.
Is JSON-LD superior to Microdata?
For most modern sites, yes. Google supports JSON-LD, Microdata, and RDFa, but JSON-LD is generally easier to maintain as it avoids schema attributes within visual HTML templates.
How frequently should I validate structured data?
Validate whenever templates, metadata, schema helpers, URLs, language routing, image generation, review data, or FAQ sections change. Also monitor Search Console after key pages are indexed.