Handling Forbidden Characters in JSON Property Names

Most articles on this topic mix together two different problems: invalid JSON syntax, and valid JSON keys that are inconvenient in code, databases, or query tools. That distinction matters. In standard JSON, a property name is just a string, so spaces, dots, hyphens, emoji, and leading digits are usually allowed.

The actual syntax rules are much narrower. Keys must be enclosed in double quotes, embedded quotes and backslashes must be escaped, and raw control characters are not allowed inside the string. If your payload parses correctly but still breaks later, the problem is usually not JSON itself. It is the consumer.

What is actually forbidden in a JSON property name?

Per RFC 8259, object member names are strings. That means a key becomes invalid JSON only when it breaks JSON string rules.

• Unquoted keys are invalid. JSON requires double quotes around every property name.
• Single-quoted keys are invalid. Single quotes belong to JavaScript literals, not JSON syntax.
• A raw double quote or raw backslash inside the key is invalid unless it is escaped as \" or \\.
• Raw control characters from U+0000 through U+001F are invalid inside the key. Use escapes such as \t, \n, or \u0000 instead.

{
  name: "Ada",               // invalid: key is not quoted
  'job-title': "Engineer",  // invalid: single quotes are not JSON
  "quote"inside": true      // invalid: quote inside key is not escaped
}

{
  "first name": "Ada",
  "job-title": "Engineer",
  "price.usd": 12.5,
  "123start": true,
  "caf\u00E9": "valid Unicode",
  "": "empty key is valid JSON",
  "quote\"inside": "escaped quote",
  "line\nbreak": "escaped newline in the key"
}

Characters that are valid JSON but still cause trouble

These characters are often described as forbidden, but the real issue is downstream compatibility rather than JSON syntax:

• Spaces, hyphens, and leading digits are valid JSON, but they break JavaScript dot notation and many code generators.
• Dots are valid JSON, but dot-based path syntaxes may treat them as separators instead of literal key names.
• Empty-string keys are valid JSON, but they are hard to document and easy to mishandle in forms and UIs.
• Unicode is valid JSON, but normalization, fonts, and copy-paste can still create lookalike-key bugs.

Why JSON parses but your code still fails

JavaScript and TypeScript access rules

When a key contains spaces, dots, hyphens, or starts with a digit, use bracket notation. The JSON is valid. The access pattern is what changes.

const payload = JSON.parse(
  '{"first name":"Ada","price.usd":12.5,"123start":true}'
);

// Wrong or misleading:
// payload.first name
// payload.price.usd
// payload.123start

// Correct:
console.log(payload["first name"]);
console.log(payload["price.usd"]);
console.log(payload["123start"]);

type Payload = {
  "first name": string;
  "price.usd": number;
  "123start": boolean;
};

Duplicate names are a bigger risk than odd characters

RFC 8259 says object names should be unique. Duplicate keys are not always rejected, but behavior becomes implementation-dependent. Many parsers keep the last value, which can hide data loss.

{
  "role": "user",
  "role": "admin"
}

Database and query-language caveats

Some systems add their own restrictions on top of JSON. For example, current MongoDB documentation notes that support for field names containing $ and . improved in MongoDB 5.0, but those names are still discouraged because several features and query patterns do not handle them cleanly.

That is the pattern to watch for: the key is valid JSON on the wire, but a storage engine, path expression, ORM, analytics pipeline, or export step interprets the same character differently.

Practical handling strategies

1. Keep the wire format, normalize internally

If an external API already uses awkward keys, preserve the original payload at the boundary and map it into a safer internal shape. That keeps ingestion compatible without forcing strange keys throughout your codebase.

function normalizeKeys(input) {
  if (Array.isArray(input)) return input.map(normalizeKeys);
  if (!input || typeof input !== "object") return input;

  return Object.fromEntries(
    Object.entries(input).map(([key, value]) => {
      const safeKey = key
        .trim()
        .replace(/[.\s-]+/g, "_")
        .replace(/[^a-zA-Z0-9_$]/g, "")
        .replace(/^([0-9])/, "_$1");

      return [safeKey, normalizeKeys(value)];
    })
  );
}

2. Use explicit key mapping when names matter

If the exact original key must be preserved for round-tripping, use an explicit mapping table instead of a lossy "replace special characters" rule.

const keyMap = {
  "first name": "firstName",
  "price.usd": "priceUsd",
  "123start": "_123start"
};

function remapObject(obj, map) {
  return Object.fromEntries(
    Object.entries(obj).map(([key, value]) => [map[key] ?? key, value])
  );
}

3. Validate key names if you control the schema

For your own APIs, it is usually better to forbid awkward names up front than to keep compensating for them later.

{
  "type": "object",
  "propertyNames": {
    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
  }
}

Troubleshooting checklist

• Parser error near a property name: check for missing double quotes, single quotes, or an unescaped quote or backslash inside the key.
• Valid JSON but undefined at runtime: switch from dot notation to bracket notation when the key contains spaces, dots, hyphens, or leading digits.
• Unexpected value overwrite: inspect the payload for duplicate names.
• Database or search index rejection: look for system-specific rules around ., $, empty names, or path separators.
• Invisible-character bugs: reformat the payload and inspect escape sequences with a validator before blaming the application code.

Bottom line

There are fewer forbidden characters in JSON property names than most developers think. In pure JSON, the key only has to be a valid JSON string. Most real-world problems come later, when another tool gives special meaning to dots, spaces, dollar signs, hyphens, or leading digits.

Use Offline Tools' JSON Formatter to catch invalid string syntax first, then decide separately whether you also need a naming convention, schema rule, or normalization step for the systems that consume the data.