There are two common ways to organize several entities on one page. Nesting puts related entities inside their parent, such as the author object inside the Article. A flat structure lists every entity as a top-level node, usually in an @graph array, and connects them with @id references. Both are valid JSON-LD; the problems come from mixing them carelessly so entities end up disconnected.
Nested
Nesting is easy to read and is how most of Google's examples are written. Each relationship is explicit in the structure. It gets repetitive when the same entity, such as the organization, appears in several places, since you either duplicate it or reference it.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Choosing an event bus",
"author": { "@type": "Person", "name": "Noor Haddad" },
"publisher": { "@type": "Organization", "name": "Kestrelmoor" }
}Flat with @graph
A flat graph lists Organization, WebSite, WebPage, Article and Person as separate nodes, each with an @id, and links them by reference. Many SEO plugins use this approach. It avoids duplication and keeps one definition per entity, at the cost of being harder to read by eye.
{
"@context": "https://schema.org",
"@graph": [
{ "@type": "Organization", "@id": "https://kestrelmoor.example/#org", "name": "Kestrelmoor" },
{ "@type": "Article", "@id": "https://kestrelmoor.example/blog/event-bus#article",
"headline": "Choosing an event bus",
"publisher": { "@id": "https://kestrelmoor.example/#org" } }
]
}The real risk: orphaned items
Trouble starts when separate tools each add their own blocks. An Article with no author, a Person floating at the top level, and two Organization nodes with different names all describe the page less clearly than either approach done consistently. Validators show the tree, so check that each entity is connected to the thing it belongs to.
Example
Merging plugin and custom markup
Kestrelmoor's blog plugin outputs an @graph, and a developer adds a separate nested Article block for a custom template. The page now has two articles. The fix is to extend the plugin's graph with the extra properties through its filter hooks instead of adding a second block.
Common mistakes
Two definitions of the same entity
Duplicate nodes with conflicting values make it unclear which is correct.
Questions
Google has not stated a preference. Its documentation uses nested examples, and it parses @graph as well.
