jsonobject

library2.3.1pypypi✓ verified 85d ago

jsonobject is a Python library for handling deeply nested JSON objects as well-schema'd Python objects. It provides a declarative way to define data models for JSON structures, facilitating easy serialization and deserialization between Python objects and JSON. Maintained by Dimagi, it is currently at version 2.3.1 and typically follows an active release cadence.

serialization data

pip install jsonobject

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSONOBJECT

jsonobject

serializationpythonv2.3.1

Install

1.7s avg

Import

39ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.3.1 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.041s · 26.4MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.7s · import 0.038s · 29MB

26MB installed

● package 26MB

Code

Verified usage

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

JsonObject

✓ from jsonobject import JsonObject

StringProperty

✓ from jsonobject import StringProperty

IntegerProperty

✓ from jsonobject import IntegerProperty

BooleanProperty

✓ from jsonobject import BooleanProperty

DateTimeProperty

✓ from jsonobject import DateTimeProperty

ListProperty

✓ from jsonobject import ListProperty

DictProperty

✓ from jsonobject import DictProperty

Define a `JsonObject` subclass with various `Property` types, instantiate objects, and serialize them to JSON. Also demonstrates deserialization from a dictionary.

import datetime from jsonobject import JsonObject, StringProperty, BooleanProperty, DateTimeProperty, ListProperty class User(JsonObject): username = StringProperty(required=True) name = StringProperty() active = BooleanProperty(default=False) date_joined = DateTimeProperty() tags = ListProperty(str) # Create an object user1 = User( name='Jane Doe', username='janedoe', date_joined=datetime.datetime.utcnow(), tags=['developer', 'python'] ) print(f"User object: {user1}") print(f"User to JSON: {user1.to_json()}") # Create from existing JSON json_data = { 'username': 'alice', 'name': 'Alice Smith', 'active': True, 'date_joined': '2023-01-15T10:30:00Z', 'tags': ['tester'] } user2 = User(json_data) print(f"User from JSON: {user2}") print(f"Is user2 active? {user2.active}")

Debug

Known issues

breakingVersion 2.0.0 changed the behavior of `ListProperty` when an iterable is passed as its value type. Previously, it might have raised `BadValueError`; now, it returns a plain Python list. This was considered a fix for unintuitive behavior but could be breaking if previous error handling was relied upon.

fix

Review code that relies on `ListProperty` raising `BadValueError` for iterable value types and adjust expectations for receiving a plain Python list instead.

affects: >=2.0.0

breakingVersion 1.0.0 officially dropped support for Python 2.7, 3.5, and 3.6. Using `jsonobject` 1.0.0 or higher with these Python versions will result in compatibility errors.

fix

Ensure your project runs on Python 3.7 or newer. Upgrade your Python environment or pin `jsonobject<1.0.0` if you must remain on older Python versions (though this is not recommended).

affects: >=1.0.0

gotchaWhen defining `Property` types, be cautious with mutable default values (e.g., `ListProperty(default=[])` or `DictProperty(default={})`). If a mutable object is used as a default, all instances of the `JsonObject` class will share the *same* mutable object, leading to unexpected side effects when one instance modifies it.

fix

Always use a `lambda` or a callable for mutable default values, e.g., `ListProperty(default=list)` or `ListProperty(default=lambda: [])`.

affects: All versions

gotchaThe `jsonobject` library provides schema-driven object mapping for JSON. It is distinct from Python's built-in `json` module, which offers basic JSON encoding/decoding, and also distinct from Java libraries often named `JSONObject`. Avoid confusing their APIs or expecting direct interoperability without explicit conversion.

fix

Be mindful of which library you are using. `jsonobject` offers powerful schema validation and object-oriented access, while the standard `json` module is for raw string-to-dict/list conversion.

affects: All versions

Errors

Common errors & fixes

AttributeError: 'dict' object has no attribute 'some_property'

Attempting to access a property on a standard Python dictionary (`dict`) as if it were a `jsonobject.JsonObject` instance. This occurs when JSON data has been loaded using `json.loads()` or similar, but not wrapped/instantiated as a `JsonObject`.

fix

Ensure that your dictionary is correctly passed to the `JsonObject` constructor: `my_object = MyJsonObject(my_dict_data)`.

jsonobject.exceptions.BadValueError: Expected type <ExpectedType>, got <ActualType>

A value assigned to a `Property` or provided during `JsonObject` instantiation does not match the expected type defined in the schema (e.g., providing a string to an `IntegerProperty`).

fix

Check the schema definition for the property (`e.g., IntegerProperty()`) and ensure the data being assigned or provided conforms to that type. Explicitly convert data types if necessary before assignment.

json.decoder.JSONDecodeError: Expecting value: line X column Y (char Z)

The input string provided to `JsonObject` constructor (or `json.loads` if you're manually parsing) is not valid JSON. This can be due to missing quotes, unescaped characters, trailing commas, or incorrect bracket/brace balancing.

fix

Validate your JSON string using a linter or online tool before passing it to `jsonobject`. Common fixes include ensuring all keys and string values use double quotes, no trailing commas, and balanced brackets/braces.

TypeError: 'PropertyName' object is not subscriptable

Attempting to access an attribute of a `JsonObject` (which is a `Property` object) using square brackets (`[]`) as if it were a dictionary or list, when it is not. For example, trying `user.username[0]` for a `StringProperty`.

fix

Access `Property` values directly as attributes (e.g., `user.username`). If the property is indeed a list or dict (`ListProperty`, `DictProperty`), then subscripting is valid for its *value*, but not the `Property` object itself.

Upgrade

Version history

2.3.1latest on PyPI · released Feb 27, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/dimagi/jsonobject ↗

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

homepagehttps://www.dimagi.com/ ↗