How to Design a Data Dictionary for AI Visibility Analytics

AI-visibility programs often start with dashboards. That is understandable: charts make a new discipline feel concrete.

But the dashboard is not the foundation. The foundation is a shared data dictionary that tells every analyst, crawler, pipeline, and stakeholder what one observation means.

Without that dictionary, two people can review the same answer and disagree about whether a brand was merely mentioned, actively recommended, or cited as evidence. The chart may still render. The number may still have two decimal places. It just will not be trustworthy.

This guide describes a practical way to design the data model behind an AI-visibility workflow. It is intended for teams auditing brand mentions, recommendations, citations, and source destinations across AI answer surfaces.

Educational note: this is an implementation framework, not a claim about any particular AI platform's ranking algorithm.

1. Start by declaring the observation grain

Before choosing columns, write one sentence that defines a row.

A useful default is:

One row represents one captured answer for one versioned prompt, on one named AI surface, in one market and locale, at one capture time.

That sentence prevents a common mistake: mixing prompt-level facts, answer-level facts, brand-level annotations, and citation-level facts in a single wide table.

A captured answer may mention several brands and include several citations. Those are one-to-many relationships. Model them as related tables or nested records instead of repeatedly overwriting fields.

A simple logical model has four layers:

1. Prompt — the question, its intent, and its version.
2. Observation — where and when the answer was captured.
3. Entity assessment — how a brand or product appears in that answer.
4. Citation assessment — which URLs were surfaced and what role they played.

2. Give every mutable thing a version

Prompt text changes. Entity aliases change. URL canonicalization rules change. Analyst rubrics improve.

If a changing object has only an ID, a historical result can silently acquire a new meaning. Pair stable IDs with explicit versions:

• prompt_id + prompt_version
• entity_id + entity_dictionary_version
• methodology_version
• canonicalization_rule_version

Never edit an old prompt definition in place after collecting observations. Create a new version and preserve the bridge between versions. This keeps trend lines auditable.

3. Separate collection facts from analyst judgments

Collection facts should describe what happened without interpretation:

• observation_id
• prompt_id
• prompt_version
• engine_surface
• market
• locale
• captured_at
• capture_status
• raw_answer
• evidence_bundle_uri

Analyst judgments belong in a second layer:

• entity_id
• mention_state
• recommendation_strength
• answer_position
• claim_alignment
• confidence_label
• analyst_id
• reviewed_at

That separation matters operationally. If the rubric changes, the team can re-annotate preserved raw evidence without pretending the source observation changed.

4. Use enums that can survive review

Free-text labels drift quickly. One analyst writes "strong mention," another writes "top pick," and a third writes "recommended." A dashboard later treats them as different categories.

Prefer a small controlled vocabulary. For example:

Mention state

• absent — the entity is not present.
• named — the entity is mentioned without evaluation.
• described — the answer provides meaningful descriptive context.
• compared — the entity is evaluated against alternatives.
• recommended — the answer explicitly suggests choosing or considering it.

Recommendation strength

• none
• conditional — suitable only for a stated situation or constraint.
• positive — clearly favorable, but not the leading choice.
• primary — presented as a leading or first choice.

Confidence label

• high — the evidence directly matches the definition.
• medium — the label is reasonable but requires interpretation.
• low — evidence is incomplete or ambiguous.

Confidence should describe the annotation, not the analyst's enthusiasm for the brand.

5. Model citations as first-class records

A URL is not merely a string attached to an answer. It passes through redirects, tracking parameters, fragments, and canonical tags. Preserve both the observed value and the normalized result.

Useful fields include:

• raw_cited_url
• resolved_url
• canonical_url
• registrable_domain
• source_role
• citation_position
• http_status_at_capture
• last_verified_at

Keep the raw URL immutable. Canonicalization can then be re-run as rules improve.

A conservative normalization policy might:

1. lowercase the hostname;
2. remove a default port;
3. strip a fragment;
4. remove only known tracking parameters;
5. follow redirects with a bounded hop count;
6. honor a canonical tag only when it is safe and relevant;
7. retain both the resolved and canonical values.

Do not remove every query parameter. Some parameters identify genuinely different resources.

6. Store the evidence needed to reproduce a judgment

A row without evidence is difficult to audit. An evidence bundle can include:

• captured answer text;
• citation list in displayed order;
• screenshot or render;
• capture timestamp and timezone;
• prompt text and version;
• engine surface and visible mode;
• collection notes and error state.

The bundle should be addressable with a stable URI or object key. Access controls and retention policies still apply, but the record needs to tell a reviewer where the evidence lives.

A compact observation can store a generated observation ID, the prompt ID and version, the named surface, market, locale, UTC capture time, capture status, methodology version, and evidence-bundle URI. The specific storage system is less important than immutable identity and traceable provenance.

7. Define invariants in plain language and code

An invariant is a rule that must remain true. Good data dictionaries include both a human explanation and a machine-checkable constraint.

Examples:

• captured_at must include a timezone.
• raw_answer may be empty only when capture_status is not complete.
• recommendation_strength cannot be primary when mention_state is absent.
• every citation record must reference an existing observation.
• one observation cannot contain duplicate citation positions.
• a normalized URL never replaces its raw source value.

Put these checks close to ingestion. A dashboard should not be the first place anyone discovers an impossible combination.

8. Build a small adjudication loop

Before scaling collection, ask two analysts to label the same small sample independently.

Do not begin by chasing an impressive agreement score. Begin by finding ambiguous definitions.

For every disagreement:

1. reveal the evidence;
2. identify which phrase in the rubric allowed two interpretations;
3. refine the definition or add a boundary example;
4. record the decision in a change log;
5. re-label the affected sample.

Boundary examples are especially valuable. A dictionary becomes useful when it explains not only what a label is, but also the nearest thing that does not qualify.

9. Keep methodology changes visible

A methodology change should create a release note. At minimum, record:

• version number;
• effective date;
• changed fields or definitions;
• reason for the change;
• expected effect on historical comparability;
• migration or re-annotation plan.

If an old and new method cannot be compared directly, show a break in the trend rather than blending them. Honest discontinuity is better than false precision.

10. Design the reporting layer last

Once the schema and definitions are stable, metrics become easier to defend.

For example, "recommendation rate" still needs a denominator. Is it:

• all scheduled prompts;
• only successful captures;
• only answers where the category was understood;
• or only observations eligible under a particular rubric version?

Write that denominator into the metric definition. Include exclusions, required fields, and version scope. Then the same calculation can be implemented in SQL, a notebook, or a dashboard without changing meaning.

A practical review checklist

Before shipping an AI-visibility data dictionary, confirm that:

• every table has a declared grain;
• stable IDs and mutable versions are separate;
• raw evidence is preserved;
• collection facts and judgments are not conflated;
• enum values have positive and negative examples;
• URLs retain raw, resolved, and canonical forms;
• invariants are machine-checkable;
• timestamps include timezones;
• analyst and methodology provenance are recorded;
• metric denominators and exclusions are explicit;
• changes have release notes;
• historical observations remain reproducible.

Closing thought

AI-visibility reporting is young enough that teams are still inventing vocabulary while building the measurement systems. That makes definitions a product feature, not administrative cleanup.

At Corank, we think about visibility as an evidence and measurement problem: preserve the answer, define the observation, make judgments reviewable, and let reporting inherit those disciplined choices.

For a companion reference of common terms, see the AI visibility reporting glossary. Use it as a starting point, then adapt definitions to your own methodology and document every change.