Schema.org Audit:
when the validator is not enough

Why "how to write correct JSON-LD" is the wrong question

People searching for "how to write JSON-LD" usually end up on a property reference, a copy-pasted example, and a validator that returns a positive result. The problem is that the green light certifies grammar, not meaning. And meaning is exactly what Google and AI engines read.

The key difference is therefore what Syntax (the JSON is valid), Semantics (the router connects the pages) and Ontology (the Knowledge Graph understands what we sell) each tell us.

The relationships declared in Schema.org are assertions about how the site is built. When they are wrong — when a hasPart declares a containment that does not exist, when a breadcrumb lives inside an Article instead of the WebPage, when an @id points to a node that was never defined — no automatic syntax-validation tool flags it. Yet the graph that machines build contains those errors.

Where this method comes from

The semantic-audit methodology did not come from a theoretical hypothesis. It formed by accumulation: one error at a time, a template that generated the same problem across hundreds of pages, a fix that revealed the next pattern. There was no initial phase in which someone "designed" this architecture: there was a path of discovery, and this document is the formalisation of what worked.

From that experience came a precise conviction: validators check grammar, not meaning. A hasPart pointing to an external page passes validation; a breadcrumb inside an Article passes validation; an @id pointing to a non-existent node passes validation. The green light says "syntax OK", not "coherent ontology".

When the number of pages exceeds the capacity to check them one by one, errors do not disappear — they change shape, becoming systemic patterns instead of isolated typos. Architecture, not the single page, is what must be designed with care.

What a Schema.org audit analyses

The audit does not stop at checking whether the code is valid. It analyses the graph as a whole and verifies that it holds up logically. Here are the areas it checks.

The operating rules: how to write JSON-LD that holds the graph together

Nineteen patterns that recur in production, with examples of correct and incorrect code. Every rule exists because a real case generated it: a template that got it wrong on 250 pages, an audit that revealed a Dangling Node, a validator that gave a green light to an ontologically broken relationship.

1. Containment vs linking: hasPart vs significantLink

hasPart indicates literal composition: X physically contains Y. significantLink indicates editorial relevance: Y is one of the most important links on the page, but it is not contained in X.

• Use hasPart: CollectionPage → its child pages, Book → Chapter, Course → Lesson, Article → FAQPage.
• Use significantLink: WebPage → related external pages, Article → cited sources, Hub → thematic siblings.

Operating test: translate the relationship into a sentence ("X physically contains Y"). If it sounds forced, the correct property is significantLink.

2. The syntactic trap of significantLink

significantLink accepts strings only. Not Reference Nodes, not objects. If you pass {"@id": "..."} the Schema.org validator returns a blocking error.

// ❌ Validator error
"significantLink": [{ "@id": "https://site.com/page/#article" }]

// ✅ Correct
"significantLink": ["https://site.com/page/#article"]

