2026-09-23 · 8 min read
- json-schema
- base64
- validation
JSON APIs sometimes carry text, binary files, or nested documents inside strings. JSON Schema's contentEncoding, contentMediaType, and contentSchema keywords can describe that representation, but their operational effect depends on the dialect, vocabulary, validator, and surrounding application.
A robust design separates outer JSON validation, transfer decoding, decoded-size enforcement, media parsing, nested validation, and business authorization. No annotation should silently grant permission to process hostile content.
Write the processing contract first
Specify the accepted encoding names and variants, padding policy, maximum encoded and decoded sizes, media types and parameters, character encoding, decoded schema dialect, and error categories. Decide which checks the schema validator performs and which remain application responsibilities.
- Require type string independently of content keywords.
- Reject ambiguous Base64 and Base64url handling.
- Bound expansion before allocating decoded buffers.
- Allowlist media types needed by the operation.
Pin vocabulary and implementation behavior
Declare $schema and inspect the selected specification's content vocabulary. Confirm whether each validator collects annotations, asserts content correctness, decodes data, evaluates contentSchema, or deliberately leaves those actions to the application.
Run a startup conformance fixture against production validator options. Unknown or unsupported required vocabulary must produce a configuration failure rather than a weaker validation path.
Secure the decoded boundary
Treat decoded bytes as untrusted input. Apply decompression limits, parser depth and entity controls, image or archive safety rules, malware policy, and storage isolation appropriate to the media type. Do not trust a supplied media type to identify actual content.
Avoid returning detailed parser internals to untrusted clients. Use stable validation categories while retaining sanitized diagnostics and correlation identifiers for operators.
Maintain cross-validator fixtures
Use Flashman's JSON formatter for schemas and instances, Base64 tool for public byte fixtures, diff for validator output, hash tool for fixture identity, and YAML converter for configuration copies.
Cover valid and invalid alphabets, padding, whitespace, empty content, Unicode, non-UTF-8 bytes, size boundaries, unknown media types, parameters, malformed decoded documents, contentSchema failure, annotation-only validators, dialect changes, and library upgrades.