# 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; 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 ```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.