Websites · Glossary
What is JSON-LD?
JSON-LD, JavaScript Object Notation for Linked Data, is a W3C format for describing things as structured data. On websites it sits in a script tag of type application/ld+json and uses schema.org vocabulary to tell search engines what a page is about, such as a local business, a product, an event or a set of FAQs.
JSON-LD is the format Google recommends for structured data. It lives apart from the visible page, so you can describe a business's hours or an event's date without changing the design.
Nuwan Madhusanka · Co-founder
4 min read · Published
| Type | Describes | Key properties |
|---|---|---|
| LocalBusiness (or a subtype such as Restaurant) | The business itself | name, address, telephone, openingHoursSpecification, geo |
| Product | An item for sale | name, image, offers with price and priceCurrency |
| Event | A dated event | name, startDate, location, offers |
| Article | A blog post or news item | headline, author, datePublished |
| FAQPage | Questions and answers on the page | mainEntity with Question and acceptedAnswer |
| BreadcrumbList | Where the page sits in the site | itemListElement with position, name, item |
What it is
JSON-LD is a W3C recommendation for expressing linked data in JSON. Each object names its vocabulary with @context, usually https://schema.org, and its kind with @type, then lists properties. On a web page, the object goes inside a script element with type application/ld+json, typically in the head. Browsers ignore it, but crawlers read it. Unlike microdata or RDFa, which add attributes to visible HTML elements, JSON-LD is a separate block, which is why it is easier to write, maintain and generate from data.
How search engines use it
Search engines read structured data to understand a page and, for supported types, to show rich results: star ratings on products, dates on events, opening hours and a map pin for a local business, breadcrumbs instead of a raw URL. Google's documentation lists which types it supports and the required and recommended properties for each, and its Rich Results Test shows whether a page qualifies. Structured data makes a page eligible for these features; it does not guarantee them, and Google decides when to show them.
When it matters
For a local business, the LocalBusiness markup with correct name, address, phone and hours supports the details search engines show about it. For a shop, Product markup with a price and availability can add those details to results. For a venue, Event markup can list upcoming dates. For a blog, Article markup clarifies the author and date. If your site has none of these, a basic Organization or LocalBusiness block is still worth adding.
Common mistakes
Marking up content that is not visible on the page, such as reviews nobody can read, which breaks Google's guidelines. Giving prices or hours in the markup that differ from the page. Leaving placeholder values from a template. Using the generic LocalBusiness type when a more specific subtype exists. Adding FAQ markup to pages where the questions are promotional. Forgetting to update dates on events, so past events stay marked up. And testing once, then never again after the page changes.
Where it shows up in OneCraft
Every OneCraft website gets a title and description on each route, plus a canonical and og:url from the site's address. With the seo capability guide, the agent also writes Open Graph tags, JSON-LD (LocalBusiness or a subtype, Product, Event, Article, FAQPage and BreadcrumbList as the pages need) and a robots.txt. A sitemap.xml is written by hand only when the domain is known; there is no automatic sitemap and no SEO settings card.
Questions people ask
Is JSON-LD better than microdata?
Google supports both and recommends JSON-LD because it is easier to add and maintain. Microdata mixes attributes into visible HTML, so a design change can break it. JSON-LD sits in one block that can be generated from the same data as the page. Either works if it is valid and matches the visible content.
Does JSON-LD improve rankings?
Not directly. Structured data helps search engines understand a page and makes it eligible for rich results, which can improve how a listing looks and how often people click it. It does not replace useful content, good titles or links, and invalid or misleading markup can make a page lose rich results.
Where do I put JSON-LD on a page?
Inside a script element with type application/ld+json, usually in the head, although the body also works. A page can have several blocks, such as one for the business and one for breadcrumbs. Search engines read blocks added by JavaScript too, but blocks in the initial HTML are read most reliably.
How do I test my structured data?
Use Google's Rich Results Test to see which rich results a page qualifies for and any errors, and the Schema Markup Validator for general schema.org checks. After publishing, the enhancement reports in Search Console show errors across the whole site over time.
Can I add FAQ schema to every page?
You can mark up real question and answer content wherever it appears, but Google has narrowed where FAQ rich results show and has changed its guidance on them, so do not count on a rich result. The markup still describes the page. Never add it to questions the page does not show, and keep answers identical.
Make one with websites
The button opens the generator with this use case already described. Change the wording to match your own.
Create a website with OneCraftRelated questions
- What is robots.txt?What is robots.txt? The plain text file at a site's root that asks crawlers which paths not to fetch, with its directives, examples and limits.
- Static site vs server side renderingStatic site vs server side rendering: pages built once at build time against pages rendered on every request, compared on speed, hosting, fresh data and cost.
- What is a meta description?What is a meta description? The short summary of a page in its HTML that search engines may show under the title. How long to make it and how to write one.
- What is a hydration error in React?What is a hydration error? When server rendered HTML and React's first render in the browser disagree. Common causes, how to read the message and how to fix it.
Written and checked by the OneCraft team. Last checked .