useConsistentObjectKeys (JSON)

Language JSON (and super languages)

Summary

Rule available since: v2.5.14
Diagnostic Category: lint/nursery/useConsistentObjectKeys
This rule has an unsafe fix.
The default severity of this rule is warning.
Sources:
- Same as json/no-unnormalized-keys

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useConsistentObjectKeys": "error"
6
      }
7
    }
8
  }
9
}

Description

Enforce JSON keys with consistent Unicode representation.

Unicode characters can have different internal representations that look identical. For example, “é” can be stored as one code point (U+00E9) or as “e” plus a combining accent (U+0065 + U+0301). Unicode normalization converts text to a standard form (such as NFC) so visually identical keys share the same representation. This avoids confusing behavior in JSON objects where equality checks and key lookups should treat matching text consistently.

See Unicode Standard Annex #15 for the normalization standard.

Examples

Invalid

In JSON, \u followed by four hexadecimal digits represents a Unicode code point. The following key uses \u0065 for e followed by \u0301 for a separate combining accent:

1
{
2
    "caf\u0065\u0301": "espresso"
3
}

code-block.json:2:5 lint/nursery/useConsistentObjectKeys  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This object key mixes Unicode characters that can be encoded in more than one way.
  
    1 │ {
  > 2 │     "caf\u0065\u0301": "espresso"
      │     ^^^^^^^^^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Characters that look identical can have different byte representations, so such keys may fail to compare as equal.
  
  ℹ Rewrite the key so equivalent characters use a single, consistent Unicode encoding.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Rewrite the key using a consistent Unicode encoding.
  
    1 1 │   {
    2   │ - ····"caf\u0065\u0301":·"espresso"
      2 │ + ····"café":·"espresso"
    3 3 │   }
    4 4 │

Valid

The same visible key can use the single precomposed character é:

1
{
2
    "caf\u00e9": "espresso"
3
}

Options

`form`

Selects the Unicode normalization form. Defaults to NFC.

NFC combines equivalent character sequences where possible;
NFD separates characters into their base character and combining marks;
NFKC replaces compatibility characters with ordinary equivalents, then combines sequences;
NFKD makes the same compatibility replacements but keeps sequences separated.

For example, the compatibility forms rewrite the single character ½ as the three-character sequence 1⁄2.

The following configuration selects NFC:

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useConsistentObjectKeys": {
6
          "level": "on",
7
          "options": {
8
            "form": "NFC"
9
          }
10
        }
11
      }
12
    }
13
  }
14
}

1
{
2
    "caf\u0065\u0301": "espresso"
3
}

code-block.json:2:5 lint/nursery/useConsistentObjectKeys  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This object key mixes Unicode characters that can be encoded in more than one way.
  
    1 │ {
  > 2 │     "caf\u0065\u0301": "espresso"
      │     ^^^^^^^^^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Characters that look identical can have different byte representations, so such keys may fail to compare as equal.
  
  ℹ Rewrite the key so equivalent characters use a single, consistent Unicode encoding.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Rewrite the key using a consistent Unicode encoding.
  
    1 1 │   {
    2   │ - ····"caf\u0065\u0301":·"espresso"
      2 │ + ····"café":·"espresso"
    3 3 │   }
    4 4 │

The following configuration selects NFD:

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useConsistentObjectKeys": {
6
          "level": "on",
7
          "options": {
8
            "form": "NFD"
9
          }
10
        }
11
      }
12
    }
13
  }
14
}

1
{
2
    "\u00C5": "precomposed A-ring"
3
}

code-block.json:2:5 lint/nursery/useConsistentObjectKeys  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This object key mixes Unicode characters that can be encoded in more than one way.
  
    1 │ {
  > 2 │     "\u00C5": "precomposed A-ring"
      │     ^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Characters that look identical can have different byte representations, so such keys may fail to compare as equal.
  
  ℹ Rewrite the key so equivalent characters use a single, consistent Unicode encoding.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Rewrite the key using a consistent Unicode encoding.
  
    1 1 │   {
    2   │ - ····"\u00C5":·"precomposed·A-ring"
      2 │ + ····"Å":·"precomposed·A-ring"
    3 3 │   }
    4 4 │

The following configuration selects NFKC:

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useConsistentObjectKeys": {
6
          "level": "on",
7
          "options": {
8
            "form": "NFKC"
9
          }
10
        }
11
      }
12
    }
13
  }
14
}

1
{
2
    "\u00BD": "vulgar fraction one half"
3
}

code-block.json:2:5 lint/nursery/useConsistentObjectKeys  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This object key mixes Unicode characters that can be encoded in more than one way.
  
    1 │ {
  > 2 │     "\u00BD": "vulgar fraction one half"
      │     ^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Characters that look identical can have different byte representations, so such keys may fail to compare as equal.
  
  ℹ Rewrite the key so equivalent characters use a single, consistent Unicode encoding.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Rewrite the key using a consistent Unicode encoding.
  
    1 1 │   {
    2   │ - ····"\u00BD":·"vulgar·fraction·one·half"
      2 │ + ····"1⁄2":·"vulgar·fraction·one·half"
    3 3 │   }
    4 4 │

The following configuration selects NFKD:

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useConsistentObjectKeys": {
6
          "level": "on",
7
          "options": {
8
            "form": "NFKD"
9
          }
10
        }
11
      }
12
    }
13
  }
14
}

1
{
2
    "\u00BD": "vulgar fraction one half"
3
}

code-block.json:2:5 lint/nursery/useConsistentObjectKeys  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This object key mixes Unicode characters that can be encoded in more than one way.
  
    1 │ {
  > 2 │     "\u00BD": "vulgar fraction one half"
      │     ^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Characters that look identical can have different byte representations, so such keys may fail to compare as equal.
  
  ℹ Rewrite the key so equivalent characters use a single, consistent Unicode encoding.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Rewrite the key using a consistent Unicode encoding.
  
    1 1 │   {
    2   │ - ····"\u00BD":·"vulgar·fraction·one·half"
      2 │ + ····"1⁄2":·"vulgar·fraction·one·half"
    3 3 │   }
    4 4 │