Skip to content

What is JSON-LD, and how do you write it for a local business?

By Bhavesh Barot

Updated
Reading time
9 min read
Guide number
No. 017
A developer with a trimmed beard types at a standing desk while looking at a monitor showing coloured blocks, a small plant in a lime green pot beside him.
On this page
  1. 01Why JSON-LD instead of other formats?
  2. 02What goes in a LocalBusiness JSON-LD block?
  3. 03How do the nested parts work?
  4. 04What about the @id field?
  5. 05How do you mark up a service page?
  6. 06Where do you put the JSON-LD block?
  7. 07How do you test JSON-LD?
  8. 08What mistakes stop JSON-LD from working?
  9. 09Does JSON-LD help with AI answers?
  10. 10A checklist before you publish
  11. 11How does Seen in Search fit in?
  12. 12Questions developers and owners ask about JSON-LD

JSON-LD (JavaScript Object Notation for Linked Data) is a format for writing structured data: a block of labeled facts about a page that search engines and other software can read. It's the format Google recommends for schema markup. On a local business site, a JSON-LD block typically says what kind of business you are, where you are, how to reach you and when you're open.

This guide is for owners and the people who build their sites. It explains what a JSON-LD block contains, walks through a full example for a US dental office one field at a time, and covers where to put it, how to test it and what goes wrong. For the bigger picture of which schema types to use, start with our schema markup guide.

Why JSON-LD instead of other formats?

Structured data can be written three ways: JSON-LD, Microdata and RDFa. Microdata and RDFa add attributes to your existing HTML tags, so the facts are spread through the page. JSON-LD sits in one self-contained script block, separate from the design.

That separation is the practical win. A designer can change the page layout without breaking the markup, and a developer can update the markup without touching the layout. Google's documentation says it recommends JSON-LD and that it can read JSON-LD even when it's added to the page by JavaScript.

What goes in a LocalBusiness JSON-LD block?

Below are the fields of a full example for a fictional dental office in Raleigh, North Carolina. In the page's code, each field is a name in quotes followed by its value, and the whole block sits inside a script tag with the type application/ld+json.

FieldExample valueWhat it tells software
@contexthttps://schema.orgWhich vocabulary the labels come from
@typeDentistWhat kind of business this is; use the most specific type that fits
@idhttps://example-dental.com/#businessA fixed identifier for your business, so other blocks can refer to it
nameOak Street Family DentalYour business name, exactly as on your Google Business Profile
urlhttps://example-dental.com/Your main website address
telephone+1-919-555-0142Your main phone, with country code
addressa PostalAddress with streetAddress, addressLocality, addressRegion, postalCode, addressCountryYour street address, split into parts
geoa GeoCoordinates with latitude and longitudeYour exact location on a map
openingHoursSpecificationa list, each with dayOfWeek, opens, closesYour hours, in 24-hour time
areaServedRaleigh, Cary, GarnerThe places you serve
imagehttps://example-dental.com/office.jpgA photo of your business
priceRangea short text rangeA rough price level, if you choose to state one
sameAslinks to your profiles on other sitesWhich other pages describe the same business

The 555 number and the address are fictional. Use your own facts, and only facts that also appear on the visible page.

How do the nested parts work?

Three fields hold a small block of their own instead of a single value.

address holds a PostalAddress. Each part goes in its own field: street in streetAddress, city in addressLocality, state as the two-letter code in addressRegion, ZIP in postalCode, and US in addressCountry. Splitting it this way stops software from misreading a suite number as part of the city.

geo holds a GeoCoordinates block with latitude and longitude. Google asks for at least five decimal places. You can copy the numbers from Google Maps by right-clicking your location.

openingHoursSpecification holds a list. Each entry gives one or more days, an opening time and a closing time, such as Monday to Thursday, 08:00 to 17:00, then a separate entry for Friday, 08:00 to 13:00. For a day you're closed, leave it out. For special hours, such as a holiday, add an entry with validFrom and validThrough dates.

What about the @id field?

The @id is easy to skip and worth adding. It gives your business a fixed identifier, usually your homepage address followed by #business or #organization. Other JSON-LD blocks on your site, such as a Service on a service page or the publisher of a blog post, can then point to that identifier instead of repeating your details. One definition, referenced everywhere, means fewer conflicting copies.

How do you mark up a service page?

On each service page, add a Service block. Its key fields:

FieldExample value
@typeService
nameEmergency dental visits
serviceTypeEmergency dentistry
providera reference to your business @id
areaServedRaleigh
descriptionone or two plain sentences that match the page

Keep the description in step with the visible text. If the page says you see emergency patients on Saturdays, the description can say so too; if it doesn't, the markup shouldn't.

Get my free report

Check whether ChatGPT names your business when buyers ask about your services. One free report per business. Use your business email. No card.

Where do you put the JSON-LD block?

Google reads JSON-LD in the head or the body of the page. Common choices:

  1. The homepage, or the contact page, carries the main LocalBusiness block.
  2. Each service page carries a Service block that refers to the business by its @id.
  3. Each location page, for firms with several offices, carries its own LocalBusiness block with that office's address, phone and hours. Don't put every office on the homepage in one block.
  4. Blog posts carry an Article or BlogPosting block with the author, headline and dates.

If your site runs on WordPress or a website builder, a plugin or the platform may already output some of this. Check what's there before adding your own, or you'll end up with two conflicting blocks.

How do you test JSON-LD?