Critical: always include the final fragment (#article, #app, #webpage) in the string. The syntax stays valid and the AI knows exactly which node you are pointing to, avoiding Dangling Nodes.

3. The breadcrumb: where it really belongs

The breadcrumb belongs to the WebPage, not to the Article. The reason is ontological: the breadcrumb describes a URL path, and URLs belong to pages, not to content. Many sites put it inside the Article and Google still shows the path in the SERP — hence the false perception that it is fine. At scale it becomes a systemic pattern.

// ✅ Correct pattern
{
  "@type": "WebPage",
  "@id": "/page/#webpage",
  "breadcrumb": { "@id": "/page/#breadcrumb" },
  "mainEntity": { "@id": "/page/#article" }
}

Architectural rule: assign the breadcrumb at the page-template level, not the entity level. In WordPress → single.php; in React → page layout, not content component.

4. Reference Node vs Stub Node

When you reference a node defined elsewhere, use only @id. Adding @type without the essential properties (name, publisher, etc.) creates a partial entity, which at scale generates ambiguity about which is the authoritative version of the entity.

// ❌ STUB — creates a partial entity
"hasPart": [
  { "@type": "WebPage", "@id": "/p1/#webpage", "url": "/p1/" }
]

// ✅ REFERENCE NODE — flattened graph
"hasPart": [
  { "@id": "https://site.com/p1/#webpage" }
]

5. ItemList: when to generate it and when not to

ItemList is a type, not a property. It should only be generated when the page is structurally a list: hubs, category indexes, rankings.

• Yes: hub pages, categories, rankings.
• No: single articles, products, tools. And never for FAQ sections — those use FAQPage with a question/answer structure.

Every ListItem must have a readable name. A bare URL is a weak signal.

6. Mixed data formats: handle both

A property can be populated in two valid forms. The generator must recognise both.

// Format A
["/page-a/", "/page-b/"]

// Format B
[{ "id": "/page-a/", "type": "..." }]

If the code expects only one format, it works until someone — maybe months later, maybe a different collaborator — writes the list in the other. The markup silently stops being valid.

7. ID conflicts: the sameAs bridge

If you inject a global site-wide Organization and a richer Organization on the "About Us" page with a different @id, Google may treat them as two distinct entities. Do not modify the global template: link the two entities with sameAs.

{
  "@type": "Organization",
  "@id": "https://site.com/#org-detail",
  "sameAs": "https://site.com/#org"
}

8. The Ontological Chimera

An ID declared as WebApplication in one part of the graph and as WebPage in another is a logical contradiction. The validator stays silent, the AI stalls in front of two incompatible types on the same node. The most frequent cause: a navigation loop that forces @type: "WebPage" onto every element, even when the ID belongs elsewhere to software.

Rule: navigation loops (menu, related, hub) must point only to containers (#webpage), never to final content (#article, #app).

9. Target typing and rich snippets

@type: "WebApplication" is semantically correct but Google requires the SoftwareApplication class plus operatingSystem for the rich result. A single type is not enough. Use multiple inheritance.

"@type": ["SoftwareApplication", "WebApplication"],
"operatingSystem": "Web Browser"

Same pattern when a range constraint blocks a semantically valid link:

// teaches expects Text or DefinedTerm
"@type": ["WebApplication", "DefinedTerm"],
"@id": "/software/#app",
"name": "Advanced SEO Protocol"

10. Container ≠ content

A page that hosts a tool is not the tool. Separate the entities with mainEntity.

// ❌
"@type": ["WebPage", "WebApplication"]

// ✅
{
  "@type": "WebPage",
  "@id": "/tool/#webpage",
  "mainEntity": {
    "@type": "WebApplication",
    "@id": "/tool/#app",
    "name": "SEO Calculator"
  }
}

Anti-pattern: applying WebPage or Article indiscriminately in a shared header. Fix it with semantic routing — the type depends on the data, not just the layout.

11. about vs mentions

• about → main topic (1–2 entities max).
• mentions → secondary references.

Too many about values dilute the signal: the page competes for the wrong queries.

12. Data parity

Every value in the JSON-LD must be visible in the rendered DOM. If you declare aggregateRating: 4.8 and the DOM has no badge showing "4.8", you are violating Google's guidelines. Risk: manual action for misleading markup.

• If you declare price: 0, the page must say "Free" or "0€".
• If you declare ratingValue: 4.8, there must be a visible badge showing "4.8".
• Purely graphical icons must be marked aria-hidden="true".

13. Fragment naming convention

Adopt a rigid convention and check it periodically. Example:

• #webpage → page container
• #article → article entity
• #app → application entity
• #breadcrumb → breadcrumb entity
• #organization → organization

Validators do not open URLs: they do not verify that the @id actually exists on the other side. A Fragment Audit — extracting all @id values used in navigation loops and verifying that they point to containers — is the only way to catch them.

14. hasPart + ItemList: the index trap

Do not put an ItemList inside hasPart. ItemList is classified as Intangible (an abstract data structure), not as CreativeWork. A book has chapters, not "a list of data".

// ❌
"hasPart": { "@type": "ItemList", "itemListElement": [...] }

// ✅
"hasPart": [
  { "@id": "https://site.com/chapter-1/#webpage" },
  { "@id": "https://site.com/chapter-2/#webpage" }
]

15. The bidirectional CollectionPage pattern

On a true Topic Cluster — a Pillar Page that organises a series of deep dives — bidirectionality is valuable:

• The CollectionPage (parent) declares hasPart towards the children.
• Every child page declares isPartOf towards the parent.
• Both with pure Reference Nodes (absolute @id, no @type).

16. Global identifiers: citing third parties

If you cite third-party software (isBasedOn: SoftwareApplication), Google activates the commercial rich-snippet filters and floods you with warnings for missing offers and operatingSystem. The lazy solution is to downgrade to Thing — which lobotomises the graph. The correct solution is to point to a global IRI.

"isBasedOn": {
  "@type": "SoftwareApplication",
  "@id": "https://www.wikidata.org/wiki/Q161676",
  "name": "WordPress"
}

The bot recognises an external citation, not a local distribution: the commercial filters are disarmed, and the @type is preserved.

17. Cross-property @id conflict

When the same @id appears in multiple properties with different ranges within the same graph, and is not defined locally with an explicit @type, the validator resolves it only once — at the first occurrence — and propagates the resulting type to all the others. If the resolved type is weak (Thing), the downgrade can invalidate properties that require stricter ranges such as CreativeWork.

// ❌ Conflict: same @id in hasPart (requires CreativeWork)
// and in isRelatedTo (free range), with no local @type

{
  "@graph": [
    {
      "@type": "CollectionPage",
      "hasPart": [
        { "@id": "https://site.com/page/#article" }
      ]
    },
    {
      "@type": "Service",
      "isRelatedTo": [
        { "@id": "https://site.com/page/#article" }
      ]
    }
  ]
}

// ✅ Solution: differentiate the fragments
// hasPart points to the content (#article)
// isRelatedTo points to the container (#webpage)

{
  "@graph": [
    {
      "@type": "CollectionPage",
      "hasPart": [
        { "@id": "https://site.com/page/#article" }
      ]
    },
    {
      "@type": "Service",
      "isRelatedTo": [
        { "@id": "https://site.com/page/#webpage" }
      ]
    }
  ]
}

The diagnostic signal is not the error message, which appears downstream at a seemingly unrelated point. It is the presence of the same @id in multiple properties. When you find that pattern, look there for the cause before looking elsewhere.

18. Fragment auto-inference: the fragile dependency

Pure Reference Nodes ({"@id": "..."}) work only if the validator can resolve the @id. There are three levels of resolution, in priority order:

1. Local definition: the @id exists in the @graph of the current page as an object with an explicit @type. Resolution guaranteed.
2. Fragment auto-inference: if the fragment is in a whitelist of known conventions (#webpage → WebPage, #article → Article, #faq → FAQPage, #breadcrumb → BreadcrumbList), the validator infers the type.
3. Downgrade to Thing: if the fragment is custom and there is no local definition, the type is Thing. This can invalidate properties with stricter ranges.

Practical consequence: pure Reference Nodes work "by luck" when they use standard fragments. One custom fragment anywhere in the graph and the mechanism breaks silently. An effective audit verifies that every referenced @id is either whitelisted or explicitly defined in the local graph.

19. Index as a view, not a container

A page that lists other pages does not contain them. They are two ontologically different relationships:

• Containment (hasPart): the container is physically made of its parts. A book contains chapters.
• Listing (significantLink): the page refers to external resources without containing them. An index lists the chapters of a book.

The temptation to use hasPart on an index is strong ("the index contains the chapters"). It is ontologically wrong: the chapters are part of the book, not of the index that lists them.

// ❌ Index with hasPart towards the chapters
{
  "@type": "CollectionPage",
  "@id": "/index/#webpage",
  "hasPart": [
    { "@id": "/chapter-1/#webpage" },
    { "@id": "/chapter-2/#webpage" }
  ]
}

// ✅ Index with significantLink (strings) towards the chapters
{
  "@type": "CollectionPage",
  "@id": "/index/#webpage",
  "significantLink": [
    "https://site.com/chapter-1/#webpage",
    "https://site.com/chapter-2/#webpage"
  ]
}

Containment stays on the real container (the book, the work, the collection). The index is a view that exposes the list, not a physical container.

Consequence for narrative patterns: in branching content (interactive path, step-by-step tutorial, decision tree), each node belongs to the previous node with isPartOf, and the subsequent nodes are declared with significantLink. The index remains the overview view with significantLink towards all nodes. No hasPart.

Diagnostics: when two identical structures give different outcomes

There is a moment in every audit when two apparently identical pages get opposite results from the validator. One passes, the other does not. The code looks the same. The instinctive reaction is to think of a validator bug, a cache, a temporary problem.

It is none of those. The reason is that validators resolve references contextually, not in isolation: it depends on what is in the rest of the graph, not just on what you write at the specific point.

Symptom → rule map

For those arriving with an already-identified problem, this table serves as a quick index.

When in doubt

Translate the JSON-LD triple into a simple sentence (Subject → Verb → Object). If the sentence sounds forced, the property is wrong — regardless of what the validator says.

"This Article physically contains a Breadcrumb" → forced → the breadcrumb belongs to the WebPage.

"This WebPage contains this other external WebPage" → forced → use significantLink.

"This WebPage is a WebApplication" → wrong → use mainEntity.

"This index physically contains its chapters" → forced → the index lists, the book contains.

Final rule: every rule above exists because a validator said "OK" while the Knowledge Graph said "no". Trust the graph, not the green tick.

The operating checklist

Concrete questions that a Semantic Audit asks of every page. It is not a test to tick off once: it is a grid to reapply when a content type is added or a rule is automated.

On the single document

• Is the page's @id unique and consistent?
• Does the breadcrumb live in the WebPage or in the Article?
• Are containment properties (hasPart) used only when containment is real?
• Do thematic outbound links use significantLink (string) or hasPart (object)?
• Does every referenced @id exist somewhere in the graph?
• Is the declared type coherent with the reality of the page?
• Does the same @id appear in multiple properties with different ranges? If yes, you have a potential resolution conflict.
• Are relational arrays all typed or all untyped? If mixed, you have a potential internal-coherence problem.

On the entire site

• Does every page use the same fragment convention?
• Do navigation loops point only to containers (#webpage)?
• Are there @id values declared as two different types on different pages?
• Have Dangling Nodes towards external URLs been eliminated?
• Do master entities live at the root of the @graph, with references using only @id?
• Are exceptions (a page hosting a tool, a course teaching a concept) handled with mainEntity or polymorphism?
• Does every custom fragment (not in the conventions whitelist) have an explicit definition in the local graph?
• Does every index use significantLink (not hasPart) to list its entries?

What an audit cannot do

To be useful, a method must also declare its limits.

• It does not judge editorial strategy. It verifies that the relationships are coherent with what the site declares itself to be. It does not decide whether the site should have a different structure.
• It does not guarantee the rich snippet. Google has specific requirements for rich results that go beyond the Schema.org vocabulary. An audit can tell you whether the markup is ontologically correct, not whether Google will decide to show the star rating.
• It does not replace human testing. The linguistic test — translating the JSON-LD into a sentence and checking whether it sounds forced — remains a human judgement that no tool can fully automate.
• It does not see the future of Schema.org. The vocabulary evolves. An audit is a snapshot of the current state of the specifications and Google guidelines. It must be repeated when something changes.
• It does not predict how validators will evolve. Fragment auto-inference, for example, is not official documentation: it is an observed behaviour of the most widespread validators. It can change without notice. An audit based on it remains reliable, but must be rechecked periodically.

Who it is for (and who it is not)

It is genuinely useful for editorial platforms with dozens or hundreds of related pages, e-commerce sites with a structured catalogue, topic-cluster architectures, sites with automated templates that generate markup at scale, and projects that must be read by AI.

It is overkill for brochure sites with 5–10 static pages, projects managed by standard plugins (Yoast, RankMath) that already cover Organization, WebSite, WebPage, and single-topic blogs with only one content type. On those projects, a full audit is a disproportionate investment: the plugin is enough, and the ontological part becomes a theoretical exercise with no practical impact.

Further reading: theory & practice

This page presents the audit method. The two linked guides explore it from two complementary angles on the IMWEB mother site.

The two guides are complementary and cross-reference each other. Theory without practice remains an intellectual exercise; practice without theory becomes a checklist of rules with no "why".

FAQ