genson

library1.4.0pypypi✓ verified 26d ago

GenSON is a powerful, user-friendly JSON Schema generator built in Python. Its core function is to take JSON objects and generate schemas that describe them, and it is unique in its ability to merge schemas. It was originally built to describe the common structure of a large number of JSON objects. The current version is 1.3.0, released on May 15, 2024, and the library is actively maintained.

serialization data

pip install genson

github ↗package ↗

INSTALL

IMPORT

SIG · GENSON

genson

serializationpythonv1.4.0

Install

1.5s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.010s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.010s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SchemaBuilder

✓ from genson import SchemaBuilder

This quickstart demonstrates how to initialize a `SchemaBuilder` and add multiple JSON objects to it. GenSON will automatically infer the common schema, merging types and determining required fields across all added objects. The resulting schema is then printed, prettified with an indent of 2.

from genson import SchemaBuilder import json # Initialize SchemaBuilder builder = SchemaBuilder() # Add the first JSON object builder.add_object({ "name": "Alice Johnson", "email": "alice@example.com", "age": 30, "is_active": True, "tags": ["user", "admin"] }) # Add a second JSON object, demonstrating schema merging builder.add_object({ "name": "Bob Smith", "email": "bob@example.com", "age": 25, "phone": "+1-555-0100", "tags": ["user"] }) # Generate and print the unified JSON Schema schema = builder.to_schema() print(json.dumps(schema, indent=2))

genson --version

Debug

Known issues

gotchaThis `genson` library is *not* the Python equivalent of the Java 'Genson' library. If you are looking for Java's Genson features in Python, this is not the correct library. Consider Python's built-in `json` library for basic JSON handling.

fix

Verify you are using the correct library for your needs. If working with Python JSON Schema generation, proceed. If porting Java Genson logic, look elsewhere.

affects: All versions

gotchaGenSON infers types and marks *all observed fields as required* by default. If a field is present in some objects but not others, it will be made optional in the resulting schema. However, if a field is always present, it will be marked as 'required'.

fix

Manually inspect and adjust the 'required' array in the generated schema if the default inference does not match your intended contract. For example, add `additionalProperties: false` manually if desired.

affects: All versions

gotchaGenSON only deals with a *subset of JSON Schema keywords* for inference (e.g., "$schema", "type", "items", "properties", "patternProperties", "required", "anyOf"). It does not automatically infer or include semantic constraints like `enum` values (unless seeded), `minLength`, `maxLength`, `pattern` for strings, or `minItems`, `maxItems` for arrays.

fix

After generating the basic schema, manually add specific semantic constraints (e.g., `minLength`, `pattern`, `enum`, `description`) to fully describe your data model beyond its basic structure.

affects: All versions

gotchaGenSON uses Python's flavor of regular expressions for `patternProperties`. Be aware of potential differences if you are accustomed to other regex engines. Also, `genson` prefers `properties` over `patternProperties`: if a property already exists that matches one of your patterns, the normal property will be updated, not the pattern property.

fix

Familiarize yourself with Python's regex syntax for `patternProperties`. If using both `properties` and `patternProperties`, be mindful that existing explicit properties will take precedence during updates.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'genson'

The 'genson' library has not been installed in your current Python environment.

fix

Run `pip install genson` in your terminal to install the library.

genson.schema.node.SchemaGenerationError: Could not find matching type for object: datetime.datetime(...)

GenSON does not natively support Python's `datetime.datetime` objects as a distinct JSON Schema type, as JSON itself does not have a native datetime type.

fix

Implement a custom `SchemaStrategy` to handle `datetime` objects, typically by converting them to a string format and optionally adding a 'format': 'date-time' keyword to the schema.

Could not find matching type for schema: {'type': ['null', 'string']}

This error occurs when GenSON struggles to correctly merge or interpret schemas that define a type as a list including 'null' and another type (e.g., string), particularly when inferring types from varied input objects.

fix

Seed the `SchemaBuilder` with an initial schema that explicitly defines `anyOf` or ensures the merged types are handled correctly, or adjust the input data to allow for clearer type inference.

Stack overflow error caused by genson parsing of untrusted JSON String

Parsing deeply nested JSON structures, especially from untrusted sources, can lead to a stack overflow due to recursive processing in earlier versions of GenSON.

fix

Upgrade GenSON to version 1.6 or higher if available (though the specified version is 1.3.0, the issue was identified as pre-1.6). If upgrading is not possible, implement depth limits or use an iterative parsing approach for deeply nested JSON data before feeding it to GenSON, or ensure inputs are not excessively nested.

Upgrade

Version history

1.4.0latest on PyPI · released Jul 6, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/wolverdude/GenSON ↗

packagehttps://pypi.org/project/genson/ ↗