vtjson

vtjson is an easy to use validation library compatible with Python type annotations.

Introduction

Here is a simple schema:

book_schema = {
    "title": str,
    "authors": [str, ...],
    "editor?": str,
    "year": int,
}

The following conventions were used:

As in typescript, a (string) key ending in ? represents an optional key. The corresponding schema (the item the key points to) will only be used for validation when the key is present in the object that should be validated. A key can also be made optional by wrapping it with optional_key.
If in a list/tuple the last entry is ... (ellipsis) it means that the next to last entry will be repeated zero or more times. In this way generic types can be created. For example the schema [str, ...] represents a list of strings.

Let's try to validate some book objects:

good_book = {
    "title": "Gone with the Wind",
    "authors": ["Margaret Mitchell"],
    "year": 1936,
}

bad_book = {
    "title": "Gone with the Wind",
    "authors": ["Margaret Mitchell"],
    "year": "1936",
}

validate(book_schema, good_book, name="good_book")
validate(book_schema, bad_book, name="bad_book")

As expected vtjson throws an exception for the second object:

Traceback (most recent call last):
          ...
    raise ValidationError(message)
vtjson.vtjson.ValidationError: bad_book['year'] (value:'1936') is not of type 'int'

We may also rewrite the book_schema as a valid Python type annotation.

class book_schema(TypedDict):
    title: str
    authors: list[str]
    editor: NotRequired[str]
    year: int

Attempting to validate the bad book would raise a similar exception as before.

Schemas can of course be more complicated and in particular they can be nested. Here is an example that shows more of the features of vtjson.

person_schema = {
    "name": regex("[a-zA-Z. ]*"),
    "email?": email,
    "website?": url,
}

book_schema = {
    "title": str,
    "authors": [person_schema, ...],
    "editor?": person_schema,
    "year": intersect(int, ge(1900)),
}

Let's try to validate an object not fitting the schema.

bad_book = {
    "title": "Gone with the Wind",
    "authors": [{"name": "Margaret Mitchell", "email": "margaret@gmailcom"}],
    "year": "1936",
}

Traceback (most recent call last):
          ...
    raise ValidationError(message)
vtjson.vtjson.ValidationError: bad_book['authors'][0]['email'] (value:'margaret@gmailcom') is not of type 'email': The part after the @-sign is not valid. It should have a period.

As before we can rewrite the new book_schema as a valid type annotation.

class person_schema(TypedDict):
    name: Annotated[str, regex("[a-zA-Z. ]*")]
    email: NotRequired[Annotated[str, email]]
    website: NotRequired[Annotated[str, url]]

class book_schema(TypedDict):
    title: str
    authors: list[person_schema]
    editor: NotRequired[person_schema]
    year: Annotated[int, ge(1900)]

For comprehensive documentation about vtjson see https://www.cantate.be/vtjson (canonical reference) or https://vtjson.readthedocs.io.

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Release files for vtjson 2.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vtjson 2.3.0
File	Size	Uploaded
vtjson-2.3.0.tar.gz	28.4 kB	Apr 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vtjson 2.3.0
File	Interpreter	ABI	Platform	Reset
vtjson-2.3.0-py3-none-any.whl 19.2 kB Apr 6, 2026	Python 3	none	any	Details

Total release size: 47.7 kB

Release files / vtjson-2.3.0.tar.gz

Download URL	vtjson-2.3.0.tar.gz
Size	28.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`4187e68c88356bfc0084ee9dba0414d554afe3f085b81e5eb8905740135901ad`
BLAKE2b-256 checksum How to use checksums	`abf7cb626e8cc88fb9121d43f798728f28d652ffdb2caefce2213755620140c0`
Upload date	Apr 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.12.3`

Release files / vtjson-2.3.0-py3-none-any.whl

Download URL	vtjson-2.3.0-py3-none-any.whl
Size	19.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2d8753ac931fc515557f88eafce372f2ad7e408e116868211ff99af094b289b7`
BLAKE2b-256 checksum How to use checksums	`ae4353801d8069e2eddc0e200779bb260e6071db230472150c8514c881e30e18`
Upload date	Apr 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.12.3`