How to Check JSON-LD Schema Nesting (and Fix Common Errors)

By Kelly Barkhurst

June 25, 2025

8 Min read

In SEO

H

Is your schema properly nested? If you’re seeing multiple “cards” in the Schema Markup Validator, it’s time to take a closer look.

Example of an unnested Schema Validator response — This image shows six top-level entities as a result of the Schema Validator review. Proper nesting can provide one top-level entity.

In this quick guide, I’ll show you how to validate your structured data using Schema.org’s Validator, what proper nesting looks like, and how to avoid one of the most common mistakes I see in JSON-LD markup: multiple top-level entities that aren’t properly linked.

Who Is This For?

If you’re a designer learning development, a dev with a UX eye, or a technical SEO specialist, this tutorial is for you.

Structured data isn’t just about checking a box for Google. It’s about giving context to your content, and nailing your nesting helps you do it clearly and correctly.

Why Nesting Schema Correctly Matters

When you don’t nest schema properly, tools like the Schema Markup Validator will display your data as multiple unconnected cards—a red flag for search engines and AI.

That might mean:

Your WebPage isn’t linked to your Person, Organization, or VideoObject
Your isPartOf and mainEntityOfPage relationships are missing or broken
Your page loses context, hurting both indexing and rich result eligibility

✅ Proper nesting = better clarity, improved validation, and stronger SEO

What Does Proper Schema Nesting Look Like?

Correctly nested schema typically has:

