Schema Builder Fixes: Choose, Structure and Complete Your Markup
Schema markup only earns its keep when it describes the page accurately: the right type for the content, the fields each search feature needs, and entities that link together properly.
The Schema Markup Builder generates JSON-LD for the type you choose, validates it against schema.org and Google's rich result criteria, flags missing fields, checks nesting and gives you code ready to paste. This page is about the design decisions behind good markup, which type, which fields and how the pieces connect, and links the guide for every finding the builder raises.
Choosing the type: start from what the page is about
Most type problems come from describing the website rather than the page. A recipe on a food blog is a Recipe, not a BlogPosting, even though it sits in the blog. A service page for a plumber is about the business and its service, not an Article. Ask one question: if someone saved this page, what thing would they say they had saved?
| The page is mainly... | Main type | Common mistake |
|---|---|---|
| One product you sell | Product with an Offer | Marking a category page of many products as a single Product |
| A recipe | Recipe | Leaving it as Article or BlogPosting,
which cannot earn recipe results |
| A news report | NewsArticle | Using it for evergreen guides, which suit
Article or BlogPosting |
| An event with a date and place | Event or a subtype such as MusicEvent | Marking a venue's general listings page as one Event |
| A job vacancy | JobPosting | Keeping markup live after the role has closed |
| Your business, for a local customer | LocalBusiness or a subtype such as Dentist | Using
plain Organization for a business with premises customers visit |
| Instructions for a task | HowTo is valid schema.org | Expecting a Google rich result: Google stopped showing HowTo results in 2023 |
Pick the most specific type that is still true. Dentist is more useful than LocalBusiness,
which is more useful than Organization. But never pick a type because it earns a rich result
if the page is not really that thing; that breaks Google's structured data guidelines and can lead to
a manual action.
Required and recommended: what Google asks for
schema.org itself requires almost nothing. The requirements come from each search feature. Google's documentation lists required properties, without which a page is not eligible, and recommended ones, which improve how a result can look. A summary for common types:
| Type and feature | Required by Google | Worth adding |
|---|---|---|
| Product (product snippet) | name, plus at least one of offers,
review or aggregateRating | image, brand, sku
or gtin, description |
| Product (merchant listing) | name, image, and an Offer
with price and currency | availability, shipping and return details |
| Recipe | name, image | recipeIngredient, recipeInstructions,
times, nutrition, ratings |
| Article | None | headline, image, author,
datePublished, dateModified |
| Event | name, startDate, location | endDate,
offers, eventStatus, image |
| JobPosting | title, description, datePosted, hiringOrganization,
jobLocation (or remote details) | baseSalary, employmentType,
validThrough |
| LocalBusiness | name, address | telephone,
openingHoursSpecification, geo, url |
Google revises these lists from time to time and has retired several less-used rich result types in recent years, so check the current documentation for any type you rely on. Two rules never change: only mark up information a visitor can see on the page, and never invent values such as ratings or prices to complete a form.
The fix guides
Each guide covers one builder finding with examples of the wrong and right markup and a way to check the result.
Choosing and completing
Fixing the wrong schema type walks through the schema.org hierarchy in plain English and how to settle on the most specific type that fits. Fixing missing required fields goes type by type through what each rich result needs and where on the page the value should come from.
Structure and connections
Fixing wrong nesting and graph structure
covers authors written as plain text instead of a Person, publishers without an Organization, and when
to nest an entity versus define it once in a @graph. Fixing
@id references that do not resolve covers identifiers that point at nothing and how to keep them
consistent across the site. Fixing multiple
competing schemas covers pages where a plugin, a theme and custom code each add their own version.
Values and business details
Fixing image and logo issues covers
logo size, relative image URLs and images that crawlers cannot fetch. Fixing
date and time formats covers ISO 8601 and time zones. Fixing
Organization and LocalBusiness fields covers sameAs links to official profiles, full
postal addresses, phone numbers, opening hours and coordinates.
Building on your platform
WordPress compares SEO plugins with dedicated schema plugins and shows how to override defaults. Shopify covers theme Product markup, review apps and adding markup through Liquid. Next.js covers generating JSON-LD from CMS data in server components and validating it in your build.
Plan the whole site, not just one page
Markup built page by page tends to describe the same business five different ways. Spending half an hour on a simple site-wide plan prevents most nesting, @id and duplication findings before they happen.
- Define your organisation once. Decide on one
@idfor it, for examplehttps://www.example.co.uk/#organization, and put its full description, logo, contact details andsameAslinks on the home page or about page. Everywhere else, refer to it by that identifier. - Give each person an identity. Authors get one Person entity each, with an
@idbased on their author page, reused on every article they write. - Describe each page as a WebPage. Link it to the site's WebSite entity and to the
main thing on the page through
mainEntityorabout. - Add the page's main entity. The Product, Recipe, Event or Article from the type table, linked back to the organisation as brand, publisher or organiser.
- Add breadcrumbs as a BreadcrumbList matching the visible breadcrumb trail.
For a local business, choose between Organization and LocalBusiness carefully. A business with premises or a service area that customers contact locally usually suits a LocalBusiness subtype; a national online brand usually suits Organization. Use one, not both for the same entity, and make sure the name, address and phone number match your Google Business Profile exactly.
Which findings to fix first
- Wrong main type. If the type is wrong, every field you add is going into the wrong container. Settle this before anything else.
- Missing required fields on revenue pages. Products, events, vacancies and local business details affect how your commercial pages appear in search.
- Competing or duplicate blocks. Remove duplicates before adding more markup, or you will be maintaining two versions of every fix.
- Broken references and nesting. Fix authors, publishers and organisation links so the graph holds together.
- Organisation and local details. A complete, consistent Organization or LocalBusiness entity supports every other page on the site.
- Recommended fields, images and dates. These refine results that are already eligible.
If time is short, fix one template completely rather than every template partly. A product template with the right type, complete required fields and clean references is worth more than half-finished markup spread across the whole site, and it gives you a tested pattern to copy to the next template.
A sensible order of work
- List your page templates and decide the main type for each using the table above.
- Write down your organisation's and authors'
@idvalues so every template uses the same ones. - Check what your theme, SEO plugin and apps already output, and decide which single source will own each type.
- Open the Schema Markup Builder, choose the type, and fill in values taken from the visible page.
- Resolve every missing required field the builder reports, then the recommended ones that apply.
- Add the generated JSON-LD through your chosen source, not by hand on individual pages if a template can do it.
- Test a live page with Google's Rich Results Test and the Schema Markup Validator.
- Watch the enhancement reports in Google Search Console as pages are recrawled.
The Schema Builder Guide covers the builder in depth and the example output shows finished markup. If you would rather start from generated markup, see the AI Schema Guide; for which results your markup can earn, see the Rich Snippets Guide.
1. Which schema type should my home page use?
Most home pages describe the business itself, so the home page is a good place for your full Organization or LocalBusiness entity and a WebSite entity, with the page described as a WebPage. Avoid marking the home page as a Product or Article unless it genuinely is one. Other pages can then refer to the organisation by its @id rather than repeating all its details, which keeps the information consistent across the whole site and means a change of phone number only needs making once.
2. Does Product markup need reviews or ratings?
No. For Google's product snippets, a Product needs a name and at least one of offers, review or aggregateRating, so a product with a price and no reviews is fine. Only add ratings that come from genuine reviews shown on the page. Merchant listing results have their own requirements, including an image and an offer with a price and currency, so check both sets of rules if you sell online and fill in whichever values your product pages genuinely show.
3. Should I still add HowTo or FAQ markup?
HowTo and FAQPage are still valid schema.org types, so the markup does no harm and some systems other than Google may read it. Google, however, stopped showing HowTo rich results in 2023 and limits FAQ rich results to well-known, authoritative government and health websites. For most businesses, neither will produce a visible rich result in Google, so spend time on types that can, such as Product, LocalBusiness or Event, first, and keep any FAQ content on the page for visitors.
4. What is the difference between nesting and @graph?
Nesting puts one entity inside another, such as an author written out in full inside an Article. A @graph lists entities side by side and connects them with @id references. Nesting is simple for one-off details. A @graph suits entities that appear on many pages, like your organisation or regular authors, because each is defined once and referred to everywhere. Both are valid, and many sites use a mix of the two, nesting small details and using references for shared entities.
5. Should I use Organization or LocalBusiness?
Use a LocalBusiness subtype when customers visit your premises or you serve a defined local area, for example a dentist, a café or a plumber. Use Organization for businesses without a local customer base, such as a national online retailer or a publisher. LocalBusiness is itself a kind of Organization, so it inherits every Organization property. Pick one for the business rather than describing it twice with two different types, which only leaves search engines to guess which one is correct.
6. How big does my logo need to be in schema?
Google's guidance asks for a logo at least 112 by 112 pixels, in a format Google Images can index, at a URL that crawlers are allowed to fetch. A square image works best because it can be shown in different layouts without awkward cropping. Use an absolute URL, keep the file somewhere stable so the address does not change with every redesign, and make sure robots.txt does not block the folder it sits in.
7. Can I copy schema from a competitor or a template?
You can copy the structure, but never the values. Every name, price, address, rating and date must describe your own page and match what visitors can see there. Templates are a good starting point for learning which properties belong where, but they often contain placeholder values, invented ratings or a type that suits a different kind of business. Check each field against your page before publishing, and validate the result with the builder and with Google's Rich Results Test.
The Schema Markup Builder generates JSON-LD for the type you select, validates it against schema.org and Google rich result criteria, identifies missing fields, checks nesting and gives you ready-to-paste code.
Run the Schema Markup Builder →