Test every page template, starting with the homepage.

  1. Paste the page address into Google's Rich Results Test. It shows the structured data Google found and any errors in the types it supports.
  2. Paste the same address into the Schema Markup Validator at validator.schema.org. It checks all Schema.org types, including ones Google doesn't use for rich results.
  3. In Google Search Console, watch the Enhancements reports. They list errors across the whole site as Google crawls it.

A clean test means Google can read the markup. It doesn't mean Google will show a rich result; that's Google's call.

What mistakes stop JSON-LD from working?

MistakeWhat happensFix
A missing comma or bracketThe whole block fails to parse and is ignoredRun it through a validator after every edit
Curly quotes from a word processorThe block fails to parseWrite it in a code editor, never in a document tool
Facts not on the visible pageBreaks Google's guidelines; may be ignored or penalizedMark up only what visitors can see
Phone or address differs from your Business ProfileConflicting facts across the webUse one exact version everywhere
Self-serving review stars on LocalBusinessGoogle doesn't show themRemove them
Several plugins each adding a blockDuplicate businesses on one pageKeep one source
Hours not updated for a changeWrong hours spread to other softwareUpdate markup with the page

Curly quotes catch more people than you'd expect. JSON needs straight quotation marks. Text pasted from a word processor or an email often converts them, and one bad quote breaks the whole block.

Does JSON-LD help with AI answers?

Indirectly. Google's AI features use its search index, and structured data helps Google understand pages in that index. AI tools that browse the web read the page, markup included. Google's guidance on AI features doesn't list any special markup as required, though, and no AI company has published how much weight it gives to markup.

The safe view: JSON-LD makes your basic facts unambiguous. The text of the page does the persuading. If you want AI tools to name you, the bigger levers are clear service pages, consistent facts across listings and mentions on sites those tools read. Our post on how to rank in ChatGPT covers those.

A checklist before you publish

  1. The @type is the most specific one that fits.
  2. Name, address and phone match your Google Business Profile exactly.
  3. Hours are in 24-hour time and match the page.
  4. The block passes both validators.
  5. Only one block describes the business on each page.
  6. Someone owns updates when facts change.

How does Seen in Search fit in?

JSON-LD helps machines read your facts. Whether AI tools name you is a separate question, and you can measure it. A Seen in Search report reads your homepage, writes buyer questions based on what you sell, puts them to AI assistants and scores how visible you are in the answers, in code, with fixed, published weights. The free report checks ChatGPT. The full paid report covers ChatGPT, Google AI Overviews and Perplexity. Our methodology page explains the score. Reports are private when they finish.

Questions developers and owners ask about JSON-LD

Is JSON-LD the same as schema markup?
No. Schema markup means structured data that uses the Schema.org vocabulary. JSON-LD is one format for writing it, alongside Microdata and RDFa. On most modern sites, schema markup is written in JSON-LD, so the two terms often get used as if they were the same thing. Google recommends the JSON-LD format.
Where do I put JSON-LD in WordPress?
Most WordPress SEO plugins generate JSON-LD from their settings, so start there and fill in your business type, address, phone and hours. For custom blocks, add a script tag with the type application/ld+json to the page through your theme or a plugin that inserts code. Avoid running two plugins that both output business markup.
Can JSON-LD go in the body instead of the head?
Yes. Google reads JSON-LD in either place, and also when JavaScript adds it to the page after loading. The head is a common choice because it keeps the markup apart from the content, but placement in the body is fine. What matters is that the block is valid and describes the page it sits on.
How many JSON-LD blocks can a page have?
As many as it needs, as long as they don't contradict each other. A service page might carry a BreadcrumbList block and a Service block. You can also combine several items in one block using a graph. Avoid two separate blocks both describing your business with different details; software can't tell which is right.
What is the @id in JSON-LD?
It's a fixed identifier for a thing, usually a web address followed by a fragment such as #business. Other blocks can point to it instead of repeating details. For a local business, give your main LocalBusiness block an @id and reference it from your Service and Article blocks, so your business details exist in one place.
Why does Google ignore my JSON-LD?
Common reasons: a syntax error, such as a missing comma or curly quotes, stops it parsing; the type isn't one Google uses for rich results; the markup describes content that isn't visible; or the page isn't indexed. Run the Rich Results Test first. If the block parses and the page is indexed, Google may simply choose not to show a rich result.
Should every page have LocalBusiness JSON-LD?
No. Put the full LocalBusiness block on the page that represents the business, usually the homepage or the contact page, and one per location page for firms with several offices. Other pages can reference the business by its @id when needed, such as a Service block's provider field.
Can I generate JSON-LD with a free tool?
Yes. Several free generators let you fill in a form and copy the result. Check the output in a validator, make sure it uses the right subtype, and confirm the facts match your visible page and Business Profile. Generated code is a starting point, not a finished job.
Does JSON-LD slow down my website?
A typical LocalBusiness block is a few kilobytes of text and has no visible effect on load time. It doesn't load images or run code. If your site feels slow, look at images, fonts and third-party scripts first. Markup is rarely the cause.
Do AI tools like ChatGPT read JSON-LD?
AI tools that browse the web read the page's code, which includes JSON-LD, but OpenAI and other AI companies haven't published how much weight they give it. Treat JSON-LD as a way to make your facts unambiguous. The visible text, consistent listings and third-party mentions do more to get you named.
Get my free report

One free report per business, private unless you publish it. Use your business email. No card. Questions about the report? Contact us.

Sources

Written by Bhavesh Barot. Last checked and updated .

Keep reading

All guides