One top-level @type: Often WebPage, ProfilePage, or ContactPage
Other schema entities (like Person, Organization, VideoObject, or Form) linked to that page using properties like mainEntity, subjectOf, or hasPart
All entities referencing each other by ID (using @id and sometimes fragment IDs like #person, #video, etc.)

How to Check Your Schema

Go to https://validator.schema.org
Paste your structured data or your page URL
Look at how many “cards” appear in the results

If you see just one card, you likely have a well-structured, nested schema.

Example of nested objects using ids to have one ContactPage object result in the schema validator

If you see multiple unconnected cards, that’s not necessarily an error, but it may indicate that you’re missing connections between your schema types.

This shows a page that is validated - a ContactPage and an unnested Creative Work — This Schema Validator result has an unnested Creative Work, separate from the ContactPage (the main entity). Using proper IDs, the Creative Work can be nested within the Contact Page.

⚠️ Note: Multiple top-level entities aren’t inherently wrong. But if they aren’t connected via properties like mainEntity, isPartOf, or hasPart, your schema may lack context—making it harder for search engines to interpret the relationships between elements.

While it won’t show up as a validation error, unconnected schema often leads to missed opportunities for rich results and indexing clarity. That’s why it’s considered best practice to nest or connect your structured data around one central entity—usually the WebPage or a specialized page type like ContactPage or ProfilePage.

Example: Manually Fixing a Broken Nesting Setup

I recently noticed that my CreativeWork object wasn’t nested properly inside my ContactPage. It was showing up as a separate top-level object in the Schema Validator.

Fix: I checked the ID for my ContactPage. The line read "@id": "https://example.com/contact/appointment#webpage"

Then I checked the CreativeWork’s "isPartOf" and found that the @id was not the same. Ah ha! A typo. If the @id’s do not match, then the objects will not be properly nested.

I ensured that the line now read: "https://example.com/contact/appointment#webpage"

Upon revalidation, the CreativeWork object now appeared nested under the ContactPage in the validator!

If you’re manually building schema across multiple pages and want to speed up your process, I also share my workflow for building structured data with ChatGPT, plus how I validate and edit AI-generated markup for real-world projects.

A Quick Word on Hashes (`#`) in Schema IDs

Using fragment IDs like #person, #form, or #video allows you to reference individual schema blocks that are all part of the same web page (@id: https://example.com/page-name#webpage).

We’re used to seeing hashtags on social media or in URLs to jump to a section, but in schema, # in the @id has nothing to do with either. It’s all about linking parts of your structured data.

Tip: I use consistent ID naming based on the schema object like #webpage, #person and #organization to make my schema clear and easy to debug.

Summary: Best Practices for Schema Nesting

Choose one main page schema type (WebPage, ProfilePage, ContactPage)
Link other entities via mainEntity, hasPart, subjectOf, or about
Use consistent and logical @id values with fragments (e.g. #form, #person)
Use the Schema Markup Validator to test nesting
Fix nesting issues to avoid multiple cards and strengthen semantic clarity

Watch the Full Video Tutorial

If you prefer a visual walkthrough, I cover finding the incorrect @ID in the "isPartOf" schema and show how I fix it in my latest video:

Hi. If you’re new to this channel, my name is Kelly Barkhurst from Designer to Full Stack. And if you are a graphic designer or developer, or someone who is interested in technology and the intersection, maybe you’re in marketing, or sales, then this channel might be good for you. So I started as a graphic designer and am now a full stack designer. So a designer who can code and is, skilled and many of the skills that are over here on the full stack developer side as well. So today we’re working on search engine optimization, which overlaps both full stack developer skills and full stack designer skills, as that overlaps on web design and UI design or front end development. So if that looks interesting to you Then please subscribe and stay tuned, because we’re going to be looking at nesting schema and using IDs. On your JSON-LD schema. All right. So let’s get into it. All right. So as we’re looking at schema, I wanted to point out an example of when you’re using the validator. The validator on schema.org how you know if everything is nested correctly. So the goal is that everything is within one of these cards. And it will typically be web page. Or if you have a specific type of web page, like a contact page or a profile page, it’ll all be wrapped there. So when you see multiple and if your goal is to nest them all with IDs, then you know that something isn’t nested correctly. So I’m going to go to the creative work. And when I click on it, it highlights on the left side. And what I can see is that it is linked to web page. Right is part of let me show you here. So it’s showing here being linked to contact page. So these are two different IDs for the same page. So when I say is part of and I turn it into web page and now I refresh across, I now have one card that’s shown here right. One object full of nested objects. And you can see that the is part of is now nested up into this web page, right? Rather than being its own, because it was looking for a contact page. So remember these hashtags, right? We use them a lot of different ways in web design. When they’re links. Right. It’s an anchor based on an ID on some kind of element on your page, and it takes you to that area of your web page when it’s in social media. Right? It is keywords and tags and are typically linked to all the results that are using that same hash tag when we’re using it in the schema l.D. For, this specific schema.org and search, we’re using it in this ID area. It is not a URL, even though often and you can present it as a URL. It is really a linking identifier, that allows everything to nest. So what I do is I try to use the exact same term of what I’m using in this page. I decided not to be specific to contact page or profile page, but just to use the general web page for all of them. And I assume that that’s okay here. I’m seeing that I didn’t I did this the way that I would want either. So it is same form, but I would probably want to well, it’s probably okay because it is a form, but I might want to do web page element, but I could have more than one web page element. So form is probably good here. All right. So I hope that helps that as you are troubleshooting your schema, that this linking ID is the key to having one big nested object. When you are reviewing your content versus having multiple objects. All right, so if you enjoyed this video, please like it. Subscribe. Hit the bell. And next up, this is the video I think you will love based on the nesting JSON-LD video you just watched.

📺 Watch: How to Check and Fix Schema Nesting

👋 About Me

Hi! I’m Kelly Barkhurst, a full-stack designer who helps other designers become fluent in development, schema, and technical SEO—one skill at a time. Whether you’re just learning structured data or trying to debug messy markup, I create tutorials and content to help bridge that knowledge gap.

Need Help with Schema or SEO?

Through Barkhurst Creative, I offer design, development, and SEO consulting, including custom structured data implementation for small businesses and creative professionals.

💬 Contact me here if you’d like to work together!

About the author

Kelly Barkhurst

Designer to Fullstack is my place to geek out and share tech solutions from my day-to-day as a graphic designer, programmer, and business owner (portfolio). I also write on Arts and Bricks, a parenting blog and decal shop that embraces my family’s love of Art and LEGO bricks!

By Kelly Barkhurst June 25, 2025