JSON-LD is a format for structured data that lets you describe a page and its key entities in a machine readable way. Google recommends JSON-LD for structured data, and says it can help search engines understand page content and support eligibility for rich results on some page types.
In simple terms, JSON-LD gives you a cleaner way to label what a page is about.
It does not replace strong copy. It does not fix a weak page. It supports a page that already has clear structure and a clear role in the site. Google’s structured data guidelines make that clear by tying eligibility to content, technical rules, and feature specific guidance.
What JSON-LD is
JSON-LD stands for JavaScript Object Notation for Linked Data. On web pages, it is commonly added inside a <script type="application/ld+json"> block. Google’s documentation points publishers to JSON-LD as the recommended format, while also saying that Microdata and RDFa are supported for rich result eligibility.
That makes JSON-LD a good starting point for most SEO teams.
It is separate from the visible HTML. It is easier to audit. It is easier to update when the page changes. It keeps the markup cleaner for developers and content teams. This ease of use is a practical implementation benefit inferred from Google’s recommendation and from the fact that JSON-LD sits outside the visible markup.
Why Google recommends JSON-LD
Google’s docs say JSON-LD is the recommended format for structured data. Google also says structured data is a standardized format for providing information about a page and classifying page content.
For SEO, that gives you a few benefits:
- cleaner markup management
- clearer page typing
- stronger support for entities and attributes
- eligibility for supported rich results when the page and markup fit Google’s rules
This is why JSON-LD fits so closely with Schema for SEO, Entity Markup, and Entity Relationships.
JSON-LD vs Microdata and RDFa
Google’s general structured data guidelines list three supported formats for rich result eligibility:
- JSON-LD
- Microdata
- RDFa
Google recommends JSON-LD from those three.
The difference is simple.
Microdata and RDFa are placed within the HTML itself.
JSON-LD sits in its own script block, which can make implementation cleaner and easier to maintain. That cleaner workflow is an implementation inference from how the formats are placed on the page.
For most sites, that cleaner separation is a strong reason to start with JSON-LD.
What JSON-LD can describe
JSON-LD uses the Schema.org vocabulary. Schema.org is the shared vocabulary that defines types and properties used across structured data, including broad types like Thing and properties such as sameAs and mainEntityOfPage.
That means JSON-LD can describe things like:
- articles
- organizations
- products
- FAQ pages
- datasets
- people
- places
- relationships between entities through recognized properties
This is one reason JSON-LD pairs so well with Entity SEO, Entity Attributes, and Entity Co-occurrence.
A simple JSON-LD example
Here is a basic example for an article page:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "JSON-LD Basics: A Clean Starting Point for Schema in SEO",
"author": {
"@type": "Person",
"name": "Kevin Maguire"
},
"publisher": {
"@type": "Organization",
"name": "Semantec SEO",
"url": "https://semantecseo.com/"
},
"mainEntityOfPage": "https://semantecseo.com/schema/json-ld-basics/"
}
</script>
Google’s Article documentation shows that article pages can use structured data to help Google understand the page, and it encourages publishers to add recommended properties that fit the page. Schema.org also documents properties like mainEntityOfPage, which help clarify which entity or page sits at the center.
The key point is not to copy this block blindly.
The goal is to match the markup to the page truthfully.
The parts of a JSON-LD block
A simple JSON-LD block often includes:
@contextto declare the vocabulary@typeto declare the schema type- properties that describe the page or entity
- references such as URLs that help identify the entity or page
These patterns come directly from Schema.org’s vocabulary model and from Google’s structured data examples across supported feature pages.
Two fields deserve extra attention:
@context
This tells parsers which vocabulary the markup is using. In most SEO use cases, that is https://schema.org. Schema.org’s own examples and Google’s examples use that pattern.
@type
This tells search engines what kind of thing the block describes, such as Article, FAQPage, Product, or Organization. Google’s Search gallery is built around supported types and feature pages, and Schema.org defines the broader type system underneath them.
How to choose the right type
Start with the page goal.
Ask what the page is:
- an article
- a product page
- an FAQ page
- a dataset page
- an organization page
Then choose the schema type that fits the visible page. Google’s feature docs follow this same pattern: page type first, markup second. Google also says markup must follow feature guidelines and content rules to stay eligible for supported search features.
This is where many sites go off track. They pick a type because they want a search feature, not because the page fits that type.
JSON-LD and entities
JSON-LD is especially useful for entity clarity.
Schema.org’s model includes properties like sameAs, which points to pages that identify the same thing, and mainEntityOfPage, which helps clarify which entity or topic is central to the page.
For SEO, that can support:
- organization identity
- person identity
- product identity
- page to entity alignment
- stronger consistency between visible content and markup
That is why JSON-LD fits naturally with Entity Map, Contextual Entity Integration, and Entity Markup.
JSON-LD and rich results
Google says structured data can help pages become eligible for rich results, and its Search gallery lists the supported structured data powered features in Google Search. That support depends on the page type, the markup, and compliance with Google’s rules.
That means JSON-LD can support page types like:
- articles
- FAQs
- products
- datasets
- organizations
- review snippets, where the page fits Google’s rules
But it still does not guarantee a rich result. Google says eligibility and display are not the same thing.
How to add JSON-LD cleanly
1. Start with a page that already makes sense
Strong markup supports strong content.
If the page is vague, thin, or badly structured, JSON-LD will not rescue it.
That is why JSON-LD belongs after page planning, not before it. See Topical Map Process and Entity Led Brief.
2. Pick one clear schema type
Do not throw several unrelated types onto the page.
Choose the one that best matches the page role, then add the properties that fit.
Google’s type specific docs repeatedly say to add the properties that apply to the page and to follow feature guidelines.
3. Match the visible content
The markup should reflect what the user can see on the page.
If the content is not visible, do not invent it in the JSON-LD.
Google’s structured data policies tie eligibility to visible, guideline compliant content.
4. Keep it updated
When the page changes, the markup should change too.
Old values, dead URLs, stale authorship fields, or wrong types can weaken the implementation and create debugging issues. That maintenance advice is a practical implementation inference from Google’s testing and compliance guidance.
5. Test it
Google recommends testing structured data with the Rich Results Test, and its documentation also points teams to Search Console and URL Inspection for monitoring and debugging.
That helps you separate:
- syntax problems
- unsupported markup
- feature eligibility issues
- crawl or indexing issues
Common mistakes
Mistake 1: Using JSON-LD on the wrong page type
A page should be marked up for what it is, not for the feature you hope to trigger. Google’s type guides and policy pages are explicit about fitting markup to the page.
Mistake 2: Adding properties that do not fit
Google’s guidance says to add properties that apply to your content. A cluttered block with weak or irrelevant properties is not better than a smaller clean block
Mistake 3: Forgetting the visible page
JSON-LD should support the page the user sees.
If the copy, the internal links, and the markup tell three different stories, the page gets weaker.
Mistake 4: Skipping testing
Rich result eligibility is not something to guess at. Google provides the Rich Results Test for this, and Search Console can help monitor structured data issues over time.
How MIRENA would use JSON-LD
MIRENA would treat JSON-LD as a support layer that comes after the page structure is clear.
That means the sequence is:
- define the page goal
- define the main entity
- build the section structure
- connect the page into the cluster
- choose the schema type that fits
- add JSON-LD to support the same page meaning
That keeps the markup aligned with the page, the entity focus, and the wider internal link system.
See MIRENA, Schema for SEO, and Drafting + Rewriting.
Quick checklist
- Is the page type clear?
- Does the chosen
@typefit the visible page? - Does the block use
https://schema.orgas the context? - Do the properties describe the page truthfully?
- Is the page still strong without the markup?
- Has the markup been tested in Google’s tools?
If not, fix the page and the implementation before adding more fields.
FAQ
What is JSON-LD in SEO?
JSON-LD is a structured data format that lets you describe page content and entities in a machine readable way. Google recommends it for structured data.
Is JSON-LD better than Microdata?
Google supports JSON-LD, Microdata, and RDFa for rich result eligibility, and recommends JSON-LD. For many teams, JSON-LD is easier to manage because it sits outside the visible HTML.
Does JSON-LD guarantee rich results?
No. Google says structured data can support eligibility for rich results, but it does not guarantee that a page will show with a rich result.
Can JSON-LD help with entities?
Yes. JSON-LD can support entity identity and page to entity alignment through Schema.org types and properties such as sameAs and mainEntityOfPage.
What is the first JSON-LD mistake to avoid?
The first big mistake is choosing a schema type that does not fit the visible page. Start with the page role, then choose the markup.
Final take
JSON-LD is the cleanest starting point for schema on most SEO pages because Google recommends it and supports it across rich result eligible page types. It works best when it supports a page that already has a clear role, a clear entity focus, and a clean place in the site structure.
Build the page first. Add the markup second. Then connect it to Entity Markup, FAQ Schema, and Product Schema for SaaS.
Leave a Reply