Schema, Explained · a three part series for people who know a little code
- Part 1: Organization, WebSite, WebPage, and BreadcrumbList (you are here)
- Part 2: LocalBusiness, Service, Article, and local search
- Part 3: FAQ, Person, Event, Recipe, and reviews
Schema markup is a block of code, usually JSON-LD inside a <script type="application/ld+json"> tag, that tells search engines and AI systems in plain facts what a page is and who is behind it. To check it, view the page source, search for ld+json, and read it like a form: a @type says what kind of thing it is, the properties fill in the facts, and an @id gives each thing a permanent name so other blocks can point to it. Every site should get four foundations right: Organization (who you are), WebSite (the site as a whole), WebPage (this page), and BreadcrumbList (where this page sits). The most common problems are not syntax errors. They are the same company described three different ways, facts that do not match the visible page, and blocks that never point at each other.
What is schema markup, in plain English?
Your website already tells people who you are, what you do, and where you are. It does it with design: a logo in the corner, a phone number in the footer, a headline, a photo. A person puts it together without thinking.
A machine has to guess. Schema markup removes the guessing. It is a small block of code, hidden from visitors, that states the facts in a fixed vocabulary everyone agreed on at Schema.org: this is an Organization, its name is this, its logo is here, its phone number is this. Google, Bing, and AI systems read it to understand the page with less guesswork, and Google uses some types to show richer search results.
Three things to keep in mind before you look at any code:
- Schema describes the page. It does not replace it. Everything in the schema should be true and visible on the page, or on the site.
- Schema does not make a weak page rank. It makes a good page easier to understand and eligible for certain search features.
- Most schema problems are content problems, not code problems. That is good news for a creative director, because content is what you already review.
How do you find the schema on a page?
You do not need any tools. Open the page, view the source, and search.
- Right-click the page and choose View Page Source (or press Ctrl+U on Windows, Option+Command+U on a Mac).
- Search the source for
ld+json. - Each match is the start of one schema block. Most pages have between one and five.
It looks like this:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Double Atari"
}
</script>
Two other places to look, once you are comfortable: Google's Rich Results Test shows which types Google can use for search features and flags errors, and the Schema Markup Validator shows everything on the page, organized. On my side project By Robots For Robots you can press Shift + M to see a page's schema parsed in place, which I wrote about in the machine view series.
One warning: schema added by JavaScript (some plugins and tag managers do this) will not show up in View Page Source. If you find nothing, try the Rich Results Test before you assume it is missing.
How do you read a block of JSON-LD?
Read JSON-LD like a form someone filled out. There are only five things to recognize.
| What you see | What it means | Example |
|---|---|---|
"@context" | Which dictionary the words come from. Almost always Schema.org. Set it once and ignore it. | "https://schema.org" |
"@type" | What kind of thing this is. The most important line in the block. | "Organization" |
"property": "value" | A fact about the thing. The property name comes from Schema.org; the value comes from you. | "name": "Double Atari" |
{ ... } inside a value | A thing inside a thing, with its own @type. | An address inside a business |
[ ... ] | A list. Use it when a property has more than one value. | Several social profiles |
And the punctuation rules that break schema most often, which are worth knowing even if you never write it yourself:
- Every property name and every text value goes in straight double quotes. Curly quotes pasted from a word processor break the whole block.
- Items are separated by commas, and there is no comma after the last item in a list or object.
- No comments. JSON does not allow them. In this series I add notes to the code to explain it, marked like this: // note. Real schema cannot contain them.
If one comma is wrong, the entire block is ignored, not just the line. That is why a validator is worth running after any edit.
What is @id, and why does it matter so much?
If you understand one idea in this series, make it this one. An @id is a permanent name tag for a thing, written as a URL with a # on the end. It does not need to be a real page. It just needs to be unique and never change.
{
"@type": "Organization",
"@id": "https://www.double-atari.com/#organization", // the name tag
"name": "Double Atari"
}
Once something has a name tag, any other block on any page can point to it instead of describing it again:
{
"@type": "WebSite",
"name": "Double Atari",
"publisher": { "@id": "https://www.double-atari.com/#organization" } // "the one I already told you about"
}
This is how a site's schema stops being a pile of separate facts and becomes one connected picture: this website is published by this organization, which was founded by this person, who wrote this article. Search engines and AI systems care a great deal about exactly those relationships, because they are how trust is judged.
The test for a reviewer is simple. Pick the main things on the site: the company, the founder, the website. Each should have one @id, used everywhere, and one full description, usually on the homepage or About page. Everywhere else should point to it.
How do you check Organization schema?
Organization schema answers "who is behind this website?" It usually lives on the homepage, and sometimes on every page.
{
"@context": "https://schema.org",
"@type": "Organization", // or a more specific type, see part 2
"@id": "https://www.example.com/#organization", // one name tag, used site-wide
"name": "Example Studio", // exactly as written on the site and Google Business Profile
"url": "https://www.example.com/", // the homepage, not the current page
"logo": "https://www.example.com/assets/logo.png", // a real, current, crawlable image
"description": "Brand and web design studio in Minneapolis.", // one plain sentence
"email": "hello@example.com",
"telephone": "+1-612-555-0100", // same number as the footer
"sameAs": [ // your profiles elsewhere, nothing else
"https://www.linkedin.com/company/example-studio/",
"https://www.instagram.com/examplestudio/"
],
"founder": { "@id": "https://www.example.com/about#person" } // points to the Person
}The // notes are added for this article. Real JSON-LD does not allow comments, so never paste them into a live page.
| Check | What good looks like |
|---|---|
| name | Matches the brand name used on the site, in the logo alt text, and on Google Business Profile, character for character |
| url | The homepage URL, with the same www and trailing slash style the site actually uses |
| logo | Opens in a browser, is the current logo, and lives on your own domain if possible |
| sameAs | Only your official profiles on other sites: LinkedIn, Instagram, Wikipedia, Crunchbase. Not your own pages. |
| @id | Identical on every page that mentions the organization |
| One definition | The full description appears once. Other pages point to it by @id instead of repeating it with different details. |
The red flag I see most: the organization is described on four templates by four different people at four different times, with four slightly different names, logos, and descriptions. Each one is "valid." Together they say the company cannot agree with itself.
How do you check WebSite schema?
WebSite schema describes the site as a whole: its name and who publishes it. It belongs on the homepage, and it is short.
{
"@context": "https://schema.org",
"@type": "WebSite",
"@id": "https://www.example.com/#website",
"name": "Example Studio", // the name you want shown for the site in search
"url": "https://www.example.com/",
"inLanguage": "en-US",
"publisher": { "@id": "https://www.example.com/#organization" } // points to the Organization
}The // notes are added for this article. Real JSON-LD does not allow comments, so never paste them into a live page.
What to check:
- name is the name you want Google to show as the site name in results. Google documents this as one of the signals it uses for site names, so keep it short and consistent with your brand.
- publisher points to the Organization's @id, rather than describing a second organization.
- If you see a
potentialActionwith aSearchAction, it was there for the sitelinks search box. Google retired that search box in late 2024. It does no harm, but it is no longer a reason to keep or add it.
How do you check WebPage schema?
WebPage schema describes the specific page you are on. Many sites skip it, and that is not a disaster, but it is the piece that ties a page to the site and to its subject. Schema.org has more specific versions you should use when they fit: AboutPage, ContactPage, CollectionPage (a list of items, like a blog index or portfolio), and FAQPage, which part 3 covers.
{
"@context": "https://schema.org",
"@type": "AboutPage", // the most specific type that fits
"@id": "https://www.example.com/about#webpage",
"url": "https://www.example.com/about", // this page's own URL
"name": "About Example Studio", // close to the page title
"isPartOf": { "@id": "https://www.example.com/#website" }, // belongs to the site
"about": { "@id": "https://www.example.com/#organization" }, // what the page is about
"mainEntity": { "@id": "https://www.example.com/about#person" }, // the main subject
"breadcrumb": { "@id": "https://www.example.com/about#breadcrumb" }
}The // notes are added for this article. Real JSON-LD does not allow comments, so never paste them into a live page.
What to check: the url is this page's URL, not the homepage; the @type is the most specific one that fits; and isPartOf points to the WebSite. When a page uses about or mainEntity, ask the content question: is that really what this page is about? If the About page says its main subject is the founder, the page should actually be mostly about the founder.
How do you check BreadcrumbList schema?
A breadcrumb is the trail at the top of a page, like Home / Services / Website Audits. BreadcrumbList schema describes that trail, and Google can show it in search results instead of a raw URL. It is one of the easiest types to check, because it should match what you can see.
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{ "@type": "ListItem", "position": 1, "name": "Home",
"item": "https://www.double-atari.com/" },
{ "@type": "ListItem", "position": 2, "name": "Services",
"item": "https://www.double-atari.com/services" },
{ "@type": "ListItem", "position": 3, "name": "Website Audits", // the current page
"item": "https://www.double-atari.com/services/website-audits/" }
]
}This is the real breadcrumb schema on the Double Atari website audits page.
| Check | What good looks like |
|---|---|
| Matches the visible trail | Same steps, same order, same words as the breadcrumb a visitor sees |
| position | Starts at 1 and counts up with no gaps |
| name | Short labels, the same ones in the navigation, not full page titles |
| item | Full URLs that work and are the canonical version of each page (no tracking parameters, no redirects) |
| Reflects the real structure | A page that lives under Services should not claim to live under Blog |
A design note: if your design has no visible breadcrumb, the schema can still describe the page's place in the site. But the strongest version is a visible breadcrumb and matching schema, because it helps people and machines in the same way.
What did I find when I checked my own site?
I ran this exact review on double-atari.com while writing this post, and I found three problems. All three are now fixed. Here is how I found them and what changed, because the same steps work on any site.
Step 1: list every block on the page
You do not need a special tool to start. Open the page in Chrome, open the developer console (View, then Developer, then JavaScript Console), paste this, and press Enter. It prints the type and @id of every schema block on the page.
document.querySelectorAll('script[type="application/ld+json"]').forEach((s, i) => {
const d = JSON.parse(s.textContent); // a syntax error here means a broken block
console.log(i, d['@type'], d['@id'] || '(no @id)');
});
On my homepage it printed this:
0 Organization https://www.double-atari.com/#localbusiness // same @id...
1 Person (no @id) // a person with no name tag
2 WebSite https://www.double-atari.com/#website
3 Service https://www.double-atari.com/#service
4 LocalBusiness https://www.double-atari.com/#localbusiness // ...used twice
5 FAQPage (no @id)
Two lines share one @id, and one Person has none. That is the whole diagnosis, and it took a few seconds. An FAQPage without an @id is fine, because nothing else needs to point to it.
Problem 1: one @id, two descriptions
Block 0 described the business as an Organization with a logo file left over from the site's old Squarespace build. Block 4 described the same @id as a LocalBusiness with the current logo, phone, and address. Same name tag, different facts, so a machine has to pick one.
// Before: block 0
{
"@type": "Organization",
"@id": "https://www.double-atari.com/#localbusiness", // same @id as block 4
"logo": "https://images.squarespace-cdn.com/.../da-logos-2.png", // old platform
"areaServed": ["Minneapolis, Minnesota", "Minnesota", "United States"]
}The // notes are added for this article. Real JSON-LD does not allow comments, so never paste them into a live page.
The fix: I deleted block 0 and moved the one fact it had that block 4 did not (that I also serve clients across the United States) into the LocalBusiness block. One business, one description.
// After: the only description of the business
{
"@type": "LocalBusiness",
"@id": "https://www.double-atari.com/#localbusiness",
"logo": "https://www.double-atari.com/assets/double-atari-logo.webp", // current file
"areaServed": ["Minneapolis", "St. Paul", "Twin Cities", "Minnesota", "United States"]
}
Problem 2: a Person with no name tag
Block 1 described me with no @id, a different job title than my About page, and a nameless employer. To a machine that reads as a second, unconnected Andrew Charon.
// Before
{
"@type": "Person",
"name": "Andrew Charon",
"jobTitle": "Digital Strategist, Web Developer, SEO Consultant", // About page says something else
"worksFor": { "@type": "Organization", "name": "Double Atari" } // which one?
}The // notes are added for this article. Real JSON-LD does not allow comments, so never paste them into a live page.
To check what the About page says, I ran the same console snippet there and read the Person block. Then I made the homepage match it.
// After
{
"@type": "Person",
"@id": "https://www.double-atari.com/about#person", // same name tag as the About page
"name": "Andrew Charon",
"url": "https://www.double-atari.com/about",
"jobTitle": "Founder and SEO Consultant", // matches the About page
"worksFor": { "@id": "https://www.double-atari.com/#localbusiness" } // points to the business
}
Problem 3: sameAs pointing at itself
On the Minneapolis SEO page the list looked normal, so I searched the page source for "sameAs" and read what was inside.
// Before: /minneapolis-seo/
"url": "https://www.double-atari.com/minneapolis-seo/", // the business url is the homepage
"sameAs": [
"https://www.double-atari.com/#localbusiness", // my own @id, not a profile elsewhere
"https://www.linkedin.com/company/double-atari-digital-marketing-experts/"
]The // notes are added for this article. Real JSON-LD does not allow comments, so never paste them into a live page.
The fix: I removed my own @id from sameAs, which is only for profiles on other websites, and set the business url back to the homepage so it matches the homepage block.
// After
"url": "https://www.double-atari.com/",
"sameAs": [
"https://www.linkedin.com/company/double-atari-digital-marketing-experts/"
]
None of these broke anything a visitor could see, which is exactly why they lasted. After the fixes I ran the console snippet again: the homepage now lists #localbusiness once, and the Person carries the same @id as the About page. Then I ran both pages through the Schema Markup Validator to confirm they parse cleanly. The review below is designed to catch these problems on your site.
The five-minute foundations review
Open the homepage, the About page, one service page, and one blog post. View source, search for ld+json, and answer these questions.
| Question | If the answer is no |
|---|---|
| Does every block pass the Rich Results Test or Schema Markup Validator without errors? | A broken block is ignored completely. Fix syntax first. |
| Is there exactly one full Organization description, with one @id? | Merge the duplicates and point to one @id. |
| Do the name, logo, phone, and email match what is visible on the site? | Update the schema, or the site. They must agree. |
| Does sameAs list only your profiles on other websites? | Remove your own URLs and anything that is not you. |
| Does WebSite name the publisher by @id? | Add a publisher that points to the Organization. |
| Does each page's WebPage url match the page it is on? | Templates often copy the homepage URL everywhere. Fix the template. |
| Does BreadcrumbList match the visible breadcrumb, in order, with working URLs? | Update it from the same data the visible breadcrumb uses. |
If you can answer yes to all seven, your foundations are done, and you are ahead of most sites I audit. Part 2 builds on them with the types that do the most for a local business: LocalBusiness, Service, and Article.
Schema foundations FAQ
What is schema markup?
Schema markup is code, usually written in JSON-LD, that describes a page in a standard vocabulary from Schema.org. It tells search engines and AI systems facts such as what the page is, which organization publishes it, and how the page fits into the site.
How do I see the schema on a website?
View the page source and search for "ld+json". Each match is a schema block. You can also paste the URL into Google's Rich Results Test or the Schema Markup Validator, which also catch schema added by JavaScript.
What is @id in schema markup?
An @id is a permanent, unique identifier for a thing, written as a URL with a fragment such as https://www.example.com/#organization. Other schema blocks can point to that @id instead of describing the same thing again, which connects a site's schema into one consistent picture.
Which schema types should every website have?
Most sites should have Organization (or a more specific type such as LocalBusiness), WebSite on the homepage, WebPage or a specific page type on each page, and BreadcrumbList wherever pages sit inside a hierarchy.
Can JSON-LD contain comments?
No. JSON does not allow comments, so a comment inside a JSON-LD block makes it invalid and search engines ignore the whole block. Keep notes in your documentation, not in the code.
Explore related Double Atari resources: schema markup for AI search, the machine view: outline and structured data, technical SEO audit checklist, and website audits.