How to implement EntityMap

List your entities

Start with the concepts, products, people, or places your site most authoritatively covers. Aim for 10–50 entities to begin. Don't try to be exhaustive — prioritise depth over breadth.

For each entity you need: a stable ID, a name, a @type, a description in your own terms, and at least one chunk.

Write the root object

{
  "version": "1.0",
  "schema": "https://entitymap.org/spec/v1.0",
  "publisher": {
    "name": "Your Site Name",
    "url": "https://yoursite.com",
    "sameAs": "https://www.wikidata.org/wiki/Q..."
  },
  "generated": "2026-04-07T00:00:00Z",
  "entities": []
}

The publisher.name value must match the publisher field on every chunk exactly. This is the primary attribution mechanism — treat it as a constant.

Add entity objects

For each entity, follow this structure:

{
  "entityId": "e_001",
  "@type": "Concept",
  "name": "Your Entity Name",
  "alternateName": "Abbreviation if any",
  "description": "1–3 sentences defining this concept
    as your site uses it. Be specific to your context.",
  "sameAs": "https://www.wikidata.org/wiki/Q...",
  "relations": [],
  "hasChunks": []
}

Add chunks

Each entity needs 1–5 evidence chunks. Select your best, most specific passages — not introductory sentences. Each chunk must carry the publisher name.

"hasChunks": [
  {
    "chunkId": "c_001",
    "text": "A 1–5 sentence passage from your content.
      Max 600 characters. Extractive preferred.",
    "sourceUrl": "https://yoursite.com/page-url",
    "pageTitle": "Title of the source page",
    "publisher": "Your Site Name",
    "retrieved": "2026-03-27T09:00:00Z",
    "relevanceScore": 0.92
  }
]

Add relations

Relations are optional but valuable. Even a sparse relation graph significantly improves how AI systems traverse your knowledge. Use predicates from the standard vocabulary.

"relations": [
  {
    "predicate": "ENABLES",
    "targetId": "e_004",
    "targetName": "AI Share of Voice"
  },
  {
    "predicate": "INSTANCE_OF",
    "targetUri": "https://www.wikidata.org/wiki/Q1163385",
    "targetName": "Herfindahl-Hirschman Index"
  }
]

For internal targets (entities in your own EntityMap), use targetId. For external concepts, use targetUri pointing to Wikidata or schema.org. targetName is required in both cases.

Generate the HTML companion

The entitymap.html file is a crawlable, human-readable rendering of the same data. It MUST NOT be maintained separately from the JSON. Use the Waikay viewer to generate it from your JSON, or build a generator following §6 of the spec.

The HTML file must embed per-entity JSON-LD, render relations as internal hyperlinks, and carry data-publisher attributes on every chunk blockquote.

Create an account and project

Go to waikay.io/entitymap, create a free account, and set up a project for your domain.

Connect your site

The generator crawls your content, runs entity extraction, and identifies candidate chunks automatically.

Review and export

Review the extracted entities and evidence. Adjust descriptions, prune low-relevance chunks, and add any missing relations. Export both files — then deploy and add discovery hints as below.

Serve both files at root

https://yourdomain.com/entitymap.json
https://yourdomain.com/entitymap.html

Both files must be publicly accessible without authentication. No subdirectory paths.

Add robots.txt hint

# EntityMap
EntityMap: https://yourdomain.com/entitymap.json

Add HTML head link to every page

<link rel="entitymap" type="application/json"
      href="https://yourdomain.com/entitymap.json" />

Add entitymap.html to sitemap.xml

List entitymap.html in your sitemap with priority: 0.9 and changefreq: weekly. This signals freshness to crawlers and surfaces the file to AI systems that follow sitemaps.

<url>
  <loc>https://yourdomain.com/entitymap.html</loc>
  <priority>0.9</priority>
  <changefreq>weekly</changefreq>
</url>

Link to entitymap.html from your site footer

Add a visible hyperlink to entitymap.html in the footer of your home page — or better, in a sitewide footer so it appears on every page. This is the most reliable discovery mechanism available today, because every AI crawler that follows HTML links will find it without requiring any special standard support.

<footer>
  <a href="https://yourdomain.com/entitymap.html">EntityMap</a>
</footer>

Use entitymap.html as the link target — not the JSON file. The HTML version is designed for crawlers: it renders entity definitions, relations, and attribution as readable text with embedded JSON-LD, so any system that fetches and parses HTML will extract structured, publisher-attributed content.

For the JSON file, use the machine-readable <link> tag in the <head> (step 3 above) rather than a visible footer link.

Pre-publish checklist

Common mistakes

Publisher name mismatch. The most frequent error. "publisher": "Acme Corp" in the root and "publisher": "Acme" on a chunk will fail validation. Copy-paste the value, don't retype it.

Stale generated timestamp. The generated field must update on every rebuild. A file with a timestamp months old signals to consumers that the EntityMap is unmaintained.

Too many entities, too few chunks. It is better to have 15 well-evidenced entities than 80 with one weak chunk each. Depth signals authority. Breadth without evidence does not.

Generic descriptions. The description field should define the concept as your site uses it — not a Wikipedia summary. "AI Share of Voice is a metric that measures the proportion of AI-generated answers in which a brand appears" is specific. "Share of voice is a marketing metric" is not.

Maintaining JSON and HTML separately. The HTML file must be generated from the JSON. If you edit one manually, they will diverge. Treat the JSON as the source of truth at all times.