Two Strings Per Entity: Killing Synonym Drift in a Content Codebase

An audit of a reference site turned up the same government agency written five ways across six pages: its full legal name, a short form, an initialism, and two descriptive paraphrases a writer had reached for to avoid repeating himself.

To a reader those are five ways of saying one thing. To anything parsing the page they are five unmatched strings and one diluted entity. Copywriters call the variation good style. It is the single easiest thing to get wrong in a content codebase, because nothing fails when you get it wrong.

The registry

The fix is to stop treating entity names as prose and start treating them as identifiers with a display layer.

export interface Entidad {
  id: string
  nombre: string   // legal name, first mention in a section
  corto: string    // short form, later mentions in that same section
  tipo: 'GovernmentOrganization' | 'Organization' | 'Legislation'
  url: string      // official first-party URL, doubles as the schema @id
  rol: string      // one stated relationship, not a description
}

Two permitted strings per entity, and the rule about which to use is positional rather than stylistic: nombre on first mention inside a section, corto for the rest of that section. There is no third option, so there is no decision to make and nothing to drift.

Three details earn their place.

url doubles as the schema @id. Emitting the entity's own official URL as its identifier means references across twelve pages resolve to one node instead of twelve. Getting this wrong is invisible in the rendered page and obvious in a graph.

rol is a relationship, not an adjective. "Certifies the current bank interest rate and supervises credit establishments" is a stated relationship. "Is a leading financial authority" is not, and a machine can do nothing with it.

Initialisms are banned in body copy. An initialism shares no substring with the name it abbreviates, so it reads as a separate entity to anything doing string matching. Cheap rule, and it removed two of the five variants on its own.

Enforce it where it can fail

A registry nobody checks is a style guide with extra steps. Two checks catch most of it:

// 1. A page must declare the entities it is about.
type Page = { about: EntidadId[]; /* ... */ }

// 2. Body copy may not contain a banned variant.
const BANNED = ['SFC', 'la Financiera', 'el supervisor financiero']
for (const term of BANNED) {
  if (body.includes(term)) {
    throw new Error(`banned entity variant "${term}" in ${page.route}`)
  }
}

The banned list is not guesswork. It comes out of the audit that found the drift, so it grows only when a real variant appears in a real draft.

The about array is the load-bearing one. Making a page declare its entities up front means schema generation, internal linking, and related-page selection all read from one field instead of three separate heuristics inferring subject matter from prose.

The URL rule that matters most

One more constraint, and it applies to the whole registry: a URL goes in only after it has been fetched and found to resolve.

That sounds like an obvious hygiene rule until you notice how many sites emit sameAs pointers to identifiers nobody verified. A wrong sameAs is worse than an absent one, because it actively asserts your entity is a different entity. Absent means unknown. Wrong means confidently incorrect, and nothing downstream will tell you.

What it costs

Prose gets slightly more repetitive. The same agency name appears in full at the top of every section that mentions it, and a writer who values variety will find that grating.

It reads worse to a human by a small margin and parses correctly by a large one. For reference content, where the reader arrived from a search for the exact term, that trade is worth making.

The pattern is running in production on a Colombian consumer credit reference site, where the entities are financial supervisors and statutes and getting their names right is closer to a correctness requirement than a style preference.