# pykwalify
> Python lib/cli for JSON/YAML schema validation
- **URL**: https://www.freshcrate.ai/projects/pykwalify
- **Author**: Johan Andersson
- **Category**: Frameworks
- **Latest version**: `1.8.0` (2026-04-21)
- **License**: MIT
- **Source**: http://github.com/grokzen/pykwalify
- **Language**: Python
- **GitHub**: 299 stars, 86 forks
- **Registry**: pypi (`pykwalify`)
- **Tags**: `pypi`
## Description
# pyKwalify
YAML/JSON validation library
This framework is a port with a lot of added functionality of the Java version of the framework kwalify that can be found at http://www.kuwata-lab.com/kwalify/
The original source code can be found at http://sourceforge.net/projects/kwalify/files/kwalify-java/0.5.1/
The source code of the latest release that has been used can be found at https://github.com/sunaku/kwalify. Please note that source code is not the original authors code but a fork/upload of the last release available in Ruby.
The schema this library is based on and extended from: http://www.kuwata-lab.com/kwalify/ruby/users-guide.01.html#schema
# Usage
Create a data file. `Json` and `Yaml` formats are both supported.
```yaml
- foo
- bar
```
Create a schema file with validation rules.
```yaml
type: seq
sequence:
- type: str
```
Run validation from cli.
```bash
pykwalify -d data.yaml -s schema.yaml
```
## Examples
The documentation describes in detail how each keyword and type works and what is possible in each case.
But there is a lot of real world examples that can be found in the test data/files. It shows a lot of examples of how all keywords and types work in practice and in combination with each other.
The files can be found here and show both schema/data combinations that will work and that will fail.
- `tests/files/success/`
- `tests/files/fail/`
- `tests/files/partial_schemas/`
# YAML parser
`ruamel.yaml` is the default YAMl parser installed with pykwalify.
Ruamel.yaml is more supported in the yaml 1.2 spec and is more actively developed.
Depending on how both libraries are developed, this can change in the future in any major update.
## UTF-8 and data encoding
If you have problems with unicode values not working properly when running pykwalify on Python 3.6x then try to add this environment variable to your execution:
```
PYTHONIOENCODING=UTF-8 pykwalify ...
```
and it might help to force UTF-8 encoding on all string objects. If this does not work please open up an issue with your schema and data that can be used to track down the problem in the source code.
# Project details
| | |
|---|---|
| python support | 3.6, 3.7, 3.8, 3.9 |
| Source | https://github.com/Grokzen/pykwalify |
| Docs (Latest release) | http://pykwalify.readthedocs.io/en/master/ |
| Docs (Unstable branch) | http://pykwalify.readthedocs.io/en/unstable/ |
| Gitter (Free Chat) | [](https://gitter.im/Grokzen/pykwalify?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
| Changelog | https://github.com/Grokzen/pykwalify/blob/unstable/docs/release-notes.rst |
| Upgrade instructions | https://github.com/Grokzen/pykwalify/blob/unstable/docs/upgrade-instructions.rst |
| Issues | https://github.com/Grokzen/pykwalify/issues |
| Travis (master) | [](https://travis-ci.org/Grokzen/pykwalify) https://travis-ci.org/Grokzen/pykwalify |
| Travis (unstable) | [](https://travis-ci.org/Grokzen/pykwalify) https://travis-ci.org/Grokzen/pykwalify |
| Test coverage | [](https://coveralls.io/r/Grokzen/pykwalify) https://coveralls.io/github/Grokzen/pykwalify |
| pypi | https://pypi.python.org/pypi/pykwalify/ |
| Open Hub | https://www.openhub.net/p/pykwalify |
| License | `MIT` https://github.com/Grokzen/pykwalify/blob/unstable/docs/license.rst |
| Copyright | `Copyright (c) 2013-2017 Johan Andersson` |
| git repo | `git clone git@github.com:Grokzen/pykwalify.git` |
| install stable | `pip install pykwalify` |
| install dev | `$ git clone git@github.com:Grokzen/pykwalify.git pykwalify`
`$ cd ./pykwalify`
`$ virtualenv .venv`
`$ source .venv/bin/activate`
`$ pip install -r dev-requirements.txt`
`$ pip install -e .` |
| required dependencies | `docopt >= 0.6.2`
`python-dateutil >= 2.4.2` |
| supported yml parsers | `ruamel.yaml >= 0.11.0` |
## Recent releases
| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `1.8.0` | 2026-04-21 | Low | Imported from PyPI (1.8.0) |
| `1.7.0` | 2018-10-03 | Low | **IMPORTANT** LICENSE UPDATE **IMPORTANT** - In this release there was a line removed from the license file. It was modified in the following commit (cc4e31b39ff4cce2dfbc662baa6469470dd3c033 Wed Oct 3 16:20:59 2018 +0200) and will be the main reason for the 1.7.0 release. All commits and tags and releases (1.6.1 and all releases before it) prior to this commit will use the old license that includes the change done in the above mentioned commit. Only release 1.7.0 and commits past |
| `1.6.1` | 2018-03-13 | Low | New keywords: - Added support for keyword *nullable*. It is now possible to allow for a key not to be empty, when *required* keyword is not used. - Added support for keyword *class*. It will not cause any validation errors, but serves to make kwalify schemas compatible that uses that keywork. Bug fixes: - Improved compatibility with unicodes to validate as strings. Changed behaviour: - Propergate json and yaml loading errors when used from the cli to the user for easier debugging |
| `1.6.0` | 2017-01-22 | Low | New keywords: - Add support for keyword _example_. It does nothing and have no validation done on it. - Add support for keyword _version_. It does nothing and have no validation done on it. - Add support for keyword _date_ and added support keyword _format_. This can be used to validate many different types of _datetime_ objects. - Add support for keyword _length_. It is very similar to _range_ but works primarily string types. - Add support for keyword _assert_. It works by running the python c |
| `1.5.2` | 2016-11-12 | Low | - Convert all documentation to readthedocs - True/False is no longer considered valid integer - python3 'bytes' objects is now a valid strings and text type - The regular PyYaml support is now deprecated in favor of ruamel.yaml, see the following link for more details about PyYaml being deprecated https://bitbucket.org/xi/pyyaml/issues/59/has-this-project-been-abandoned PyYaml will still be possible to use in the next major release version (1.6.0) but removed in release (1.7.0) and forward. |
| `1.5.1` | 2016-03-06 | Low | - Improvements to documentation (scottclowe). - Improved code linting by reworking private variables in Rule class to now be properties and updated all code that used the old way. - Improved code linting by reworking all Log messages to render according to pep standard. (By using %s and passing in variables as positional arguments) - Fix bug when validating sequence and value should only be unicode escaped when a string - Improve validation of timestamps. - Improve float validation to now ac |
| `1.5.0` | 2015-09-30 | Low | - float / number type now support range restrictions - ranges on non number types (e.g. seq, string) now need to be non negative. - Fixed encoding bug triggered when both regex matching-rule 'any' and 'all' found keyword that failed regex match. Added failure unit tests to cover regex matching-rule 'any' and 'all' during failed regex match. Updated allowed rule list to include matching-rule 'all'. - Changed _validate_mappings method from using re.match to re.search. This fixes bug related |
| `1.4.1` | 2015-08-31 | Low | - Added tests to sdist to enable downstream packaging to run tests. No code changes in this release. |
| `1.4.0` | 2015-08-04 | Low | - Dropped support for python 3.2 becuase of unicode literals do not exists in python 3.2. - Fixed logging & raised exceptions when using unicode characters inside schemas/data/filenames. - Reworked all RuleError exceptions to now have better exception messages. - RuleError exceptions now have a unique 'error_key' that can make it easier to identify what error it is. - Paths for RuleErrors have been moved inside the exception as a variable. - Rewrote all SchemaConflict exceptions to be more human |
| `1.3.0` | 2015-07-13 | Low | - Rewrote most of the error messages to be more human readable. See `docs/Upgrade Instructions.md` for more details. - It is now possible to use the exceptions that was raised for each validation error. It can be found in the variable `c.validation_errors_exceptions`. They contain more detailed information about the error. |
## Citation
- HTML: https://www.freshcrate.ai/projects/pykwalify
- Markdown: https://www.freshcrate.ai/projects/pykwalify.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/pykwalify/deps
_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._