Computational Marketing
FeaturesLong read

A topical map is a data structure you diff against your live site, not a planning doc someone maintains: how a technical B2B team should store page families, search ownership and hub links as queryable data, and check them in CI

Store page families and hub links as data, then fail the build when the live site drifts.

· 9 min read
Cover illustration for “A topical map is a data structure you diff against your live site, not a planning doc someone maintains: how a technical B2B team should store page families, search ownership and hub links as queryable data, and check them…
Features · November 21, 2026 · 9 min read · 1,976 words

A topical map should be a data structure a technical B2B team can diff against its live site. Storing page families, search ownership, and hub links as queryable rows makes gaps and conflicts computable. Enforcing those rows in CI turns the map into a contract between what the team intends to publish and what the site actually contains.

Why a topical map stored as a document quietly breaks the moment content ships

The team believes the map is current, but the site has moved on. A page has been published, another redirected, and a third removed without a corresponding change to the planning spreadsheet. The document still describes the intended site, while readers and crawlers encounter a different one.

That gap is hard to see during ordinary publishing work. A spreadsheet built during planning and edited when someone remembers can look complete even as duplicate intent ownership and stale entries accumulate. What does “covered” mean if the destination now returns a 404? A rich-text document cannot answer that by comparing its entries with HTTP responses. Without a machine-readable contract and a process that checks it, those contradictions wait for a manual audit.

What a topical map actually models, stated as a data schema

With one row per page, each check has a record to compare. The page_family field groups the rows that queries check for coverage and ownership, while primary_intent holds the main search intent that those queries compare. Without the same intent token, small changes in wording can hide an overlap. The owner_url field identifies the destination accountable for that intent. The status field distinguishes covered, needs-update, and missing, so planned coverage is not mistaken for live coverage.

Page roles need a constrained vocabulary. The available roles are pillar, subtopic explainer, comparison, use case, location page, industry page, FAQ, and transactional. Queries depend on those labels staying consistent. A separate section field can distinguish Core Section pages, which bear monetization and high prominence, from Outer Section pages, which support coverage, build historical data, and route authority back.

Links belong in the schema too, as references. A hub reference identifies the family’s hub, while hub_links records the rows a page must link to and receive links from. With foreign-key-style references, a join can find a page that has no inbound hub relationship. Notes in a margin cannot support that comparison reliably. Together, these fields describe both the pages and the relationships the live site is expected to preserve.

How the owner URL field enforces one-page-one-intent and prevents cannibalization by design

What happens when two pages claim the same intent? With a documented convention, someone has to notice and decide whether the overlap is acceptable. With an ownership constraint, different owner URLs for the same intent cluster are a schema violation. The contract makes the conflict explicit before another competing page ships.

Resolving that conflict requires one of three recorded decisions. Consolidation lets one URL absorb the other, differentiation changes the scopes so their intents no longer overlap, and a redirect sends one URL to the owner with a 301. The decision needs a date as well. Otherwise, a later publishing cycle can recreate the overlap because the map preserves neither the resolution nor when it happened.

That record also makes ownership changes reviewable in a diff. A comparison with Search Console can flag when the URL appearing for the cluster’s primary query differs from the declared owner, although that observed mismatch is distinct from duplicate ownership in the schema. At publication time, the stronger preventive control is simpler. Requiring a corresponding approved row and unique ownership assignment before a new URL reaches production prevents an AI content pipeline from creating overlapping pages at publish speed.

Storing the map as queryable data — format choices, storage options, and what makes a schema testable

The storage choice depends on who writes rows and how CI reads them. YAML or JSON checked into the repository makes changes visible in git and avoids an external dependency for CI reads. A SQLite database committed with the codebase is another viable store. A headless CMS with a queryable API suits a workflow in which non-technical editors need to maintain rows. No format wins on its own.

The CMS option changes the build’s dependencies, however. CI must authenticate and retrieve the map through the API, so an unavailable API can interrupt a build. Repository files make that read local, while placing row changes inside the repository workflow. Either approach needs structured, versioned data and a stable schema. Even a readable file can have inconsistent entries if its types are not enforced.

Schema validation therefore comes before structural checks. A JSON Schema or equivalent defines required fields, including owner_url, page_family, page_role, and status, and constrains the permitted values. A misspelled status must fail validation so that a coverage query does not miss it. Versioning the schema also makes changes to the contract reviewable. That is important when a template change can break hundreds of rows at once.

The CI checks that turn the map into a structural contract the codebase enforces

Coverage detection checks the HTTP response from the owner URL for each row marked covered. A 200 passes, while a 404 or a redirect to a different URL violates the contract. This catches pages deleted or restructured without a map update. Intent uniqueness compares primary_intent values within each page_family. A duplicate fails the check before the competing page ships.

Orphan detection compares covered owner URLs with the targets recorded in other rows’ hub_links. A URL with no inbound hub reference produces a warning or failure, according to team policy. The new-URL gate checks the opposite direction. It compares URLs created by the content pipeline with approved map rows, blocking production promotion when a URL lacks a designated owner and family.

