This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

GenSON

GenSON is a powerful, user-friendly JSON Schema generator built in Python.

(Note: This is not to be confused with the Java Genson library. If you are coming from Java and looking for a Python equivalent, this is not it. You should instead look into Python’s builtin json library.)

Its power comes from the ability to generate a single schema from multiple objects. You can also throw existing schemas into the mix. Basically, you can feed it as many schemas and objects as you want and it will spit out one, unified schema for them all.

The generator follows these three rules:

  1. Every object it is given must validate under the generated schema.
  2. Any object that is valid under any schema it is given must also validate under the generated schema.
  3. The generated schema should be as strict as possible given the first 2 rules.

JSON Schema Implementation

GenSON is a Draft 4 generator.

It is important to note that the generator uses only a small subset of JSON Schema’s capabilities. This is mainly because the generator doesn’t know the specifics of your data model, and it doesn’t try to guess them. Its purpose is to generate the basic structure so that you can skip the boilerplate and focus on the details of the schema.

This means that headers and most keywords aren’t dealt with. Specifically, the generator only deals with 4 keywords: "type", "items", "properties" and "required". You should be aware that this limited vocabulary could cause the generator to violate rules 1 and 2. If you feed it schemas with advanced keywords, it will just blindly pass them on to the final schema.

CLI Tool

The package includes a genson executable that allows you to access this functionality from the command line. For usage info, run with --help:

$ genson --help
usage: genson [-h] [-a] [-d DELIM] [-i SPACES] [-s SCHEMA] ...

Generate one, unified JSON Schema from one or more JSON objects and/or JSON
Schemas. (uses Draft 4 - http://json-schema.org/draft-04/schema)

positional arguments:
  object                files containing JSON objects (defaults to stdin if no
                        arguments are passed and the -s option is not present)

optional arguments:
  -h, --help            show this help message and exit
  -a, --no-merge-arrays
                        generate a different subschema for each element in an
                        array rather than merging them all into one
  -d DELIM, --delimiter DELIM
                        set a delimiter - Use this option if the input files
                        contain multiple JSON objects/schemas. You can pass
                        any string. A few cases ('newline', 'tab', 'space')
                        will get converted to a whitespace character, and if
                        empty string ('') is passed, the parser will try to
                        auto-detect where the boundary is.
  -i SPACES, --indent SPACES
                        pretty-print the output, indenting SPACES spaces
  -s SCHEMA, --schema SCHEMA
                        file containing a JSON Schema (can be specified
                        mutliple times to merge schemas)

GenSON Python API

Schema is the basic schema generator class. Schema objects can be loaded up with existing schemas and objects before being serialized.

import genson

s = genson.Schema()
s.add_schema({"type": "object", "properties": {}})
s.add_object({"hi": "there"})
s.add_object({"hi": 5})

s.to_dict()
#=> {"type": "object", "properties": {"hi": {"type": ["integer", "string"]}}}

s.to_json()
#=> "{\"type\": \"object\", \"properties\": {\"hi\": {\"type\": [\"integer\", \"string\"]}}}"

Schema Object Methods

Schema(merge_arrays=True)

Builds a schema generator object.

arguments:

  • merge_arrays (default True): Assume all array items share the same schema (as they should). The alternate behavior is to merge schemas based on position in the array.
add_schema(schema)

Merges in an existing schema. Take care here because there is no schema validation. If you pass in a bad schema, you’ll get back a bad schema.

arguments:

  • schema (required - dict or Schema): an existing JSON Schema to merge.
add_object(obj)

Modify the schema to accommodate an object.

arguments:

  • obj (required - dict): a JSON object to use in generating the schema.
to_dict()

Convert the current schema to a dict.

to_json()

Convert the current schema directly to serialized JSON.

Schema Object Interaction

Schema objects can also interact with each other:

  • You can pass one schema directly to another to merge them.
  • You can compare schema equality directly.
import genson

s1 = genson.Schema()
s1.add_schema({"type": "object", "properties": {"hi": {"type": "string"}}})

s2 = genson.Schema()
s2.add_schema({"type": "object", "properties": {"hi": {"type": "integer"}}})

s1 == s2
#=> False

s1.add_schema(s2)
s2.add_schema(s1)

s1 == s2
#=> True

s1.to_dict()
#=> {"type": "object", "properties": {"hi": {"type": ["integer", "string"]}}}

Compatibility

GenSON has been tested and verified using the following versions of Python:

  • Python 2.7.11
  • Python 3.3.5
  • Python 3.4.4
  • Python 3.5.1

Contributing

When contributing, please follow these steps:

  1. Clone the repo and make your changes.
  2. Make sure your code has test cases written against it.
  3. Make sure all the tests pass.
  4. Lint your code with Flake8.
  5. Add your name to the list of contributers.
  6. Submit a Pull Request.

Tests

Tests are written in unittest. You can run them all easily with the included executable bin/test.py.

$ bin/test.py

You can also invoke individual test suites:

$ bin/test.py --test-suite test.test_gen_single

History

0.1.0 (2014-11-29)

  • Initial release.

0.2.0

  • Bugfix: Options were not propagated down to subschemas.
  • Bugfix: Empty arrays resulted in invalid schemas because it still included an items property.
  • Bugfix: items was being set to a list even when merge_arrays was set to True. This resulted in overly permissive schemas because items are matched optionally by default.
  • Improvement: Positional Array Matching - In order to be more consistent with the way JSON Schema works, the alternate to merge_arrays is no longer never to merge list items, but instead to merge them based on their position in the list.
  • Improvement: Schema Incompatibility Warning - A schema incompatibility used to cause a fatal error with a nondescript warning. The message has been improved and it has been reduced to a warning.

Credits

GenSON is written and maintained by Jon Wolverton.

Contributors

Release History

Release History

0.2.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
genson-0.2.0.tar.gz (11.7 kB) Copy SHA256 Checksum SHA256 Source Jun 19, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting