How to validate JSON schemas in bulk with the AJV CLI
Learn how to ensure data integrity by validating configuration files against JSON schemas automatically and efficiently using the AJV CLI.
Summary
- Validating JSON files before ingestion prevents critical backend application errors.
- AJV is the fastest and most popular tool for checking if data follows a predefined structure.
- The AJV command-line interface allows processing hundreds of files in seconds.
- Using strict schemas acts as a data contract between different microservices.
- Automating this task in CI pipelines reduces the need for manual checks in production.
Why validate your JSON files?
When managing backend systems, the ingestion of malformed data is one of the most common sources of incidents. If a configuration file sent to the server does not follow the expected structure, your application may crash silently or, worse, process corrupted data. The JSON (JavaScript Object Notation) format, while flexible, lacks native type checking, which forces us to use validation tools.
Validating data at the source is what we call 'defensive programming'. Even before touching the database, we confirm that all mandatory fields are present and data types are correct. Just as we free up blocked ports with fuser to avoid conflicts, we need to ensure that the data flow is clean to maintain system stability.
The role of AJV in automation
AJV (Another JSON Schema Validator) is widely recognized as the most efficient validation library for the Node.js ecosystem. It works by comparing your JSON files against a 'JSON Schema', which is essentially a rule file defining what valid data looks like (e.g., which field is required or the format of a string).
The great advantage of AJV is its Command Line Interface (CLI). Instead of writing a complex script in every project to read directories and validate files, the ajv-cli package solves this with a single command. This is perfect for inclusion in pre-commit hooks or CI/CD pipelines, ensuring no invalid file reaches your cluster.
How to install and configure validation
Installation is straightforward via npm. I always recommend installing it globally to facilitate access in any project directory or as a development dependency in your package.json. For those who work with data manipulation, this tool is as useful as knowing how to convert JSON to CSV in the terminal for quick analysis.
- Install AJV globally:
npm install -g ajv-cli ajv-formats. - Create your schema file (e.g.,
schema.json) defining the field rules. - Run the bulk validation pointing the schema to the files folder:
ajv validate -s schema.json -d 'config/*.json'.
Practical tips for daily use
When working with bulk validation, a common challenge is handling specific formats like dates or URIs. The ajv-formats package is an essential add-on that teaches AJV how to validate these standard internet formats. Without it, the validator will treat a date as a generic string, without checking if the format is correct.
Another important practice is to organize your schemas by version. If your system evolves, your schemas should too. Maintaining semantic versioning allows you to validate legacy files with old schemas and new files with stricter rules, preventing an update from breaking your entire data ingestion automation in production.
Conclusion: integrity as a standard
Adopting automatic validation via the AJV CLI is not just an engineering luxury, but a necessity for systems that require high availability. By treating every configuration file as a contract, we eliminate ambiguity and ensure that the backend processes only what it can safely interpret.
Automation is the path to reducing human error. The next time you need to validate a batch of configurations, don't waste time writing custom scripts; use consolidated command-line tools and focus on your business logic, not on verifying JSON keys.