How to Build a Site-Wide Entity Graph

Most structured data on the web is decoration: an Article block here, an Organization block there, none of them aware of each other. A site-wide entity graph is different. Every block points at the same nodes, so a machine reading any page can reconstruct the whole map of who you are and what you know.

What is a site-wide entity graph?

A site-wide entity graph is a set of JSON-LD nodes, spread across many pages, that share identifiers so they describe one connected knowledge graph. The author on an article, the Person on the About page and the subject of the résumé are the same node because they carry the same @id — not because a parser guessed from matching names.

That is this site's own graph: every node is a page at /entities, every edge is both a visible link and a JSON-LD relationship. Hover a node to see its neighbourhood.

Step 1 — Decide which entities you own

You do not need an entity for every noun. You need one for every thing a buyer or an assistant might ask about that you have a right to answer: the founder, the organization, each service, each location, each proprietary method, and the core concepts of your field. For a law firm that might be twenty. For this site it is twenty-eight.

Step 2 — Mint stable identifiers

Use the hub URL plus a fragment: https://example.com/entities/geo#term. Identifiers must never change once published. A useful convention: #person, #organization, #website on the home page; #term on concept hubs.

Step 3 — Write the hub before the markup

An entity hub page needs, in order: a one-sentence definition that answers “what is X?” on its own, the entity's relationships as links, the articles that discuss it, and its external identifiers. The definition is the passage you want retrieval systems to lift; write it like a dictionary entry, not a sales line.

Step 4 — Connect pages to entities

{
  "@type": "Article",
  "headline": "AI pages vs. AI architecture",
  "author": { "@id": "https://georgemoreas.com/#person" },
  "about": [{ "@id": "https://georgemoreas.com/entities/internal-linking#term" }],
  "mentions": [{ "@id": "https://georgemoreas.com/entities/rag#term" }]
}

about is what the page is primarily about; mentions is what it references. Every article on this site emits about automatically from the same registry that renders the “Entities in this essay” block.

Step 5 — Connect entities to the world

sameAs points to authoritative external descriptions of the same thing: a Wikipedia article, an official specification, a LinkedIn profile, a Google Business Profile. It is how you tell a machine “my GEO is the GEO in this paper,” resolving ambiguity you cannot resolve with text alone.

Step 6 — Mirror every edge with a visible link

Structured data that the visible page does not support is a mismatch, and Google's guidelines say markup should describe content users can see. If the JSON-LD says two entities are related, the hub pages should link to each other with descriptive anchors. This also gives crawlers a path; see AI pages vs. AI architecture for the linking side.

Step 7 — Keep it in one registry

The graph should be generated from one source of truth — a file, a CMS collection, a database table — so the hub pages, the article blocks, the JSON-LD, the sitemap and your llms.txt cannot drift. Drift is the quiet killer: two definitions of the same term on two pages is exactly the ambiguity the graph exists to remove.

Common mistakes

• Re-describing the same Organization in full on every page instead of referencing its @id.
• Marking up FAQ or review content that is not visible on the page.
• Creating hub pages with no unique content — a definition and a list of links is the minimum, not the whole page.
• Letting sameAs point to profiles you do not control or that describe something else.

Background reading: what schema markup is and why your website should be a knowledge base.