# Jambo - JSON Schema to Pydantic Converter

**Jambo** is a Python package that automatically converts [JSON Schema](https://json-schema.org/) definitions into [Pydantic](https://docs.pydantic.dev/) 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](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), 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 ```bash pip install 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. See the docs for full details: https://jambo.readthedocs.io/en/latest/usage.ref_cache.html > [!NOTE] > The use of the instance API and ref cache can cause schema and type name collisions if not managed carefully, therefore > it's recommended that each namespace or schema source uses its own `SchemaConverter` instance. > If you don't need cache control, the static API is simpler and sufficient for most use cases. ### Static (compatibility) example ```python from 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) ```python from 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](https://jambo.readthedocs.io/). ### Strings with constraints ```python from 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 ```python from 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 ```python from 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 ```python from 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: ```bash poe tests ``` Or manually: ```bash python -m unittest discover -s tests -v ``` --- ## 🛠 Development Setup To set up the project locally: 1. Clone the repository 2. Install [uv](https://github.com/astral-sh/uv) (if not already installed) 3. Install dependencies: ```bash uv sync ``` 4. Set up git hooks: ```bash 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.