JSON-LD is a graph. @id references connect nodes. An Article references its author by @id. The author references the organization by @id. The organization references its social profiles via sameAs. Validators check each node against its schema type definition and stop there.
Google's knowledge-graph ingestion does not stop there. If the Article's @id reference to an author resolves to a node that doesn't exist, the author is skipped. If an Organization node declares a brand relationship but the brand node has no inverse reference back, the claim is weakened. If two nodes circularly reference each other with no base case, the parser may discard the whole cluster.
JSON-LD Graph Linter treats your JSON-LD as the graph it actually is.
Four failure modes the linter catches
Dangling @id references. An Article has "author": {"@id": "#author-1"}, and there's no node anywhere with "@id": "#author-1". Generic validators pass this silently. The graph linter flags every dangling pointer.
Orphan nodes. A node declared with an @id that nothing else references and that itself references nothing. It sits in the graph alone, connected to nothing, ignored by consumers. Often the result of a template that emits the node but the referencing template was deleted.
Missing inverse properties. Schema.org defines bidirectional relationships. If Person worksFor Organization, Organization should have employee back to Person. author → creativeWork is another pair. When the inverse is missing, the knowledge graph sees a weaker signal.
Circular references with no root. Node A references B, B references A, neither is referenced from outside. Some parsers handle this; some don't. All parsers prefer a root node that can be traced to.
What the output looks like
The linter walks every JSON-LD block on the page, flattens the @graph, builds a node table (id → types + inbound count + outbound count), and a reference table (every @id pointer with its source + property). Then runs four checks and emits:
- Node count, reference count, dangling count.
- Orphan node list (ids that nothing points to + that point nowhere).
- Missing-inverse list with the source relationship and the expected inverse.
- An AI fix prompt that takes the findings and emits a corrected
@graphblock with bracketed placeholders for any missing node.
Related reading
- Schema Validator — node-level Google rich-results check
- Schema Completeness — full @graph generator
- Entity Consistency Checker — cross-page drift
Fact-check notes and sources
- Schema.org data model: schema.org/docs/datamodel.html
- JSON-LD 1.1 spec: www.w3.org/TR/json-ld11
- Google on
@idusage: developers.google.com/search/docs/appearance/structured-data/product (see the cross-reference examples)
The $100 Network covers shipping consistent schema across a site network. A graph linter catches the drift that flat validators miss.
