2026-09-27 · 8 min read
- json-schema
- validation
- regex
Some JSON objects are records with fixed fields; others are dictionaries whose property names carry meaning. JSON Schema provides propertyNames to constrain names and patternProperties to apply schemas to values selected by regular expressions.
A reliable dictionary contract must define the name language, value families, overlap behavior, and treatment of names outside those families. These decisions should be visible in fixtures rather than inferred from one permissive example.
Separate name validation from value validation
propertyNames applies a schema to each property name as a string. It can constrain length, format, or pattern, but it does not validate the corresponding value and does not make that value evaluated for additionalProperties.
- Use propertyNames for rules shared by every name.
- Use properties for known exact names.
- Use patternProperties for dynamic value families.
- Define the remaining-value policy explicitly.
Design patterns as a namespace
JSON Schema regular expressions search within a name unless the pattern itself anchors the intended boundary. A pattern such as p matches apple; a prefix namespace normally needs a deliberate expression such as ^p_. Keep expressions within the portable subset supported by every deployed validator.
Treat each pattern as a namespace specification. Document case behavior, separators, Unicode policy, maximum name length, reserved prefixes, and whether user-created names can collide with future platform fields.
Make overlap behavior intentional
Every patternProperties entry whose expression matches a property applies to that property's value. The validator does not select the most specific or first pattern. If two namespaces overlap, the value must satisfy both schemas.
Use overlaps only when intersection is the intended design. Otherwise revise the expressions or factor shared constraints into a base value schema. Test declared properties that also match a pattern because properties does not take precedence.
Choose an extension policy
Set additionalProperties to reject, allow, or validate values not covered by properties and patternProperties. In composed schemas, consider whether unevaluatedProperties better expresses a boundary after successful applicators, but pin the dialect and verify implementation support.
Avoid open-ended dictionaries for authorization, environment variables, headers, or plugin configuration without key normalization and prototype-safe handling in application code. Schema validation does not remove those runtime responsibilities.
Publish a cross-validator matrix
Use Flashman's JSON formatter for schemas and instances, regex tester for public name sets, diff for validator results, YAML/JSON converter for configuration, and case converter for naming-policy examples.
Cover exact and partial matches, empty and long names, Unicode, case variants, reserved prefixes, two-pattern overlaps, fixed fields that match patterns, invalid values, extra names, composition, unsupported regex features, dialect changes, and validator upgrades.