# How the Unknown-Key Rule Detects Potential Typos in YAML Files

> Learn how the unknown-key rule in YAML detects typos by comparing unrecognized keys to valid schema keys using Levenshtein distance, flagging likely misspellings within a distance of 2.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-06-28

---

**The unknown-key rule detects potential typos in YAML by comparing unrecognized keys against valid schema keys using Levenshtein distance, flagging matches within a distance threshold of 2 as likely misspellings.**

The DESIGN-MD specification uses YAML for configuration, and the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) CLI includes a linter to validate these files. The **unknown-key rule** is a critical validation mechanism that identifies unrecognized keys and suggests corrections when they appear to be misspelled versions of valid schema properties. This rule prevents configuration errors by catching typos early in the development process.

## How the Unknown-Key Rule Detects Typos

The detection logic operates in three distinct phases, traversing from raw YAML parsing to actionable developer feedback.

### Step 1: Collecting Unknown Keys

During the parsing phase, the linter extracts keys that appear in the YAML but lack definitions in the schema. In [`packages/cli/src/linter/model/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/handler.ts), the parser populates `state.unknownKeys` with these unrecognized key names and stores their corresponding raw values in `state.unknownKeyValues`. This collection phase isolates potential typos from the set of valid configuration properties.

### Step 2: Computing String Similarity

For each unknown key, the rule retrieves the complete set of valid schema keys. It then executes a **Levenshtein distance** algorithm (implemented in [`packages/cli/src/linter/linter/rules/levenshtein.test.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/levenshtein.test.ts)) to calculate the edit distance between the unknown key and every valid key. When the minimum distance is less than or equal to **2**, the rule identifies the closest-matching schema key as a probable correction.

### Step 3: Generating Typo Suggestions

When a candidate typo is identified, the rule constructs a `RuleFinding` object containing the unknown key name, the suggested correction, and the precise location in the source file. The finding includes a diagnostic message formatted as: "`<unknown-key>` is not a known key. Did you mean `<suggested-key>`?" This implementation resides in [`packages/cli/src/linter/linter/rules/unknown-key.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/unknown-key.ts).

## Implementation Details

The rule is registered in the linter pipeline through [`packages/cli/src/linter/linter/rules/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/index.ts), which imports and exposes the `unknownKey` function. The core logic accepts a `DesignSystemState` object containing the accumulated parsing state and returns an array of findings.

```typescript
// Example invocation from the linter pipeline
import { unknownKey } from './unknown-key.js';

function runLinter(state: DesignSystemState) {
  const findings = unknownKey(state);
  // findings contains suggestions when typos are detected
  console.log(findings);
}

```

A typical finding returned for a typo like `colr` instead of `color`:

```json
{
  "message": "`colr` is not a known key. Did you mean `color`?",
  "location": { "line": 12, "column": 3 },
  "severity": "error"
}

```

The test suite in [`packages/cli/src/linter/linter/rules/unknown-key.test.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/unknown-key.test.ts) validates this behavior, demonstrating how the rule handles various misspelling scenarios against the DESIGN-MD schema.

## Summary

- The **unknown-key rule** validates YAML by identifying keys that do not exist in the schema.
- It uses **Levenshtein distance** with a threshold of **2** to find similar valid keys.
- Findings are generated in [`packages/cli/src/linter/linter/rules/unknown-key.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/unknown-key.ts) and include specific line and column locations.
- The rule integrates into the CLI via [`packages/cli/src/linter/linter/rules/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/index.ts).
- This approach catches configuration errors early by suggesting corrections for misspelled properties.

## Frequently Asked Questions

### What is the Levenshtein distance threshold for typo detection?

The rule uses a threshold of **2** for the Levenshtein distance calculation. If an unknown key requires two or fewer character insertions, deletions, or substitutions to match a valid schema key, the rule flags it as a potential typo and suggests the valid key.

### Where does the unknown-key rule source its list of valid keys?

The rule derives valid keys from the DESIGN-MD schema definition. During the parsing phase in [`packages/cli/src/linter/model/handler.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/handler.ts), the linter distinguishes between defined schema properties and unrecognized keys, storing the latter in `state.unknownKeys` for subsequent analysis.

### How does the rule handle cases where multiple valid keys are similar?

The rule calculates the Levenshtein distance against every valid schema key and selects the candidate with the smallest distance. If multiple keys share the same minimum distance (≤ 2), the implementation typically suggests the first closest match found, though the specific tie-breaking logic is defined in [`packages/cli/src/linter/linter/rules/unknown-key.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/unknown-key.ts).

### Can I adjust the typo detection sensitivity in the configuration?

The threshold of 2 is hardcoded in the rule implementation within [`packages/cli/src/linter/linter/rules/unknown-key.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/unknown-key.ts). To adjust the sensitivity, you would need to modify the source code and rebuild the CLI, as the current version does not expose this parameter through external configuration files.