Structured-data correspondence adds a check against rendered HTML. The JSON-LD must declare the @type and entity properties specified in the row, so a page’s declared role and its structured data do not drift apart. This check needs more fields than the minimum schema has. At build time, JSON-LD linting and representative validation per template keep the work bounded. Full-crawl validation belongs in a scheduled job.

A violation and its enforcement point are separate decisions. Fast structural failures can block a PR, while slower live-site failures can open issues after a nightly crawl. This keeps work that needs the network out of the commit hook while still flagging live drift. The pipeline finds the mismatch. Human review can then focus on how to resolve it.

How the same data structure determines which pages are eligible to appear in AI-generated answers

The map also governs structural conditions that can support inclusion in AI-generated answers. It does not confer eligibility or guarantee citations by itself. Retrieval may pick a passage, sentence, or claim from a cluster. The family remains useful because a pillar and focused spokes, joined by descriptive internal anchors, provide breadth and corroboration across related questions.

A missing row exposes a hole in that coverage. For that intent, the brand lacks a mapped answer, leaving room for another source to supply it. The about and mentions properties in WebPage and Article schema connect content to entities, while stable @id URIs can cross-reference those entities across pages. The map specifies those declarations, and CI checks whether they exist in rendered HTML.

Real buyer questions, grouped by map cluster, can be run through ChatGPT, Perplexity, Claude, and Google AI answers on a fixed cadence. Logging the citation rate for each cluster shows where coverage is weak. A citation gap then calls for investigation against the map before attributing it to a particular field. The distinction prevents structural completeness from becoming a substitute for outcome measurement.

Running the diff in practice — what a team checks on a PR, nightly, and quarterly

Diagram: From PR to Nightly to Quarterly: Three CI Cadences. Visualizes: The article describes three distinct cadences for running topical-map checks, each catching a different class of problem.

Each cadence catches a different kind of change. On every PR, required-field validation, vocabulary checks, intent uniqueness, and the new-URL gate examine the proposed structure. These checks run in under a minute and block merge on failure. They answer whether the proposed change respects the contract. They do not establish whether an already-published URL still works.

The nightly job tests that live state instead. It checks covered URLs for errors or redirects, looks for broken hub reachability, and compares rendered JSON-LD with map declarations. These failures open issues or notify the owning team while the nightly deploy proceeds. The distinction is deliberate. A valid commit can coexist with a live-site problem that only HTTP checks or a crawl reveal.

At quarterly review, the team checks whether the contract still covers the right ground. Search intent shifts, competitor pages appear, and AI answer patterns change even when every URL and field is still valid. Comparing the page_family set with current Search Console query clusters and logged AI citation gaps exposes thin or outdated coverage. The resulting diff adds missing rows with priorities, merges overlapping rows, records redirects when ownership changes, and closes clusters outside the site’s declared scope. Each change becomes a PR, so decisions on scope go through the same review as changes to the structure.

The objection that topical structure alone is insufficient when AI engines weight off-site consensus

The strongest objection is that on-site completeness addresses only part of AI visibility. An engine may draw on third-party directories, review platforms, or other sources of corroboration. The notes also give no basis for a fixed split where Gemini rewards owned sites while ChatGPT rewards third-party consensus. Where each platform actually cites the brand merits investigation.

That limitation calls for a schema extension. An off_site_coverage field per cluster can record target industry directories, review platforms, and authoritative publications where the brand should appear for the relevant entities. A CI-adjacent job can check for brand mentions and flag covered clusters that have no off-site corroboration. Per-platform citation tracking then distinguishes families with both coverage and citations from those with strong on-site coverage but weak citation results. The latter is a signal to investigate external corroboration as one possible missing ingredient.

Getting a technical B2B team to the first working version — schema, seed data, and the first CI gate

Diagram: First Working Version in One Sprint: Five Steps. Visualizes: The article lays out a concrete build sequence for reaching a first working topical-map CI system within a sprint.

For a first working version by the end of a sprint, the recommended starting point is a YAML file, a JSON Schema, and one new-URL gate. Define five required fields, namely owner_url, page_family, page_role, primary_intent, and status. Constrain the role and status vocabularies, then commit the schema. This produces a testable contract before the richer link and entity checks exist. The review process still needs to grant permission to publish, since covered only records coverage.

Next, seed the file from an existing audit. A live-site crawl and a Search Console URL export provide the URL inventory, with one row per URL and family and intent assignments drawn from the existing content. Mark rows covered initially and flag obvious overlaps as needs-update. Those initial labels are a starting claim awaiting an HTTP audit. The nightly check will test them against the site.

The first CI job compares build URLs with the map. Any URL without a matching approved entry fails with “new URL [url] has no approved topical map entry”. From the start, this gate makes the team choose an intent for each new page before it ships. The next addition is the intent-uniqueness check in the same job. If pages in a family have the same primary_intent value, the build fails and shows which pages compete.

Finally, a nightly cron job fetches each covered owner URL and opens a GitHub issue for a non-200 response. That supplies the first live-site drift detector without requiring the complete system. Later checks can add hub relationships, structured-data correspondence, and citation measurement. Each passing PR keeps new changes accountable to the data, and each clean nightly run provides evidence that the checked parts of the map and site remain in sync.

More in Features