Jambo - JSON Schema to Pydantic Converter

Swiss AI Hub fork. This is a fork of jambo (MIT, by Vitor Hideyoshi) published as swiss-ai-hub-jambo and imported as swiss_ai_hub.jambo. It adds binary and file-path string-format support on top of upstream. The API is otherwise identical — the upstream docs apply.

Jambo is a Python package that automatically converts JSON Schema definitions into Pydantic models. It's designed to streamline schema validation and enforce type safety using Pydantic's validation features.

Created to simplify the process of dynamically generating Pydantic models for AI frameworks like LangChain, CrewAI, and others.

✨ Features

• ✅ Convert JSON Schema into Pydantic models dynamically;
• 🔒 Supports validation for:
  • strings
  • integers
  • floats
  • booleans
  • arrays
  • nested objects
  • allOf
  • anyOf
  • oneOf
  • ref
  • enum
  • const
• ⚙️ Enforces constraints like minLength, maxLength, pattern, minimum, maximum, uniqueItems, and more;
• 📦 Zero config — just pass your schema and get a model.

📦 Installation

pip install swiss-ai-hub-jambo

🚀 Usage

There are two ways to build models with Jambo:

1. The original static API: SchemaConverter.build(schema) doesn't persist any reference cache between calls and doesn't require any configuration.
2. The new instance API: use a SchemaConverter() instance and call build_with_cache, which exposes and persists a reference cache and helper methods.

The instance API is useful when you want to reuse generated subtypes, inspect cached models, or share caches between converters; all leveraging namespaces via the $id property in JSON Schema. See the docs for full details: https://jambo.readthedocs.io/en/latest/usage.ref_cache.html

Static (compatibility) example

from swiss_ai_hub.jambo import SchemaConverter

schema = {
    "title": "Person",
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
    },
    "required": ["name"],
}

# Old-style convenience API (kept for compatibility)
Person = SchemaConverter.build(schema)

obj = Person(name="Alice", age=30)
print(obj)

Instance API (recommended for cache control)

from swiss_ai_hub.jambo import SchemaConverter

converter = SchemaConverter()

schema = {
    "title": "Person",
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "address": {"type": "object", "properties": {"street": {"type": "string"}}},
    },
    "required": ["name"],
}

# build_with_cache populates the converter's instance-level ref cache
Person = converter.build_with_cache(schema)

# you can retrieve cached subtypes by name/path
cached_person = converter.get_cached_ref("Person")
# clear the instance cache when needed
converter.clear_ref_cache()

✅ Example Validations

Following are some examples of how to use Jambo to create Pydantic models with various JSON Schema features, but for more information, please refer to the documentation.

Strings with constraints

from swiss_ai_hub.jambo import SchemaConverter


schema = {
    "title": "EmailExample",
    "type": "object",
    "properties": {
        "email": {
            "type": "string",
            "minLength": 5,
            "maxLength": 50,
            "pattern": r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$",
        },
    },
    "required": ["email"],
}

Model = SchemaConverter.build(schema)
obj = Model(email="user@example.com")
print(obj)

Integers with bounds

from swiss_ai_hub.jambo import SchemaConverter


schema = {
    "title": "AgeExample",
    "type": "object",
    "properties": {
        "age": {"type": "integer", "minimum": 0, "maximum": 120}
    },
    "required": ["age"],
}

Model = SchemaConverter.build(schema)
obj = Model(age=25)
print(obj)

Nested Objects

from swiss_ai_hub.jambo import SchemaConverter


schema = {
    "title": "NestedObjectExample",
    "type": "object",
    "properties": {
        "address": {
            "type": "object",
            "properties": {
                "street": {"type": "string"},
                "city": {"type": "string"},
            },
            "required": ["street", "city"],
        }
    },
    "required": ["address"],
}

Model = SchemaConverter.build(schema)
obj = Model(address={"street": "Main St", "city": "Gotham"})
print(obj)

References

from swiss_ai_hub.jambo import SchemaConverter


schema = {
    "title": "person",
    "$ref": "#/$defs/person",
    "$defs": {
        "person": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"},
                "emergency_contact": {
                    "$ref": "#/$defs/person",
                },
            },
        }
    },
}

model = SchemaConverter.build(schema)

obj = model(
    name="John",
    age=30,
    emergency_contact=model(
        name="Jane",
        age=28,
    ),
)

🧪 Running Tests

To run the test suite:

poe tests

Or manually:

python -m unittest discover -s tests -v

🛠 Development Setup

To set up the project locally:

1. Clone the repository
2. Install uv (if not already installed)
3. Install dependencies:

uv sync

4. Set up git hooks:

poe create-hooks

📌 Roadmap / TODO

• Better error reporting for unsupported schema types

🤝 Contributing

PRs are welcome! This project uses MIT for licensing, so feel free to fork and modify as you see fit.

🧾 License

MIT License.