Building an entity graph in JSON-LD
Telling search engines and language models who you are by declaring your interconnected identities, instead of hoping machines infer them.
By Andrew J. Pyle
Search engines and language models will not reliably connect the dots between your scattered web presences. If you want them treated as one identity, you have to say so, in machine-readable form.
This is how I build an entity graph in JSON-LD: one canonical Person node, a mesh of matching identifiers that resolves both ways, honest claims, and structured data emitted where a crawler actually reads it.
01TELL THE MACHINES WHO YOU ARE
Declared, not inferred
Search engines and language models will not reliably connect the dots between your scattered web presences. The personal site, the projects, the profiles, the company. If you want those treated as one identity, you have to say so, in machine-readable form.
The relationships are not inferred. They are declared. Hope is not a structured-data strategy.
02ONE HUB NODE
A canonical anchor for the person
Start with one authoritative identifier: a single Person node with a stable id that everything else attaches to. That node is the hub. Every page, every profile, every organization points back to the same anchor.
Without one canonical anchor, you get fragments: a dozen half-identities an engine cannot merge. With one, you get a graph that resolves to a single person.
03MATCHING IDS ACROSS DOMAINS
The mesh has to resolve both ways
A one-sided claim is weak. If your site says you founded a company, the company's site should emit the same identifier back. Matching ids across domains let an engine merge the nodes into one entity instead of guessing.
The same discipline covers your external profiles. Point to them, and where you can, have them point back. A mesh that resolves both ways is far stronger than a pile of one-directional assertions.
04OVERSTATE NOTHING
The graph has to match reality
Structured data is a claim, and a claim that does not match reality is a liability. Overstate nothing. If a relationship changes, update the graph. A graph that drifts from the truth is worse than no graph, because it teaches the machines something false about you.
This is the same rule as the content do-no-harm gate and the observed-status principle. Honest and current beats impressive and stale, every time.
05STATIC AT BUILD TIME
Where the graph gets emitted
Render the JSON-LD as static HTML at build time, not from client-side JavaScript. A crawler or a model that does not run your scripts has to see the graph immediately, in the raw HTML. If it is injected after load, the machines that matter most may never see it.
If it is not in the HTML a crawler receives, it does not exist. Emit the graph where the crawler reads, not where the browser renders.
06NEXT STEPS
From scattered pages to one identity
- Define one Person node with a stable id, and make it the hub.
- Attach your projects and organizations to it, with matching ids where you control both ends.
- Audit every claim against reality, and remove anything you cannot stand behind.
- Emit the graph as static HTML at build time, and verify it in the raw page source.