Pattern Validation with Regular Expressions in JSON Schema

Pattern Validation with Regular Expressions

The pattern keyword in JSON Schema validates that a string matches a regular expression. It uses the ECMA-262 regex dialect (the same as JavaScript), giving you access to character classes, quantifiers, groups, and anchors.

Basic Syntax

{
  "type": "string",
  "pattern": "^[A-Z]{2}-\\d{4}$"
}

This matches strings like "AB-1234" — two uppercase letters, a hyphen, and four digits. The ^ and $ anchors ensure the entire string must match, not just a substring.

How the Example Schema Works

The schema validates three common formatted strings:

1. phoneNumber — ^\\+[1-9]\\d{6,14}$ matches E.164 international phone numbers: a + sign, a non-zero first digit, and 6 to 14 additional digits. The value "+14155551234" (a US number) passes.

2. zipCode — ^\\d{5}(-\\d{4})?$ matches US ZIP codes in either 5-digit (90210) or ZIP+4 (90210-1234) format. The (-\\d{4})? group is optional.

3. hexColor — ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ matches CSS hex colors in 3-digit (#f00) or 6-digit (#3b82f6) notation. The alternation | inside the group handles both lengths.

Important: JSON String Escaping

Because the pattern is embedded in a JSON string, backslashes must be double-escaped. A literal \d in regex becomes "\\d" in the JSON schema. This is the most common source of pattern bugs.

Regex intent	JSON Schema string
\d (digit)	"\\d"
\. (literal dot)	"\\."
\+ (literal plus)	"\\+"
\\ (literal backslash)	"\\\\"

Anchoring

JSON Schema does not implicitly anchor patterns. The regex "\\d{3}" matches any string containing three consecutive digits (e.g., "abc123def"). If you want the entire string to consist of exactly three digits, use "^\\d{3}$".

Combining with Other String Keywords

You can use pattern alongside minLength, maxLength, and format. All constraints must be satisfied simultaneously:

{
  "type": "string",
  "minLength": 7,
  "maxLength": 16,
  "pattern": "^\\+[1-9]\\d+$"
}

This provides defense in depth — the pattern checks structure, while length keywords prevent unexpectedly short or long inputs.