Skip to main content

Python dict-like object which abstracts resolution of JSONSchema references

Project description

Build Status

JSONSchema Ref Dict

Python dict-like object which abstracts resolution of JSONSchema references.

from json_ref_dict import RefDict

schema = RefDict("https://json-schema.org/draft-07/schema#/")

Nested items containing "$ref" will be resolved lazily when accessed, meaning the dictionary can be treating as a single, continuous (and possibly infinite) document.

Remote references are supported, and will be resolved relative to the current document.

If no scheme is provided, it is assumed that the document is present on the local filesystem (see Example below).

If PyYAML is installed, then loading of YAML documents will be supported, otherwise only JSON documents may be loaded.

Example

Given the following related schemas:

master.yaml

definitions:
  foo:
    type: string
  local_ref:
    $ref: '#/definitions/foo'
  remote_ref:
    $ref: 'other.yaml#/definitions/bar'
  backref:
    $ref: 'other.yaml#/definitions/baz'

other.yaml

definitions:
  bar:
    type: integer
  baz:
    $ref: 'master.yaml#/definitions/foo'

We can parse these as a single object as follows:

from json_ref_dict import RefDict

schema = RefDict("master.yaml#/definitions")
print(schema)
>>> {'foo': {'type': 'string'}, 'local_ref': {'$ref': '#/definitions/foo'}, 'remote_ref': {'$ref': 'other.yaml#/definitions/bar'}, 'backref': {'$ref': 'other.yaml#/definitions/baz'}}

print(schema["local_ref"])
>>> {'type': 'string'}

print(schema["remote_ref"])
>>> {'type': 'integer'}

print(schema["backref"])
>>> {'type': 'string'}

Materializing documents

If you don't want the lazy behaviour, and want to get all of the IO out of the way up front, then you can "materialize" the dictionary:

from json_ref_dict import materialize, RefDict

schema = materialize(RefDict("https://json-schema.org/draft-04/schema#/"))
assert isinstance(schema, dict)

A materialized RefDict is just a regular dict, containing a document with all references resolved. This is useful if, for example, you want to cache/persist the entire schema. Be aware that if there are cyclical references in the schema, these will be present on the materialized dictionary.

The materialize helper also supports some basic transformation options, as performing global transformations on infinite documents is non-trivial:

  • include_keys - an iterable of keys to include in the materialized document.
  • exclude_keys - an iterable of keys to exclude from the materialized document.
  • value_map - an operation to apply to the values of the document (not lists or dictionaries).

Requirements

This package is currently tested for Python 3.6.

Installation

This project may be installed using pip:

pip install json-ref-dict

Development

  1. Clone the repository: git clone git@github.com:jacksmith15/json-ref-dict.git && cd json-ref-dict
  2. Install the requirements: pip install -r requirements.txt -r requirements-test.txt
  3. Run pre-commit install
  4. Run the tests: bash run_test.sh -c -a

This project uses the following QA tools:

  • PyTest - for running unit tests.
  • PyLint - for enforcing code style.
  • MyPy - for static type checking.
  • Travis CI - for continuous integration.
  • Black - for uniform code formatting.

License

This project is distributed under the MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

json-ref-dict-0.7.2.tar.gz (19.7 kB view details)

Uploaded Source

Built Distribution

json_ref_dict-0.7.2-py3-none-any.whl (13.2 kB view details)

Uploaded Python 3

File details

Details for the file json-ref-dict-0.7.2.tar.gz.

File metadata

  • Download URL: json-ref-dict-0.7.2.tar.gz
  • Upload date:
  • Size: 19.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for json-ref-dict-0.7.2.tar.gz
Algorithm Hash digest
SHA256 33d327c90a348838b94903402fa452905c284c64033b17d7a94cb5bc767a7518
MD5 cbf7a4bcb6303a660ef855897fa54f2a
BLAKE2b-256 d823ee62caa62e1d7cfbfda5a00ba7766d95324136c1cb20988ea0b2d47779b9

See more details on using hashes here.

File details

Details for the file json_ref_dict-0.7.2-py3-none-any.whl.

File metadata

File hashes

Hashes for json_ref_dict-0.7.2-py3-none-any.whl
Algorithm Hash digest
SHA256 6024c659d999fae5efdc37719e91c5c0c3695fee16c44c2a736fd97f1a4ce4c2
MD5 c1489e1cb5a4bb5c946210cd662b0136
BLAKE2b-256 ccd4bfe0831f412a262a3a921dbdd610cd939af2062ee07f8d5dbb393622ae19

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page