API Documentation

class jsonschema_pyref.RefResolver(base_uri: str, referrer: Optional[Union[dict, list, str, int, float, bool]], store: Union[dict, tuple] = (), cache_remote: bool = True, handlers: Union[dict, tuple] = (), urljoin_cache: Optional[Callable[[str, str], str]] = None, remote_cache: Optional[Callable[[str], dict]] = None)[source]

Bases: jsonschema.validators.RefResolver

Drop-in replacement for jsonschema.RefResolver that can resolve py-obj and py-pkgdata URLs.

The easiest way to use it is to initialize it using the from_schema method and pass it as a keyword argument to jsonschema.validate:

>>> import jsonschema
>>> from jsonschema_pyref import RefResolver
>>> schema = {
...     'properties': {
...         'a': {'$ref': 'py-obj:jsonschema_pyref.examples.schema1'}
...     }
... }
>>> resolver = RefResolver.from_schema(schema)
>>> jsonschema.validate({'a': 'hello'}, schema, resolver=resolver) is None
jsonschema_pyref.URL_SCHEME_RESOLVERS = {'py-obj': <function _resolve_url_py_obj>, 'py-pkgdata': <function _resolve_url_py_pkgdata>}

Additional URL handlers for the custom URL schemes supported by this package.

This can be passed to the handlers argument of jsonschema.RefResolver, but take note: It is also necessary to override the urljoin_cache argument to use jsonschema_pyref.urljoin as follows:

>>> import jonschema
>>> from jsonschema_pyref import URL_SCHEME_RESOLVERS, urljoin
>>> from functools import lru_cache
>>> resolver = RefResolver({}, {}, handlers=URL_SCHEME_RESOLVERS,
...                        urljoin_cache=lru_cache(1024)(urljoin))

This boilerplate can be avoided entirely by using the supplied jsonschema_pyref.RefResolver which has these enhancements by default (and is otherwise identical to jsonschema.RefResolver).

exception jsonschema_pyref.ValidationError(message, validator=<unset>, path=(), cause=None, context=(), validator_value=<unset>, instance=<unset>, schema=<unset>, schema_path=(), parent=None)[source]

Bases: jsonschema.exceptions._Error

An instance was invalid under a provided schema.

jsonschema_pyref.urljoin(base: str, url: str, allow_fragments: bool = True) str[source]

Extends the stdlib’s urllib.parse.urljoin to support the custom URL schemes implemented by this package.

The join semantics for py-obj and py-pkgdata URLs differ from those of typical http-like URLs, as well as from each other.

The rules for py-obj are as follows:

  • If joined with a “relative” URL, if the URL starts with a Python identifier, it is simply appended to the current object path:

    >>> from jsonschema_pyref import urljoin
    >>> urljoin('py-obj:a.b.c', 'd.e')
  • However, if the “relative” URL starts with one or more ., it is processed relative to the base path using similar semantics to Python relative imports. That is, one dot means a different attribute of the same object, and so on:

    >>> urljoin('py-obj:a.b.c', '.d')
    >>> urljoin('py-obj:a.b.c', '..d')
    >>> urljoin('py-obj:a.b.c', '..d.e')
  • When joining an absolute URL with the py-obj scheme, the new URL replaces the base:

    >>> urljoin('py-obj:a.b.c', 'py-obj:d.e.f')
  • And likewise when joining an absolute URL with an entirely different scheme:

    >>> urljoin('py-obj:a.b.c', 'https://example.com')
  • Fragments are dropped from the base URL, and retained from the joined URL:

    >>> urljoin('py-obj:a.b.c#replaced', '.d#fragment')
    >>> urljoin('py-obj:a.b.c#replaced', '#fragment')

The rules for py-pkgdata are as follows:

  • If joined to a relative URL, it is treated as a different file relative to the same package/directory as the base URL, very similarly to how urllib.parse.urljoin works for relative paths joined to http(s) URLs:

    >>> urljoin('py-pkgdata:a.b.c/schema1.json', 'schema2.json')
    >>> urljoin('py-pkgdata:a.b.c/schemas/schema1.json', 'schema2.json')
    >>> urljoin('py-pkgdata:a.b.c/schemas/sub/schema1.json', 'schema2.json')
    >>> urljoin('py-pkgdata:a.b.c/schemas/schema1.json', '../more_schemas/schema2.json')


    This does not support relative URLs with a package-relative component, only different paths within the same package. Maybe support for this could be added in the future, but under the current format it’s too ambiguous.

  • When joining an absolute URL, if the joined URL is in the same package it works the same as the relative case (effectively the joined URL replaces the base):

    >>> urljoin('py-pkgdata:a.b.c/schema1.json', 'py-pkgdata:a.b.c/schema2.json')
  • Likewise when they are different packages:

    >>> urljoin('py-pkgdata:a.b.c/schema1.json', 'py-pkgdata:d.e.f/schema2.json')
  • Or if they are the exact same URL, that URL is returned:

    >>> urljoin('py-pkgdata:a.b.c/sub/schema1.json', 'py-pkgdata:a.b.c/sub/schema1.json')
  • And likewise if they are not the same scheme at all:

    >>> urljoin('py-pkgdata:a.b.c/schema1.json', 'http://example.com/schema2.json')
  • The same rules apply for fragments as with py-obj:

    >>> urljoin('py-pkgdata:a.b.c/schema1.json#replaced', 'schema2.json#fragment')
    >>> urljoin('py-pkgdata:a.b.c/schema1.json#replaced', '#fragment')
jsonschema_pyref.urlparse(url: str) urllib.parse.ParseResult[source]

Extends the stdlib’s urllib.parse.urlparse to support the custom URL schemes implemented by this package.

jsonschema_pyref.validate(document: Optional[Union[dict, list, str, int, float, bool]], schema: Union[dict, bool], cls: Optional[Type] = None, *args: Any, **kwargs: Any)[source]

Drop-in replacement for jsonschema.validate which uses the customized jsonschema_pyref.RefResolver by default.

>>> from jsonschema_pyref import validate
>>> schema = {
...     'properties': {
...         'a': {'$ref': 'py-obj:jsonschema_pyref.examples.schema1'}
...     }
... }
>>> validate({'a': 'hello'}, schema) is None