Skip to content

Welcome to Kajson Documentation

Kajson is a powerful drop-in replacement for Python's standard json module that automatically handles complex object serialization, including Pydantic v2 models, datetime objects, and custom types.

Why Kajson?

Say goodbye to type X is not JSON serializable!

The Problem with Standard JSON

import json
from datetime import datetime
from pydantic import BaseModel


class User(BaseModel):
    name: str
    created_at: datetime


user = User(name="Alice", created_at=datetime.now())

# ❌ Standard json fails
json.dumps(user)  # TypeError: Object of type User is not JSON serializable

The Kajson Solution

import kajson

# ✅ Just works!
json_str = kajson.dumps(user)
restored_user = kajson.loads(json_str)
assert user == restored_user  # Perfect reconstruction!

Key Features

  • 🔄 Drop-in replacement - Same API as standard json module
  • 🐍 Pydantic v2 support - Seamless serialization of Pydantic models
  • 📅 DateTime handling - Built-in support for date, time, datetime, timedelta
  • 🏗️ Type preservation - Automatically preserves and reconstructs original types
  • 🔌 Extensible - Easy registration of custom encoders/decoders
  • 🎁 Batteries included - Common types work out of the box

Installation

pip install kajson

poetry add kajson

uv pip install kajson

Basic Example

from datetime import datetime, timedelta
from pydantic import BaseModel
import kajson


class Task(BaseModel):
    name: str
    created_at: datetime
    duration: timedelta


# Create and serialize
task = Task(name="Write documentation", created_at=datetime.now(), duration=timedelta(hours=2))

json_str = kajson.dumps(task, indent=2)
print(json_str)

# Deserialize back
restored_task = kajson.loads(json_str)
assert task == restored_task

Used by Pipelex

This library is used by Pipelex, the reference runtime for MTHDS, the open standard for AI methods. Pipelex lets you build AI methods with your coding agent and run them anywhere — from your agent or your chatbot via MCP, as a webapp, or via API in any software.

License

Kajson is distributed under the Apache 2.0 License.

This project is based on the excellent work from unijson by Bastien Pietropaoli.