2026-09-25 · 8 min read
- json-schema
- validation
- architecture
The JSON Schema format keyword labels strings that follow recognizable syntaxes such as date-time, email, hostname, URI, IP address, and UUID. Modern dialects distinguish collecting that information as an annotation from asserting that the instance conforms.
A portable validation design cannot assume that recognizing format means rejecting invalid values. The schema dialect, declared vocabularies, validator configuration, optional checker packages, and application policy determine the effective behavior.
Choose assertion policy explicitly
Document whether format is informative, enforced by the schema validator, or enforced later by an application parser. Pin the $schema URI and validator options so development, CI, gateways, and production do not accidentally apply different policies.
- Use annotation mode when consumers need descriptive metadata.
- Enable assertions only with tested checker support.
- Reject unsupported required vocabularies at startup.
- Do not infer behavior from editor highlighting.
Separate standard syntax from business rules
A valid date-time can still violate a product rule requiring UTC, minute precision, or a restricted year range. A syntactically valid email address does not prove deliverability, ownership, or account eligibility. Keep those requirements in named schema constraints or explicit application validation.
Avoid custom formats that perform network access, database lookups, authorization, or mutation. Validation should be deterministic, bounded, and safe for untrusted documents.
Specify custom formats conservatively
If a domain syntax genuinely needs a custom format, define its grammar, Unicode and case behavior, length limits, error model, and versioning. Register the same implementation under controlled configuration in every required language.
Decide what older consumers do when they encounter the name. An unknown format commonly does not fail validation, so a format alone is a poor migration gate for a new mandatory invariant.
Test semantic boundaries
Build tables of valid, invalid, and deliberately ambiguous examples. Include calendar boundaries, fractional seconds, timezone offsets, internationalized names, malformed Unicode, trailing whitespace, normalization differences, and values designed to stress parsers.
Compare final validity across implementations before comparing error messages. Where a format delegates to platform libraries, test every runtime and version used in production.
Maintain a conformance matrix
Use Flashman's JSON formatter for schemas and fixtures, regex tester for public pattern experiments, timestamp converter for calendar cases, diff for validator results, and YAML/JSON converter for configuration copies.
Cover annotation and assertion modes, optional plugins, unknown and custom formats, nested dialects, references, generated clients, gateway validation, library upgrades, resource limits, and intentional application-level constraints.