Setting up schema.org markup correctly: where it goes, how it is generated, and how to keep it true

Decide what the markup says before deciding where it goes

Markup is a second copy of facts the page already states, so it starts with the facts: the business's name as it appears on the sign, one address, one main phone number, the hours by day, the area served, and the services by their plain names. Write them in one place, a settings page in your site's admin or a short document your web person keeps, and let every page and every block of markup take them from there. A fact written twice drifts; a fact written once changes everywhere at the same time.

Which schema.org types to use for the business and its pages is in structured data for AI, and how the nodes point at one another with @id is in building an entity. This article is about the setup around them.

Where the JSON-LD goes

One script element of type application/ld+json, in the head or the body of the page. Google's introduction to structured data recommends JSON-LD, the format defined in the W3C's JSON-LD specification, and it can sit apart from the visible HTML while still describing it. One block holding a graph of nodes, each with its own @id, is easier to keep consistent than several blocks written by different tools.

Written into the page, or injected by a script

Put the block in the HTML your server sends, not in a script that adds it after the page loads. Google renders JavaScript, but its JavaScript documentation describes rendering as a separate step that can come later than the crawl, and a crawler that runs no scripts at all receives only the HTML. Markup injected by a tag manager or a widget is markup some of your readers never see.

Check it the way a crawler would. View the page source, not the browser's element inspector, which shows the page after scripts have run, and search it for application/ld+json. If the block is there, it is in the HTML. If it appears only in the inspector, a script put it there.

Builders and plugins: the second business nobody meant to add

Page builders and SEO plugins often add markup on their own: a WebSite node, an Organization node filled from the site title, sometimes a LocalBusiness node with whatever phone number was typed into the plugin's settings a year ago. Add your own block on top and the page can describe two businesses with two phone numbers. Our audit of 9,483 small business websites found the pattern at scale: 17.8% of the sites had no schema.org markup at all, most of the markup the rest carried described the website rather than the business, and a further 13.7% had business markup missing the fields that would make it usable.

1. View the source of the homepage and count the application/ld+json blocks, noting which tool wrote each.
2. List every node of a business type across them, with the name, address and phone each one states.
3. Keep one writer for the business node, the plugin or your own block, and switch the other off in its settings rather than deleting its output by hand.
4. Fill in the one you keep from the facts source, and check that the page's visible footer states the same values.
5. Repeat on a service page and the contact page, because some tools behave differently by template.

Testing: valid is not the same as true

Two kinds of tool answer two different questions. Google's Rich Results Test reports what Google reads for the search features it supports and flags errors against those features' rules. The Schema Markup Validator run by the schema.org project checks a block against the whole vocabulary, including types Google shows nothing for. Use both, and read their reports as statements about syntax and vocabulary.

Neither tool can tell you whether the phone number in the markup is the number that rings. That check is yours: set the block beside the visible page and compare every value. Google's structured data guidelines require markup to describe the visible page and not to mislead, which no validator can confirm for you. After a change goes live, Search Console's reports show over the following weeks whether Google read the markup the way you meant.

Keeping it true when the business changes

Markup goes stale the way a footer does, one change at a time. Hours move with the seasons, a service is dropped, a second location opens, the phone system changes. Make the change in the facts source on the day it happens, let the templates carry it to the page and the markup together, and read one page's source afterward to confirm both changed.

• Remove the Service node for a service you no longer offer, on the day the page comes down.
• Change dateModified on an article only when its words change, not when the template does.
• Add holiday hours as specialOpeningHoursSpecification before the holiday, and take them out after it.
• Look at the business node once a quarter against the sign, the phone and the map listing.

What not to mark up

• Anything the page does not show. Markup that states a fact a visitor cannot see is exactly what Google's guidelines rule out.
• Reviews or ratings copied from a platform. Google's review snippet rules say not to aggregate them from other websites, and a business's reviews of itself on its own site earn no stars.
• FAQ markup added only for the rich result, which Google no longer shows for any site. Implementing FAQ schema covers what the markup still does.
• A type that does not exist. Check the type on schema.org before using it; where no type fits exactly, use the nearest parent that does.