Skip to content
contextlint

CTX-002 Term consistency

Overview

Section titled “Overview”

Validates that aliases defined in a glossary file are not used in document bodies. When Database is the canonical form and DB / database are registered as aliases, any occurrence of DB in the body is reported as warning. This is a project-scope rule and is evaluated across all documents loaded via include.

Detection is case-insensitive. The glossary file itself is excluded.

Why it matters

Section titled “Why it matters”

Notation drift like “should we write Database or DB?” is hard to call out in review and gradually erodes the searchability of the entire documentation set. AI-generated drafts are especially prone to using multiple notations for the same concept. Treating the glossary as the single source of truth and detecting alias usage mechanically keeps terminology consistent.

Options

Section titled “Options”
FieldTypeRequiredDescription
glossarystringYesGlob of the file treated as the glossary
termColumnstringYesColumn name that holds the canonical form
aliasColumnstring—Column name that holds aliases (comma-separated for multiple). Without it, nothing is detected
sectionstring—Restrict the table read from the glossary to one under a specific section
filesstring—Glob of files this rule applies to (the glossary itself is always excluded)

aliasColumn is technically optional, but without it no aliases are extracted from the glossary and the rule reports nothing. In practice it is effectively required.

Bad example

Section titled “Bad example”
docs/glossary.md:


| Term     | Aliases       |
| -------- | ------------- |
| Database | DB, database  |


docs/design.md:


# Design


We use a DB for storage.

The alias DB is used in docs/design.md, which triggers a violation.

docs/design.md
  line 3  warning  "DB" should be "Database" (defined in glossary)  CTX-002

After fix

Section titled “After fix”
docs/design.md:


# Design


We use a Database for storage.

Configuration example

Section titled “Configuration example”
{
  "rule": "ctx002",
  "options": {
    "glossary": "docs/glossary.md",
    "termColumn": "Term",
    "aliasColumn": "Aliases",
    "files": "docs/**/*.md"
  }
}

The glossary file is expected to look like this:

## Terms


| Term     | Aliases       |
| -------- | ------------- |
| Database | DB, database  |
| API      | Api, api      |

The Aliases column is comma-separated, so multiple aliases fit in a single cell.

Section titled “Related rules”