JSON-LD (JavaScript Object Notation for Linked Data) is a format for adding structured data to a web page. It describes what a page is about, such as an article, a product, a business or an FAQ, in a machine-readable block of code that search engines and other systems can parse without guessing.
It's also Google's recommended format for schema markup, which makes it the version most site owners will run into.
What is JSON-LD?
JSON-LD is a way of writing linked data using JSON, the lightweight data format used across the web. The JSON-LD 1.1 specification became a W3C Recommendation in July 2020. On a web page, JSON-LD lives inside a script tag with the type application/ld+json, usually in the page head, and it doesn't change what visitors see.
A few keywords do most of the work:
- @context sets the vocabulary. For SEO, this is almost always https://schema.org.
- @type says what kind of thing you're describing, such as Organization, Article, Product or FAQPage.
- @id gives a thing a unique identifier (usually a URL), so different blocks can refer to the same entity.
Everything else is properties from the vocabulary, such as name, url, logo, author or datePublished.
Why JSON-LD matters
Structured data helps search engines understand a page's content and, for supported types, makes the page eligible for rich results like review stars, product details or event listings. Google's structured data introduction lists three supported formats: JSON-LD, Microdata and RDFa. Google says all three are fine if implemented correctly, but it recommends JSON-LD when your setup allows, because it's the easiest to implement and maintain at scale.
Eligibility isn't a guarantee. Google's structured data policies state plainly that it doesn't guarantee your structured data will appear in results. Google presents structured data as a way to understand pages and enable search features, not as a ranking boost.
For GEO, JSON-LD is useful because it states facts clearly: who your organization is, who wrote an article, what a product costs. How individual AI systems use structured data isn't fully documented, so treat it as a clarity signal rather than a guaranteed path into AI answers.
How JSON-LD works
A simple example
Here's how a hypothetical bakery might describe itself in JSON-LD. The block sits in a script tag of type application/ld+json:
{"@context": "https://schema.org", "@type": "Bakery", "name": "Example Bakery", "url": "https://www.example.com", "telephone": "+1-555-0100", "address": {"@type": "PostalAddress", "streetAddress": "123 Main St", "addressLocality": "Springfield", "addressRegion": "IL"}}
Notice the nesting: the address is its own typed object inside the business. That separation from visible HTML is what makes JSON-LD easier to manage than Microdata or RDFa, which wrap attributes around page elements.
Adding JSON-LD to a page
You can hard-code it in templates, use a CMS field or plugin, or generate it with JavaScript. Google says it can read JSON-LD injected dynamically, and its guide to generating structured data with JavaScript covers Google Tag Manager and custom scripts. Server-rendered JSON-LD is still the safer choice, since some crawlers don't run JavaScript.
Testing it
Google recommends the Rich Results Test during development and Search Console's rich result reports after launch. The Schema Markup Validator, run by schema.org, checks general schema.org markup beyond the types Google supports.
JSON-LD best practices
- Mark up only what's visible. Google's policies require structured data to be a true representation of the page content. Don't describe reviews, prices or FAQs that users can't see.
- Include all required properties for the rich result type you want. Missing required fields make the page ineligible.
- Use the most specific type. Bakery is more useful than LocalBusiness, and LocalBusiness more useful than Organization.
- Connect entities with @id. Give your Organization a stable @id and reference it as the publisher on every article.
- Add sameAs links to your official profiles, which helps tie your brand to its entry in a knowledge graph.
- Keep it in sync. When prices, hours or authors change, update the JSON-LD. Generating it from the same data as the page helps.
- Retest after template changes. A theme update can silently break or duplicate markup.
Common JSON-LD mistakes
- Syntax errors. A missing comma or a curly quote copied from a word processor breaks the whole block.
- Marking up hidden or false content. This can lead to a manual action that removes rich result eligibility, according to Google.
- Duplicate or conflicting blocks. A plugin and a theme both outputting Organization markup with different details sends mixed signals.
- Expecting instant rich results. Valid markup makes a page eligible. Google decides whether to show the feature.
JSON-LD vs. schema markup
The terms often get used interchangeably, but they're different layers. Schema.org is the vocabulary, the list of types and properties. JSON-LD is one syntax for writing that vocabulary into a page. You can write schema.org markup in Microdata or RDFa too; JSON-LD is simply the one Google recommends.
How Butter approaches JSON-LD
At Butter, structured data is part of how we help brands become easy for search engines and AI systems to understand. Our GEO plan includes schema markup guidance and knowledge graph submissions, and JSON-LD is the natural format for it because it's what Google recommends and what most platforms support. We focus on the basics first: a clean Organization block with sameAs links, accurate Article and author markup, and types that match what's actually on the page. We don't promise rich results or AI citations from markup alone.
Frequently asked questions
Is JSON-LD better than Microdata?
Google says all three supported formats work equally well when implemented correctly. It recommends JSON-LD because it's easier to add and maintain, and it keeps structured data separate from your visible HTML.
Where should JSON-LD go on a page?
Google accepts JSON-LD in either the head or the body of the page. Many sites place it in the head for tidiness, but Google's documentation supports either location.
Does JSON-LD improve rankings?
Not directly. Google doesn't present structured data as a ranking boost. It helps search engines understand your content and can make pages eligible for rich results, which may make your listing more noticeable.