Merge pull request #78 from mikix/model-desc

feat: support object-level descriptions

.githooks/pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
     - repo: https://github.com/astral-sh/ruff-pre-commit
         # Ruff version.
-      rev: v0.11.4
+      rev: v0.14.7
       hooks:
           # Run the linter.
           - id: ruff

.github/ISSUE_TEMPLATE/bug_report.md

@@ -2,7 +2,7 @@
 name: Bug report
 about: Create a report to help us improve
 title: "[BUG] Title Here"
-labels: enhancement
+labels: bug
 assignees: HideyoshiNakazone
 
 ---

.github/workflows/build.yml

@@ -23,6 +23,7 @@ jobs:
           - "3.11"
           - "3.12"
           - "3.13"
+          - "3.14"
 
     steps:
       - uses: actions/checkout@v4
@@ -31,7 +32,7 @@ jobs:
         uses: astral-sh/setup-uv@v5
         with:
           # Install a specific version of uv.
-          version: "0.6.14"
+          version: "0.9.15"
           enable-cache: true
           cache-dependency-glob: "uv.lock"
           python-version: ${{ matrix.python-version }}
@@ -44,6 +45,9 @@ jobs:
           uv run poe tests
           uv run poe tests-report
 
+      - name: Static type check
+        run: uv run poe type-check
+
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
         with:
@@ -65,7 +69,7 @@ jobs:
         uses: astral-sh/setup-uv@v5
         with:
           # Install a specific version of uv.
-          version: "0.6.14"
+          version: "0.9.15"
           enable-cache: true
           cache-dependency-glob: "uv.lock"
 

.python-version

@@ -0,0 +1 @@
+3.14

README.md

@@ -1,8 +1,8 @@
 # Jambo - JSON Schema to Pydantic Converter
 
-<p align="center">
+<p style="text-align:center">
 <a href="https://github.com/HideyoshiNakazone/jambo" target="_blank">
- <img src="https://img.shields.io/github/last-commit/HideyoshiNakazone/jambo.svg">
+ <img src="https://img.shields.io/github/last-commit/HideyoshiNakazone/jambo.svg" alt="Last commit">
  <img src="https://github.com/HideyoshiNakazone/jambo/actions/workflows/build.yml/badge.svg" alt="Tests">
 </a>
 <a href="https://codecov.io/gh/HideyoshiNakazone/jambo" target="_blank">
@@ -19,12 +19,13 @@
 </p>
 
 **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 powerful validation features.
+It's designed to streamline schema validation and enforce type safety using Pydantic's validation features.
 
-Created to simplifying the process of dynamically generating Pydantic models for AI frameworks like [LangChain](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), and others.
+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;
@@ -37,6 +38,7 @@ Created to simplifying the process of dynamically generating Pydantic models for
     - nested objects
     - allOf
     - anyOf
+    - oneOf
     - ref
     - enum
     - const
@@ -55,10 +57,19 @@ 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",
@@ -69,12 +80,40 @@ schema = {
     "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

docs/source/conf.py

@@ -18,6 +18,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",  # <-- needed
 ]
 
 
@@ -35,3 +36,6 @@ html_static_path = ["_static"]
 # -- Options for autodoc -----------------------------------------------------
 add_module_names = False
 python_use_unqualified_type_names = True
+
+
+autodoc_typehints = "both"

docs/source/jambo.exceptions.rst

@@ -0,0 +1,37 @@
+jambo.exceptions package
+========================
+
+Submodules
+----------
+
+jambo.exceptions.internal\_assertion\_exception module
+------------------------------------------------------
+
+.. automodule:: jambo.exceptions.internal_assertion_exception
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+jambo.exceptions.invalid\_schema\_exception module
+--------------------------------------------------
+
+.. automodule:: jambo.exceptions.invalid_schema_exception
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+jambo.exceptions.unsupported\_schema\_exception module
+------------------------------------------------------
+
+.. automodule:: jambo.exceptions.unsupported_schema_exception
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: jambo.exceptions
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/source/jambo.parser.rst

@@ -36,6 +36,22 @@ jambo.parser.boolean\_type\_parser module
    :show-inheritance:
    :undoc-members:
 
+jambo.parser.const\_type\_parser module
+---------------------------------------
+
+.. automodule:: jambo.parser.const_type_parser
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+jambo.parser.enum\_type\_parser module
+--------------------------------------
+
+.. automodule:: jambo.parser.enum_type_parser
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 jambo.parser.float\_type\_parser module
 ---------------------------------------
 
@@ -52,6 +68,14 @@ jambo.parser.int\_type\_parser module
    :show-inheritance:
    :undoc-members:
 
+jambo.parser.null\_type\_parser module
+--------------------------------------
+
+.. automodule:: jambo.parser.null_type_parser
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 jambo.parser.object\_type\_parser module
 ----------------------------------------
 
@@ -60,6 +84,14 @@ jambo.parser.object\_type\_parser module
    :show-inheritance:
    :undoc-members:
 
+jambo.parser.oneof\_type\_parser module
+---------------------------------------
+
+.. automodule:: jambo.parser.oneof_type_parser
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 jambo.parser.ref\_type\_parser module
 -------------------------------------
 

docs/source/jambo.rst

@@ -7,6 +7,7 @@ Subpackages
 .. toctree::
    :maxdepth: 4
 
+   jambo.exceptions
    jambo.parser
    jambo.types
 

docs/source/usage.oneof.rst

@@ -0,0 +1,112 @@
+OneOf Type
+=================
+
+The OneOf type is used to specify that an object must conform to exactly one of the specified schemas. Unlike AnyOf which allows matching multiple schemas, OneOf enforces that the data matches one and only one of the provided schemas.
+
+
+Examples
+-----------------
+
+1. **Overlapping String Example** - A field that accepts strings with overlapping constraints:
+
+.. code-block:: python
+
+    from jambo import SchemaConverter
+
+    schema = {
+        "title": "SimpleExample",
+        "type": "object",
+        "properties": {
+            "value": {
+                "oneOf": [
+                    {"type": "string", "maxLength": 6},
+                    {"type": "string", "minLength": 4}
+                ]
+            }
+        },
+        "required": ["value"]
+    }
+
+    Model = SchemaConverter.build(schema)
+
+    # Valid: Short string (matches first schema only)
+    obj1 = Model(value="hi")
+    print(obj1.value)  # Output: hi
+
+    # Valid: Long string (matches second schema only)
+    obj2 = Model(value="very long string")
+    print(obj2.value)  # Output: very long string
+
+    # Invalid: Medium string (matches BOTH schemas - violates oneOf)
+    try:
+        obj3 = Model(value="hello")  # 5 chars: matches maxLength=6 AND minLength=4
+    except ValueError as e:
+        print("Validation fails as expected:", e)
+
+
+2. **Discriminator Example** - Different shapes with a type field:
+
+.. code-block:: python
+
+    from jambo import SchemaConverter
+
+    schema = {
+        "title": "Shape",
+        "type": "object",
+        "properties": {
+            "shape": {
+                "oneOf": [
+                    {
+                        "type": "object",
+                        "properties": {
+                            "type": {"const": "circle"},
+                            "radius": {"type": "number", "minimum": 0}
+                        },
+                        "required": ["type", "radius"]
+                    },
+                    {
+                        "type": "object",
+                        "properties": {
+                            "type": {"const": "rectangle"},
+                            "width": {"type": "number", "minimum": 0},
+                            "height": {"type": "number", "minimum": 0}
+                        },
+                        "required": ["type", "width", "height"]
+                    }
+                ],
+                "discriminator": {
+                    "propertyName": "type"
+                }
+            }
+        },
+        "required": ["shape"]
+    }
+
+    Model = SchemaConverter.build(schema)
+
+    # Valid: Circle
+    circle = Model(shape={"type": "circle", "radius": 5.0})
+    print(circle.shape.type)  # Output: circle
+
+    # Valid: Rectangle
+    rectangle = Model(shape={"type": "rectangle", "width": 10, "height": 20})
+    print(rectangle.shape.type)  # Output: rectangle
+
+    # Invalid: Wrong properties for the type
+    try:
+        invalid = Model(shape={"type": "circle", "width": 10})
+    except ValueError as e:
+        print("Validation fails as expected:", e)
+
+
+.. note::
+
+    OneOf ensures exactly one schema matches. The discriminator helps Pydantic efficiently determine which schema to use based on a specific property value.
+
+.. warning::
+
+    If your data could match multiple schemas in a oneOf, validation will fail. Ensure schemas are mutually exclusive.
+
+.. warning::
+
+    The discriminator feature is not officially in the JSON Schema specification, it was introduced by OpenAPI. Use it with caution and ensure it fits your use case.

docs/source/usage.ref_cache.rst

@@ -0,0 +1,348 @@
+===============
+Reference Cache
+===============
+
+The reference cache is named after the mechanism used to implement
+the `$ref` keyword in the JSON Schema specification.
+
+Internally, the cache is used by both :py:meth:`SchemaConverter.build_with_cache <jambo.SchemaConverter.build_with_cache>`
+and :py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>`.
+However, only :py:meth:`SchemaConverter.build_with_cache <jambo.SchemaConverter.build_with_cache>` exposes the cache through a supported API;
+:py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>` uses the cache internally and does not provide access to it.
+
+The reference cache accepts a mutable mapping (typically a plain Python dict)
+that maps reference names (strings) to generated Pydantic model classes.
+Since only the reference names are stored it can cause name collisions if
+multiple schemas with overlapping names are processed using the same cache.
+Therefore, it's recommended that each namespace or schema source uses its own
+:class:`SchemaConverter` instance.
+
+-----------------------------------------
+Configuring and Using the Reference Cache
+-----------------------------------------
+
+The reference cache can be used in three ways:
+
+* Without a persistent reference cache (no sharing between calls).
+* Passing an explicit ``ref_cache`` dictionary to a call.
+* Using the converter instance's default cache (the instance-level cache).
+
+
+Usage Without Reference Cache
+=============================
+
+When you run the library without a persistent reference cache, the generated
+types are not stored for reuse. Each call to a build method creates fresh
+Pydantic model classes (they will have different Python object identities).
+Because nothing is cached, you cannot look up generated subtypes later.
+
+This is the default behaviour of :py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>`.
+You can achieve the same behaviour with :py:meth:`SchemaConverter.build_with_cache <jambo.SchemaConverter.build_with_cache>` by
+passing ``without_cache=True``.
+
+
+Usage: Manually Passing a Reference Cache
+=========================================
+
+You can create and pass your own mutable mapping (typically a plain dict)
+as the reference cache. This gives you full control over sharing and
+lifetime of cached types. When two converters share the same dict, types
+created by one converter will be reused by the other.
+
+.. code-block:: python
+
+    from jambo import SchemaConverter
+
+    # a shared cache you control
+    shared_cache = {}
+
+    converter1 = SchemaConverter(shared_cache)
+    converter2 = SchemaConverter(shared_cache)
+
+    model1 = converter1.build_with_cache(schema)
+    model2 = converter2.build_with_cache(schema)
+
+    # Because both converters use the same cache object, the built models are the same object
+    assert model1 is model2
+
+If you prefer a per-call cache (leaving the converter's instance cache unchanged), pass the ``ref_cache`` parameter to
+:py:meth:`SchemaConverter.build_with_cache <jambo.SchemaConverter.build_with_cache>`:
+
+.. code-block:: python
+
+    # pass an explicit, private cache for this call only
+    model_a = converter1.build_with_cache(schema, ref_cache={})
+    model_b = converter1.build_with_cache(schema, ref_cache={})
+
+    # because each call received a fresh dict, the resulting model classes are distinct
+    assert model_a is not model_b
+
+
+Usage: Using the Instance Default (Instance-level) Cache
+=======================================================
+
+By default, a :class:`SchemaConverter` instance creates and keeps an internal
+reference cache (a plain dict). Reusing the same converter instance across
+multiple calls will reuse that cache and therefore reuse previously generated
+model classes.
+
+That cache is isolated per namespace via the `$id` property in JSON Schema, so
+schemas with different `$id` values will not collide in the same cache.
+
+.. code-block:: python
+
+    from jambo import SchemaConverter
+
+    # no $id in this example, therefore a default namespace is used
+    schema = {
+        "title": "Person",
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "age": {"type": "integer"},
+            "address": {
+                "type": "object",
+                "properties": {
+                    "street": {"type": "string"},
+                    "city": {"type": "string"},
+                },
+                "required": ["street", "city"],
+            },
+        },
+        "required": ["name", "address"],
+    }
+
+    converter = SchemaConverter()  # has its own internal cache
+
+    model1 = converter.build_with_cache(schema)
+    model2 = converter.build_with_cache(schema)
+
+    # model1 and model2 are the same object because the instance cache persisted
+    assert model1 is model2
+
+When passing a schema with a different `$id`, the instance cache keeps types
+separate:
+
+.. code-block:: python
+
+    schema_a = {
+        "$id": "namespace_a",
+        "title": "Person",
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+        },
+        "required": ["name"],
+    }
+
+    schema_b = {
+        "$id": "namespace_b",
+        "title": "Person",
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+        },
+        "required": ["name"],
+    }
+
+    converter = SchemaConverter()  # has its own internal cache
+
+    model_a = converter.build_with_cache(schema_a)
+    model_b = converter.build_with_cache(schema_b)
+
+    # different $id values isolate the types in the same cache
+    assert model_a is not model_b
+
+If you want to temporarily avoid using the instance cache for a single call,
+use ``without_cache=True``. That causes :py:meth:`SchemaConverter.build_with_cache <jambo.SchemaConverter.build_with_cache>` to
+use a fresh, empty cache for the duration of that call only:
+
+.. code-block:: python
+
+    model1 = converter.build_with_cache(schema, without_cache=True)
+    model2 = converter.build_with_cache(schema, without_cache=True)
+
+    # each call used a fresh cache, so the models are distinct
+    assert model1 is not model2
+
+
+Inspecting and Managing the Cache
+=================================
+
+The converter provides a small, explicit API to inspect and manage the
+instance cache.
+
+Retrieving cached types
+-----------------------
+
+:py:meth:`SchemaConverter.get_cached_ref <jambo.SchemaConverter.get_cached_ref>`(name, namespace="default") — returns a cached model class or ``None``.
+
+Retrieving the root type of the schema
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When retrieving the root type of a schema, pass the schema's ``title`` property as the name.
+
+.. code-block:: python
+
+    from jambo import SchemaConverter
+
+    converter = SchemaConverter()
+
+    schema = {
+        "title": "person",
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "age": {"type": "integer"},
+        },
+    }
+
+    person_model = converter.build_with_cache(schema)
+    cached_person_model = converter.get_cached_ref("person")
+
+
+Retrieving a subtype
+~~~~~~~~~~~~~~~~~~~~
+
+When retrieving a subtype, pass a path string (for example, ``parent_name.field_name``) as the name.
+
+.. code-block:: 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"},
+                    "city": {"type": "string"},
+                },
+                "required": ["street", "city"],
+            },
+        }
+    }
+
+    person_model = converter.build_with_cache(schema)
+    cached_address_model = converter.get_cached_ref("person.address")
+
+
+
+Retrieving a type from ``$defs``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When retrieving a type defined in ``$defs``, access it directly by its name.
+
+.. code-block:: python
+
+    from jambo import SchemaConverter
+
+    converter = SchemaConverter()
+
+    schema = {
+        "title": "person",
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "age": {"type": "integer"},
+            "address": {"$ref": "#/$defs/address"},
+        },
+        "$defs": {
+            "address": {
+                "type": "object",
+                "properties": {
+                    "street": {"type": "string"},
+                    "city": {"type": "string"},
+                },
+                "required": ["street", "city"],
+            }
+        },
+    }
+
+    person_model = converter.build_with_cache(schema)
+    cached_address_model = converter.get_cached_ref("address")
+
+
+Isolation by Namespace
+~~~~~~~~~~~~~~~~~~~~~~
+
+The instance cache is isolated per namespace via the `$id` property in JSON Schema.
+When retrieving a cached type, you can specify the namespace to look in
+(via the ``namespace`` parameter). By default, the ``default`` namespace is used
+
+
+.. code-block:: python
+
+    from jambo import SchemaConverter
+
+    converter = SchemaConverter()
+
+    schema_a = {
+        "$id": "namespace_a",
+        "title": "Person",
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+        },
+        "required": ["name"],
+    }
+
+    schema_b = {
+        "$id": "namespace_b",
+        "title": "Person",
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+        },
+        "required": ["name"],
+    }
+
+    person_a = converter.build_with_cache(schema_a)
+    person_b = converter.build_with_cache(schema_b)
+
+    cached_person_a = converter.get_cached_ref("Person", namespace="namespace_a")
+    cached_person_b = converter.get_cached_ref("Person", namespace="namespace_b")
+
+    assert cached_person_a is person_a
+    assert cached_person_b is person_b
+
+
+Clearing the cache
+------------------
+
+:py:meth:`SchemaConverter.clear_ref_cache <jambo.SchemaConverter.clear_ref_cache>`(namespace: Optional[str]="default") — removes all entries from the instance cache.
+
+
+When you want to clear the instance cache, use :py:meth:`SchemaConverter.clear_ref_cache <jambo.SchemaConverter.clear_ref_cache>`.
+You can optionally specify a ``namespace`` to clear only that namespace;
+otherwise, the default namespace is cleared.
+
+If you want to clear all namespaces, call :py:meth:`SchemaConverter.clear_ref_cache <jambo.SchemaConverter.clear_ref_cache>` passing `None` as the namespace,
+which removes all entries from all namespaces.
+
+
+Notes and Behavioural Differences
+================================
+
+* :py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>` does not expose or persist an instance cache. If you call it without
+  providing a ``ref_cache`` it will create and use a temporary cache for that
+  call only; nothing from that call will be available later via
+  :py:meth:`SchemaConverter.get_cached_ref <jambo.SchemaConverter.get_cached_ref>`.
+
+* :py:meth:`SchemaConverter.build_with_cache <jambo.SchemaConverter.build_with_cache>` is the supported entry point when you want
+  cache control: it uses the instance cache by default, accepts an explicit
+  ``ref_cache`` dict for per-call control, or uses ``without_cache=True`` to
+  run with an ephemeral cache.
+
+
+References in the Test Suite
+============================
+
+These behaviours are exercised in the project's tests; see :mod:`tests.test_schema_converter`
+for examples and additional usage notes.

docs/source/usage.rst

@@ -1,9 +1,15 @@
+===================
 Using Jambo
 ===================
 
-Jambo is designed to be easy to use, it doesn't require any complex setup or configuration.
-Below a example of how to use Jambo to convert a JSON Schema into a Pydantic model.
+Jambo is designed to be easy to use. It doesn't require complex setup or configuration when not needed, while providing more powerful instance methods when you do need control.
 
+Below is an example of how to use Jambo to convert a JSON Schema into a Pydantic model.
+
+
+-------------------------
+Static Method (no config)
+-------------------------
 
 .. code-block:: python
 
@@ -15,8 +21,16 @@ Below a example of how to use Jambo to convert a JSON Schema into a Pydantic mod
         "properties": {
             "name": {"type": "string"},
             "age": {"type": "integer"},
+            "address": {
+                "type": "object",
+                "properties": {
+                    "street": {"type": "string"},
+                    "city": {"type": "string"},
+                },
+                "required": ["street", "city"],
+            },
         },
-        "required": ["name"],
+        "required": ["name", "address"],
     }
 
     Person = SchemaConverter.build(schema)
@@ -26,16 +40,81 @@ Below a example of how to use Jambo to convert a JSON Schema into a Pydantic mod
     # Output: Person(name='Alice', age=30)
 
 
-The :py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>` static method takes a JSON Schema dictionary and returns a Pydantic model class. You can then instantiate this class with the required fields, and it will automatically validate the data according to the schema.
+The :py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>` static method takes a JSON Schema dictionary and returns a Pydantic model class.
 
-If passed a description inside the schema it will also add it to the Pydantic model using the `description` field. This is useful for AI Frameworks as: LangChain, CrewAI and others, as they use this description for passing context to LLMs.
+Note: the static ``build`` method was the original public API of this library. It creates and returns a model class for the provided schema but does not expose or persist an instance cache.
 
 
-For more complex schemas and types see our documentation on
+--------------------------------
+Instance Method (with ref cache)
+--------------------------------
+
+.. code-block:: 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"},
+                    "city": {"type": "string"},
+                },
+                "required": ["street", "city"],
+            },
+        },
+        "required": ["name", "address"],
+    }
+
+    # The instance API (build_with_cache) populates the converter's instance-level reference cache
+    Person = converter.build_with_cache(schema)
+
+    obj = Person(name="Alice", age=30)
+    print(obj)
+    # Output: Person(name='Alice', age=30)
+
+    # When using the converter's built-in instance cache (no ref_cache passed to the call),
+    # all object types parsed during the build are stored and can be retrieved via get_cached_ref.
+
+    cached_person_model = converter.get_cached_ref("Person")
+    assert Person is cached_person_model  # the cached class is the same object that was built
+
+    # A nested/subobject type can also be retrieved from the instance cache
+    cached_address_model = converter.get_cached_ref("Person.address")
+
+
+The :py:meth:`SchemaConverter.build_with_cache <jambo.SchemaConverter.build_with_cache>` instance method was added after the
+initial static API to make it easier to access and reuse subtypes defined in a schema.
+Unlike the original static :py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>`,
+the instance method persists and exposes the reference cache and provides helpers such as
+:py:meth:`SchemaConverter.get_cached_ref <jambo.SchemaConverter.get_cached_ref>` and
+:py:meth:`SchemaConverter.clear_ref_cache <jambo.SchemaConverter.clear_ref_cache>`.
+
+.. warning::
+    The instance API with reference cache can lead to schema and type name collisions if not managed carefully.
+    It's recommended that each schema defines its own unique namespace using the `$id` property in JSON Schema,
+    and then access it's ref_cache by passing it explicitly when needed.
+    
+For details and examples about the reference cache and the different cache modes (instance cache, per-call cache, ephemeral cache), see:
+
+.. toctree::
+    usage.ref_cache
+
+
+Type System
+-----------
+
+For a full explanation of the supported schemas and types see our documentation on types:
 
 .. toctree::
     :maxdepth: 2
-    :caption: Contents:
 
     usage.string
     usage.numeric
@@ -45,5 +124,6 @@ For more complex schemas and types see our documentation on
     usage.reference
     usage.allof
     usage.anyof
+    usage.oneof
     usage.enum
     usage.const

jambo/exceptions/__init__.py

@@ -0,0 +1,10 @@
+from .internal_assertion_exception import InternalAssertionException
+from .invalid_schema_exception import InvalidSchemaException
+from .unsupported_schema_exception import UnsupportedSchemaException
+
+
+__all__ = [
+    "InternalAssertionException",
+    "InvalidSchemaException",
+    "UnsupportedSchemaException",
+]

jambo/exceptions/internal_assertion_exception.py

@@ -0,0 +1,16 @@
+class InternalAssertionException(RuntimeError):
+    """Exception raised for internal assertions."""
+
+    def __init__(
+        self,
+        message: str,
+    ) -> None:
+        # Normalize message by stripping redundant prefix if present
+        message = message.removeprefix("Internal Assertion Failed: ")
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return (
+            f"Internal Assertion Failed: {super().__str__()}\n"
+            "This is likely a bug in Jambo. Please report it at"
+        )

jambo/exceptions/invalid_schema_exception.py

@@ -0,0 +1,27 @@
+from typing_extensions import Optional
+
+
+class InvalidSchemaException(ValueError):
+    """Exception raised for invalid JSON schemas."""
+
+    def __init__(
+        self,
+        message: str,
+        invalid_field: Optional[str] = None,
+        cause: Optional[BaseException] = None,
+    ) -> None:
+        # Normalize message by stripping redundant prefix if present
+        message = message.removeprefix("Invalid JSON Schema: ")
+        self.invalid_field = invalid_field
+        self.cause = cause
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        base_msg = f"Invalid JSON Schema: {super().__str__()}"
+        if self.invalid_field:
+            return f"{base_msg} (invalid field: {self.invalid_field})"
+        if self.cause:
+            return (
+                f"{base_msg} (caused by {self.cause.__class__.__name__}: {self.cause})"
+            )
+        return base_msg

jambo/exceptions/unsupported_schema_exception.py

@@ -0,0 +1,23 @@
+from typing_extensions import Optional
+
+
+class UnsupportedSchemaException(ValueError):
+    """Exception raised for unsupported JSON schemas."""
+
+    def __init__(
+        self,
+        message: str,
+        unsupported_field: Optional[str] = None,
+        cause: Optional[BaseException] = None,
+    ) -> None:
+        # Normalize message by stripping redundant prefix if present
+        message = message.removeprefix("Unsupported JSON Schema: ")
+        self.unsupported_field = unsupported_field
+        self.cause = cause
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        base_msg = f"Unsupported JSON Schema: {super().__str__()}"
+        if self.unsupported_field:
+            return f"{base_msg} (unsupported field: {self.unsupported_field})"
+        return base_msg

jambo/parser/__init__.py

@@ -7,7 +7,9 @@ from .const_type_parser import ConstTypeParser
 from .enum_type_parser import EnumTypeParser
 from .float_type_parser import FloatTypeParser
 from .int_type_parser import IntTypeParser
+from .null_type_parser import NullTypeParser
 from .object_type_parser import ObjectTypeParser
+from .oneof_type_parser import OneOfTypeParser
 from .ref_type_parser import RefTypeParser
 from .string_type_parser import StringTypeParser
 
@@ -22,7 +24,9 @@ __all__ = [
     "BooleanTypeParser",
     "FloatTypeParser",
     "IntTypeParser",
+    "NullTypeParser",
     "ObjectTypeParser",
+    "OneOfTypeParser",
     "StringTypeParser",
     "RefTypeParser",
 ]

jambo/parser/_type_parser.py

@@ -1,27 +1,31 @@
-from jambo.types.type_parser_options import TypeParserOptions
+from jambo.exceptions import InvalidSchemaException
+from jambo.types.type_parser_options import JSONSchema, TypeParserOptions
 
 from pydantic import Field, TypeAdapter
-from typing_extensions import Annotated, Any, Generic, Self, TypeVar, Unpack
+from typing_extensions import Annotated, Any, ClassVar, Generic, Self, TypeVar, Unpack
 
 from abc import ABC, abstractmethod
 
 
-T = TypeVar("T")
+T = TypeVar("T", bound=type)
 
 
 class GenericTypeParser(ABC, Generic[T]):
-    json_schema_type: str = None
+    json_schema_type: ClassVar[str]
 
     type_mappings: dict[str, str] = {}
 
     default_mappings = {
         "default": "default",
         "description": "description",
+        "examples": "examples",
+        "title": "title",
+        "deprecated": "deprecated",
     }
 
     @abstractmethod
     def from_properties_impl(
-        self, name: str, properties: dict[str, Any], **kwargs: Unpack[TypeParserOptions]
+        self, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
     ) -> tuple[T, dict]:
         """
         Abstract method to convert properties to a type and its fields properties.
@@ -32,7 +36,7 @@ class GenericTypeParser(ABC, Generic[T]):
         """
 
     def from_properties(
-        self, name: str, properties: dict[str, Any], **kwargs: Unpack[TypeParserOptions]
+        self, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
     ) -> tuple[T, dict]:
         """
         Converts properties to a type and its fields properties.
@@ -46,15 +50,20 @@ class GenericTypeParser(ABC, Generic[T]):
         )
 
         if not self._validate_default(parsed_type, parsed_properties):
-            raise ValueError(
-                f"Default value {properties.get('default')} is not valid for type {parsed_type.__name__}"
+            raise InvalidSchemaException(
+                "Default value is not valid", invalid_field=name
+            )
+
+        if not self._validate_examples(parsed_type, parsed_properties):
+            raise InvalidSchemaException(
+                "Examples values are not valid", invalid_field=name
             )
 
         return parsed_type, parsed_properties
 
     @classmethod
     def type_from_properties(
-        cls, name: str, properties: dict[str, Any], **kwargs: Unpack[TypeParserOptions]
+        cls, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
     ) -> tuple[type, dict]:
         """
         Factory method to fetch the appropriate type parser based on properties
@@ -64,22 +73,53 @@ class GenericTypeParser(ABC, Generic[T]):
         :param kwargs: Additional options for type parsing.
         :return: A tuple containing the type and its properties.
         """
-        parser = cls._get_impl(properties)
+
+        parser = cls._get_impl(cls._normalize_properties(properties))
 
         return parser().from_properties(name=name, properties=properties, **kwargs)
 
+    @staticmethod
+    def _normalize_properties(properties: JSONSchema) -> JSONSchema:
+        """
+        Normalizes the properties dictionary to ensure consistent structure.
+        :param properties: The properties to be normalized.
+        """
+        type_value = properties.pop("type", None)
+
+        if isinstance(type_value, str):
+            properties["type"] = type_value
+            return properties
+
+        if isinstance(type_value, list) and len(type_value) == 0:
+            raise InvalidSchemaException(
+                "Invalid schema: 'type' list cannot be empty",
+                invalid_field=str(properties),
+            )
+
+        if isinstance(type_value, list) and len(type_value) == 1:
+            properties["type"] = type_value[0]
+            return properties
+
+        if isinstance(type_value, list):
+            properties["anyOf"] = [{"type": t} for t in type_value]
+            return properties
+
+        return properties
+
     @classmethod
-    def _get_impl(cls, properties: dict[str, Any]) -> type[Self]:
+    def _get_impl(cls, properties: JSONSchema) -> type[Self]:
         for subcls in cls.__subclasses__():
             schema_type, schema_value = subcls._get_schema_type()
 
             if schema_type not in properties:
                 continue
 
-            if schema_value is None or schema_value == properties[schema_type]:
+            if schema_value is None or schema_value == properties[schema_type]:  # type: ignore
                 return subcls
 
-        raise ValueError("Unknown type")
+        raise InvalidSchemaException(
+            "No suitable type parser found", invalid_field=str(properties)
+        )
 
     @classmethod
     def _get_schema_type(cls) -> tuple[str, str | None]:
@@ -108,7 +148,7 @@ class GenericTypeParser(ABC, Generic[T]):
         }
 
     @staticmethod
-    def _validate_default(field_type: type, field_prop: dict) -> bool:
+    def _validate_default(field_type: T, field_prop: dict) -> bool:
         value = field_prop.get("default")
 
         if value is None and field_prop.get("default_factory") is not None:
@@ -117,8 +157,27 @@ class GenericTypeParser(ABC, Generic[T]):
         if value is None:
             return True
 
+        return GenericTypeParser._is_valid_value(field_type, field_prop, value)
+
+    @staticmethod
+    def _validate_examples(field_type: T, field_prop: dict) -> bool:
+        examples = field_prop.get("examples")
+
+        if examples is None:
+            return True
+
+        if not isinstance(examples, list):
+            return False
+
+        return all(
+            GenericTypeParser._is_valid_value(field_type, field_prop, e)
+            for e in examples
+        )
+
+    @staticmethod
+    def _is_valid_value(field_type: T, field_prop: dict, value: Any) -> bool:
         try:
-            field = Annotated[field_type, Field(**field_prop)]
+            field = Annotated[field_type, Field(**field_prop)]  # type: ignore
             TypeAdapter(field).validate_python(value)
         except Exception as _:
             return False

jambo/parser/allof_type_parser.py

@@ -1,7 +1,9 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser._type_parser import GenericTypeParser
+from jambo.types.json_schema_type import JSONSchema
 from jambo.types.type_parser_options import TypeParserOptions
 
-from typing_extensions import Any, Unpack
+from typing_extensions import Unpack
 
 
 class AllOfTypeParser(GenericTypeParser):
@@ -10,7 +12,7 @@ class AllOfTypeParser(GenericTypeParser):
     json_schema_type = "allOf"
 
     def from_properties_impl(
-        self, name, properties, **kwargs: Unpack[TypeParserOptions]
+        self, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
     ):
         sub_properties = properties.get("allOf", [])
 
@@ -25,36 +27,46 @@ class AllOfTypeParser(GenericTypeParser):
             sub_properties
         )
 
+        if (examples := properties.get("examples")) is not None:
+            combined_properties["examples"] = examples
+
         return parser().from_properties_impl(name, combined_properties, **kwargs)
 
     @staticmethod
     def _get_type_parser(
-        sub_properties: list[dict[str, Any]],
+        sub_properties: list[JSONSchema],
     ) -> type[GenericTypeParser]:
         if not sub_properties:
-            raise ValueError("Invalid JSON Schema: 'allOf' is empty.")
+            raise InvalidSchemaException(
+                "'allOf' must contain at least one schema", invalid_field="allOf"
+            )
 
-        parsers = set(
+        parsers: set[type[GenericTypeParser]] = set(
             GenericTypeParser._get_impl(sub_property) for sub_property in sub_properties
         )
         if len(parsers) != 1:
-            raise ValueError("Invalid JSON Schema: allOf types do not match.")
+            raise InvalidSchemaException(
+                "All sub-schemas in 'allOf' must resolve to the same type",
+                invalid_field="allOf",
+            )
 
         return parsers.pop()
 
     @staticmethod
     def _rebuild_properties_from_subproperties(
-        sub_properties: list[dict[str, Any]],
-    ) -> dict[str, Any]:
-        properties = {}
+        sub_properties: list[JSONSchema],
+    ) -> JSONSchema:
+        properties: JSONSchema = {}
         for subProperty in sub_properties:
             for name, prop in subProperty.items():
                 if name not in properties:
-                    properties[name] = prop
+                    properties[name] = prop  # type: ignore
                 else:
                     # Merge properties if they exist in both sub-properties
-                    properties[name] = AllOfTypeParser._validate_prop(
-                        name, properties[name], prop
+                    properties[name] = AllOfTypeParser._validate_prop(  # type: ignore
+                        name,
+                        properties[name],  # type: ignore
+                        prop,
                     )
         return properties
 
@@ -65,8 +77,8 @@ class AllOfTypeParser(GenericTypeParser):
 
         if prop_name == "default":
             if old_value != new_value:
-                raise ValueError(
-                    f"Invalid JSON Schema: conflicting defaults for '{prop_name}'"
+                raise InvalidSchemaException(
+                    f"Conflicting defaults for '{prop_name}'", invalid_field=prop_name
                 )
             return old_value
 

jambo/parser/anyof_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser._type_parser import GenericTypeParser
 from jambo.types.type_parser_options import TypeParserOptions
 
@@ -14,18 +15,25 @@ class AnyOfTypeParser(GenericTypeParser):
         self, name, properties, **kwargs: Unpack[TypeParserOptions]
     ):
         if "anyOf" not in properties:
-            raise ValueError(f"Invalid JSON Schema: {properties}")
+            raise InvalidSchemaException(
+                f"AnyOf type {name} must have 'anyOf' property defined.",
+                invalid_field="anyOf",
+            )
 
         if not isinstance(properties["anyOf"], list):
-            raise ValueError(f"Invalid JSON Schema: {properties['anyOf']}")
+            raise InvalidSchemaException(
+                "AnyOf must be a list of types.", invalid_field="anyOf"
+            )
 
         mapped_properties = self.mappings_properties_builder(properties, **kwargs)
 
         sub_properties = properties["anyOf"]
 
         sub_types = [
-            GenericTypeParser.type_from_properties(name, subProperty, **kwargs)
-            for subProperty in sub_properties
+            GenericTypeParser.type_from_properties(
+                f"{name}.sub{i}", subProperty, **kwargs
+            )
+            for i, subProperty in enumerate(sub_properties)
         ]
 
         if not kwargs.get("required", False):
@@ -34,8 +42,12 @@ class AnyOfTypeParser(GenericTypeParser):
         # By defining the type as Union of Annotated type we can use the Field validator
         # to enforce the constraints of each union type when needed.
         # We use Annotated to attach the Field validators to the type.
-        field_types = [
-            Annotated[t, Field(**v)] if v is not None else t for t, v in sub_types
-        ]
+        field_types = []
+        for subType, subProp in sub_types:
+            default_value = subProp.pop("default", None)
+            if default_value is None:
+                default_value = ...
+
+            field_types.append(Annotated[subType, Field(default_value, **subProp)])
 
         return Union[(*field_types,)], mapped_properties

jambo/parser/array_type_parser.py

@@ -1,21 +1,20 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser._type_parser import GenericTypeParser
 from jambo.types.type_parser_options import TypeParserOptions
 
-from typing_extensions import Iterable, TypeVar, Unpack
+from typing_extensions import (
+    Iterable,
+    Unpack,
+)
 
 import copy
 
 
-V = TypeVar("V")
-
-
 class ArrayTypeParser(GenericTypeParser):
     mapped_type = list
 
     json_schema_type = "type:array"
 
-    default_mappings = {"description": "description"}
-
     type_mappings = {
         "maxItems": "max_length",
         "minItems": "min_length",
@@ -26,8 +25,15 @@ class ArrayTypeParser(GenericTypeParser):
     ):
         item_properties = kwargs.copy()
         item_properties["required"] = True
+
+        if (items := properties.get("items")) is None:
+            raise InvalidSchemaException(
+                f"Array type {name} must have 'items' property defined.",
+                invalid_field="items",
+            )
+
         _item_type, _item_args = GenericTypeParser.type_from_properties(
-            name, properties["items"], **item_properties
+            name, items, **item_properties
         )
 
         wrapper_type = set if properties.get("uniqueItems", False) else list
@@ -35,11 +41,18 @@ class ArrayTypeParser(GenericTypeParser):
 
         mapped_properties = self.mappings_properties_builder(properties, **kwargs)
 
-        if "default" not in mapped_properties:
+        if (
+            default_value := mapped_properties.pop("default", None)
+        ) is not None or not kwargs.get("required", False):
             mapped_properties["default_factory"] = self._build_default_factory(
-                properties.get("default"), wrapper_type
+                default_value, wrapper_type
             )
 
+        if (example_values := mapped_properties.pop("examples", None)) is not None:
+            mapped_properties["examples"] = [
+                wrapper_type(example) for example in example_values
+            ]
+
         return field_type, mapped_properties
 
     def _build_default_factory(self, default_list, wrapper_type):
@@ -47,8 +60,9 @@ class ArrayTypeParser(GenericTypeParser):
             return lambda: None
 
         if not isinstance(default_list, Iterable):
-            raise ValueError(
-                f"Default value for array must be an iterable, got {type(default_list)}"
+            raise InvalidSchemaException(
+                f"Default value for array must be an iterable, got {type(default_list)}",
+                invalid_field="default",
             )
 
         return lambda: copy.deepcopy(wrapper_type(default_list))

jambo/parser/boolean_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser._type_parser import GenericTypeParser
 from jambo.types.type_parser_options import TypeParserOptions
 
@@ -20,6 +21,9 @@ class BooleanTypeParser(GenericTypeParser):
 
         default_value = properties.get("default")
         if default_value is not None and not isinstance(default_value, bool):
-            raise ValueError(f"Default value for {name} must be a boolean.")
+            raise InvalidSchemaException(
+                f"Default value for {name} must be a boolean.",
+                invalid_field="default",
+            )
 
         return bool, mapped_properties

jambo/parser/const_type_parser.py

@@ -1,9 +1,10 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser._type_parser import GenericTypeParser
 from jambo.types.json_schema_type import JSONSchemaNativeTypes
 from jambo.types.type_parser_options import TypeParserOptions
 
 from pydantic import AfterValidator
-from typing_extensions import Annotated, Any, Unpack
+from typing_extensions import Annotated, Any, Literal, Unpack
 
 
 class ConstTypeParser(GenericTypeParser):
@@ -12,19 +13,24 @@ class ConstTypeParser(GenericTypeParser):
     default_mappings = {
         "const": "default",
         "description": "description",
+        "examples": "examples",
     }
 
     def from_properties_impl(
         self, name, properties, **kwargs: Unpack[TypeParserOptions]
     ):
         if "const" not in properties:
-            raise ValueError(f"Const type {name} must have 'const' property defined.")
+            raise InvalidSchemaException(
+                f"Const type {name} must have 'const' property defined.",
+                invalid_field="const",
+            )
 
         const_value = properties["const"]
 
         if not isinstance(const_value, JSONSchemaNativeTypes):
-            raise ValueError(
-                f"Const type {name} must have 'const' value of allowed types: {JSONSchemaNativeTypes}."
+            raise InvalidSchemaException(
+                f"Const type {name} must have 'const' value of allowed types: {JSONSchemaNativeTypes}.",
+                invalid_field="const",
             )
 
         const_type = self._build_const_type(const_value)
@@ -33,11 +39,19 @@ class ConstTypeParser(GenericTypeParser):
         return const_type, parsed_properties
 
     def _build_const_type(self, const_value):
-        def _validate_const_value(value: Any) -> Any:
-            if value != const_value:
-                raise ValueError(
-                    f"Value must be equal to the constant value: {const_value}"
-                )
-            return value
+        # Try to use Literal for hashable types (required for discriminated unions)
+        # Fall back to validator approach for non-hashable types
+        try:
+            # Test if the value is hashable (can be used in Literal)
+            hash(const_value)
+            return Literal[const_value]
+        except TypeError:
+            # Non-hashable type (like list, dict), use validator approach
+            def _validate_const_value(value: Any) -> Any:
+                if value != const_value:
+                    raise ValueError(
+                        f"Value must be equal to the constant value: {const_value}"
+                    )
+                return value
 
-        return Annotated[type(const_value), AfterValidator(_validate_const_value)]
+            return Annotated[type(const_value), AfterValidator(_validate_const_value)]

jambo/parser/enum_type_parser.py

@@ -1,6 +1,7 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser._type_parser import GenericTypeParser
 from jambo.types.json_schema_type import JSONSchemaNativeTypes
-from jambo.types.type_parser_options import TypeParserOptions
+from jambo.types.type_parser_options import JSONSchema, TypeParserOptions
 
 from typing_extensions import Unpack
 
@@ -11,30 +12,40 @@ class EnumTypeParser(GenericTypeParser):
     json_schema_type = "enum"
 
     def from_properties_impl(
-        self, name, properties, **kwargs: Unpack[TypeParserOptions]
+        self, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
     ):
         if "enum" not in properties:
-            raise ValueError(f"Enum type {name} must have 'enum' property defined.")
+            raise InvalidSchemaException(
+                f"Enum type {name} must have 'enum' property defined.",
+                invalid_field="enum",
+            )
 
         enum_values = properties["enum"]
 
         if not isinstance(enum_values, list):
-            raise ValueError(f"Enum type {name} must have 'enum' as a list of values.")
+            raise InvalidSchemaException(
+                f"Enum type {name} must have 'enum' as a list of values.",
+                invalid_field="enum",
+            )
 
-        if any(
-            not isinstance(value, JSONSchemaNativeTypes) for value in enum_values
-        ):
-            raise ValueError(
-                f"Enum type {name} must have 'enum' values of allowed types: {JSONSchemaNativeTypes}."
+        if any(not isinstance(value, JSONSchemaNativeTypes) for value in enum_values):
+            raise InvalidSchemaException(
+                f"Enum type {name} must have 'enum' values of allowed types: {JSONSchemaNativeTypes}.",
+                invalid_field="enum",
             )
 
         # Create a new Enum type dynamically
-        enum_type = Enum(name, {str(value).upper(): value for value in enum_values})
+        enum_type = Enum(name, {str(value).upper(): value for value in enum_values})  # type: ignore
+        enum_type.__doc__ = properties.get("description")
+
         parsed_properties = self.mappings_properties_builder(properties, **kwargs)
 
-        if (
-            "default" in parsed_properties and parsed_properties["default"] is not None
-        ):            
+        if "default" in parsed_properties and parsed_properties["default"] is not None:
             parsed_properties["default"] = enum_type(parsed_properties["default"])
 
+        if "examples" in parsed_properties:
+            parsed_properties["examples"] = [
+                enum_type(example) for example in parsed_properties["examples"]
+            ]
+
         return enum_type, parsed_properties

jambo/parser/null_type_parser.py

@@ -0,0 +1,18 @@
+from jambo.parser._type_parser import GenericTypeParser
+from jambo.types.type_parser_options import TypeParserOptions
+
+from typing_extensions import Unpack
+
+
+class NullTypeParser(GenericTypeParser):
+    mapped_type = type(None)
+
+    json_schema_type = "type:null"
+
+    def from_properties_impl(
+        self, name, properties, **kwargs: Unpack[TypeParserOptions]
+    ):
+        mapped_properties = self.mappings_properties_builder(properties, **kwargs)
+        mapped_properties["default"] = None
+
+        return self.mapped_type, mapped_properties

jambo/parser/object_type_parser.py

@@ -1,8 +1,13 @@
+from jambo.exceptions import InternalAssertionException
 from jambo.parser._type_parser import GenericTypeParser
+from jambo.types.json_schema_type import JSONSchema
 from jambo.types.type_parser_options import TypeParserOptions
 
 from pydantic import BaseModel, ConfigDict, Field, create_model
-from typing_extensions import Any, Unpack
+from pydantic.fields import FieldInfo
+from typing_extensions import Unpack
+
+import warnings
 
 
 class ObjectTypeParser(GenericTypeParser):
@@ -11,60 +16,93 @@ class ObjectTypeParser(GenericTypeParser):
     json_schema_type = "type:object"
 
     def from_properties_impl(
-        self, name: str, properties: dict[str, Any], **kwargs: Unpack[TypeParserOptions]
+        self, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
     ) -> tuple[type[BaseModel], dict]:
         type_parsing = self.to_model(
             name,
             properties.get("properties", {}),
             properties.get("required", []),
+            description=properties.get("description"),
             **kwargs,
         )
-        type_properties = {}
+        type_properties = self.mappings_properties_builder(properties, **kwargs)
 
-        if "default" in properties:
-            type_properties["default_factory"] = lambda: type_parsing.model_validate(
-                properties["default"]
+        if (
+            default_value := type_properties.pop("default", None)
+        ) is not None or not kwargs.get("required", False):
+            type_properties["default_factory"] = (
+                lambda: type_parsing.model_validate(default_value)
+                if default_value is not None
+                else None
             )
 
+        if (example_values := type_properties.pop("examples", None)) is not None:
+            type_properties["examples"] = [
+                type_parsing.model_validate(example) for example in example_values
+            ]
+
         return type_parsing, type_properties
 
     @classmethod
     def to_model(
         cls,
         name: str,
-        schema: dict[str, Any],
+        properties: dict[str, JSONSchema],
         required_keys: list[str],
+        description: str | None = None,
         **kwargs: Unpack[TypeParserOptions],
     ) -> type[BaseModel]:
         """
         Converts JSON Schema object properties to a Pydantic model.
         :param name: The name of the model.
-        :param schema: The properties of the JSON Schema object.
+        :param properties: The properties of the JSON Schema object.
         :param required_keys: List of required keys in the schema.
         :return: A Pydantic model class.
         """
-        model_config = ConfigDict(validate_assignment=True)
-        fields = cls._parse_properties(schema, required_keys, **kwargs)
+        ref_cache = kwargs.get("ref_cache")
+        if ref_cache is None:
+            raise InternalAssertionException(
+                "`ref_cache` must be provided in kwargs for ObjectTypeParser"
+            )
 
-        return create_model(name, __config__=model_config, **fields)
+        if (model := ref_cache.get(name)) is not None and isinstance(model, type):
+            warnings.warn(
+                f"Type '{name}' is already in the ref_cache and therefore cached value will be used."
+                " This may indicate a namming collision in the schema or just a normal optimization,"
+                " if this behavior is desired pass a clean ref_cache or use the param `without_cache`"
+            )
+            return model
+
+        model_config = ConfigDict(validate_assignment=True)
+        fields = cls._parse_properties(name, properties, required_keys, **kwargs)
+
+        model = create_model(
+            name, __config__=model_config, __doc__=description, **fields
+        )  # type: ignore
+        ref_cache[name] = model
+
+        return model
 
     @classmethod
     def _parse_properties(
         cls,
-        properties: dict[str, Any],
+        name: str,
+        properties: dict[str, JSONSchema],
         required_keys: list[str],
         **kwargs: Unpack[TypeParserOptions],
-    ) -> dict[str, tuple[type, Field]]:
+    ) -> dict[str, tuple[type, FieldInfo]]:
         required_keys = required_keys or []
 
         fields = {}
-        for name, prop in properties.items():
-            sub_property = kwargs.copy()
-            sub_property["required"] = name in required_keys
+        for field_name, field_prop in properties.items():
+            sub_property: TypeParserOptions = kwargs.copy()
+            sub_property["required"] = field_name in required_keys
 
             parsed_type, parsed_properties = GenericTypeParser.type_from_properties(
-                name, prop, **sub_property
+                f"{name}.{field_name}",
+                field_prop,
+                **sub_property,  # type: ignore
             )
-            fields[name] = (parsed_type, Field(**parsed_properties))
+            fields[field_name] = (parsed_type, Field(**parsed_properties))
 
         return fields

jambo/parser/oneof_type_parser.py

@@ -0,0 +1,114 @@
+from jambo.exceptions import InvalidSchemaException
+from jambo.parser._type_parser import GenericTypeParser
+from jambo.types.type_parser_options import TypeParserOptions
+
+from pydantic import BaseModel, BeforeValidator, Field, TypeAdapter, ValidationError
+from typing_extensions import Annotated, Any, Union, Unpack, get_args
+
+
+Annotation = Annotated[Any, ...]
+
+
+class OneOfTypeParser(GenericTypeParser):
+    mapped_type = Union
+
+    json_schema_type = "oneOf"
+
+    def from_properties_impl(
+        self, name, properties, **kwargs: Unpack[TypeParserOptions]
+    ):
+        if "oneOf" not in properties:
+            raise InvalidSchemaException(
+                f"Invalid JSON Schema: {properties}", invalid_field="oneOf"
+            )
+
+        if not isinstance(properties["oneOf"], list) or len(properties["oneOf"]) == 0:
+            raise InvalidSchemaException(
+                f"Invalid JSON Schema: {properties['oneOf']}", invalid_field="oneOf"
+            )
+
+        mapped_properties = self.mappings_properties_builder(properties, **kwargs)
+
+        sub_types = [
+            GenericTypeParser.type_from_properties(
+                f"{name}_sub{i}", subProperty, **kwargs
+            )
+            for i, subProperty in enumerate(properties["oneOf"])
+        ]
+
+        if not kwargs.get("required", False):
+            mapped_properties["default"] = mapped_properties.get("default")
+
+        subfield_types = [Annotated[t, Field(**v)] for t, v in sub_types]
+
+        # Added with the understanding of discriminator are not in the JsonSchema Spec,
+        # they were added by OpenAPI and not all implementations may support them,
+        # and they do not always generate a model one-to-one to the Pydantic model
+        # TL;DR: Discriminators were added by OpenAPI and not a Official JSON Schema feature
+        if (discriminator := properties.get("discriminator")) is not None:
+            validated_type = self._build_type_one_of_with_discriminator(
+                subfield_types, discriminator
+            )
+        else:
+            validated_type = self._build_type_one_of_with_func(subfield_types)
+
+        return validated_type, mapped_properties
+
+    @staticmethod
+    def _build_type_one_of_with_discriminator(
+        subfield_types: list[Annotation], discriminator_prop: dict
+    ) -> Annotation:
+        """
+        Build a type with a discriminator.
+        """
+        if not isinstance(discriminator_prop, dict):
+            raise InvalidSchemaException(
+                "Discriminator must be a dictionary", invalid_field="discriminator"
+            )
+
+        for field in subfield_types:
+            field_type, field_info = get_args(field)
+
+            if issubclass(field_type, BaseModel):
+                continue
+
+            raise InvalidSchemaException(
+                "When using a discriminator, all subfield types must be of type 'object'.",
+                invalid_field="discriminator",
+            )
+
+        property_name = discriminator_prop.get("propertyName")
+        if property_name is None or not isinstance(property_name, str):
+            raise InvalidSchemaException(
+                "Discriminator must have a 'propertyName' key",
+                invalid_field="propertyName",
+            )
+
+        return Annotated[Union[(*subfield_types,)], Field(discriminator=property_name)]
+
+    @staticmethod
+    def _build_type_one_of_with_func(subfield_types: list[Annotation]) -> Annotation:
+        """
+        Build a type with a validation function for the oneOf constraint.
+        """
+
+        def validate_one_of(value: Any) -> Any:
+            matched_count = 0
+
+            for field_type in subfield_types:
+                try:
+                    TypeAdapter(field_type).validate_python(value)
+                    matched_count += 1
+                except ValidationError:
+                    continue
+
+            if matched_count == 0:
+                raise ValueError("Value does not match any of the oneOf schemas")
+            elif matched_count > 1:
+                raise ValueError(
+                    "Value matches multiple oneOf schemas, exactly one expected"
+                )
+
+            return value
+
+        return Annotated[Union[(*subfield_types,)], BeforeValidator(validate_one_of)]

jambo/parser/ref_type_parser.py

@@ -1,10 +1,13 @@
+from jambo.exceptions import InternalAssertionException, InvalidSchemaException
 from jambo.parser import GenericTypeParser
+from jambo.types import RefCacheDict
+from jambo.types.json_schema_type import JSONSchema
 from jambo.types.type_parser_options import TypeParserOptions
 
-from typing_extensions import Any, ForwardRef, Literal, TypeVar, Union, Unpack
+from typing_extensions import ForwardRef, Literal, Union, Unpack
 
 
-RefType = TypeVar("RefType", bound=Union[type, ForwardRef])
+RefType = Union[type, ForwardRef]
 
 RefStrategy = Literal["forward_ref", "def_ref"]
 
@@ -13,21 +16,22 @@ class RefTypeParser(GenericTypeParser):
     json_schema_type = "$ref"
 
     def from_properties_impl(
-        self, name: str, properties: dict[str, Any], **kwargs: Unpack[TypeParserOptions]
+        self, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
     ) -> tuple[RefType, dict]:
         if "$ref" not in properties:
-            raise ValueError(f"RefTypeParser: Missing $ref in properties for {name}")
+            raise InvalidSchemaException(
+                f"Missing $ref in properties for {name}", invalid_field="$ref"
+            )
 
-        context = kwargs.get("context")
-        if context is None:
-            raise RuntimeError(
-                f"RefTypeParser: Missing `content` in properties for {name}"
+        if kwargs.get("context") is None:
+            raise InternalAssertionException(
+                "`context` must be provided in kwargs for RefTypeParser"
             )
 
         ref_cache = kwargs.get("ref_cache")
         if ref_cache is None:
-            raise RuntimeError(
-                f"RefTypeParser: Missing `ref_cache` in properties for {name}"
+            raise InternalAssertionException(
+                "`ref_cache` must be provided in kwargs for RefTypeParser"
             )
 
         mapped_properties = self.mappings_properties_builder(properties, **kwargs)
@@ -41,19 +45,19 @@ class RefTypeParser(GenericTypeParser):
             # If the reference is either processing or already cached
             return ref_state, mapped_properties
 
-        ref_cache[ref_name] = self._parse_from_strategy(
-            ref_strategy, ref_name, ref_property, **kwargs
-        )
+        ref = self._parse_from_strategy(ref_strategy, ref_name, ref_property, **kwargs)
+        ref_cache[ref_name] = ref
 
-        return ref_cache[ref_name], mapped_properties
+        return ref, mapped_properties
 
     def _parse_from_strategy(
         self,
         ref_strategy: RefStrategy,
         ref_name: str,
-        ref_property: dict[str, Any],
+        ref_property: JSONSchema,
         **kwargs: Unpack[TypeParserOptions],
-    ):
+    ) -> RefType:
+        mapped_type: RefType
         match ref_strategy:
             case "forward_ref":
                 mapped_type = ForwardRef(ref_name)
@@ -62,14 +66,14 @@ class RefTypeParser(GenericTypeParser):
                     ref_name, ref_property, **kwargs
                 )
             case _:
-                raise ValueError(
-                    f"RefTypeParser: Unsupported $ref {ref_property['$ref']}"
+                raise InvalidSchemaException(
+                    f"Unsupported $ref {ref_property['$ref']}", invalid_field="$ref"
                 )
 
         return mapped_type
 
     def _get_ref_from_cache(
-        self, ref_name: str, ref_cache: dict[str, type]
+        self, ref_name: str, ref_cache: RefCacheDict
     ) -> RefType | type | None:
         try:
             ref_state = ref_cache[ref_name]
@@ -84,42 +88,48 @@ class RefTypeParser(GenericTypeParser):
             # If the reference is not in the cache, we will set it to None
             ref_cache[ref_name] = None
 
+        return None
+
     def _examine_ref_strategy(
-        self, name: str, properties: dict[str, Any], **kwargs: Unpack[TypeParserOptions]
-    ) -> tuple[RefStrategy, str, dict] | None:
-        if properties["$ref"] == "#":
+        self, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
+    ) -> tuple[RefStrategy, str, JSONSchema]:
+        if properties.get("$ref") == "#":
             ref_name = kwargs["context"].get("title")
             if ref_name is None:
-                raise ValueError(
-                    "RefTypeParser: Missing title in properties for $ref of Root Reference"
+                raise InvalidSchemaException(
+                    "Missing title in properties for $ref of Root Reference",
+                    invalid_field="title",
                 )
             return "forward_ref", ref_name, {}
 
-        if properties["$ref"].startswith("#/$defs/"):
+        if properties.get("$ref", "").startswith("#/$defs/"):
             target_name, target_property = self._extract_target_ref(
                 name, properties, **kwargs
             )
             return "def_ref", target_name, target_property
 
-        raise ValueError(
-            "RefTypeParser: Only Root and $defs references are supported at the moment"
+        raise InvalidSchemaException(
+            "Only Root and $defs references are supported at the moment",
+            invalid_field="$ref",
         )
 
     def _extract_target_ref(
-        self, name: str, properties: dict[str, Any], **kwargs: Unpack[TypeParserOptions]
-    ) -> tuple[str, dict]:
+        self, name: str, properties: JSONSchema, **kwargs: Unpack[TypeParserOptions]
+    ) -> tuple[str, JSONSchema]:
         target_name = None
         target_property = kwargs["context"]
         for prop_name in properties["$ref"].split("/")[1:]:
             if prop_name not in target_property:
-                raise ValueError(
-                    f"RefTypeParser: Missing {prop_name} in"
-                    " properties for $ref {properties['$ref']}"
+                raise InvalidSchemaException(
+                    f"Missing {prop_name} in properties for $ref {properties['$ref']}",
+                    invalid_field=prop_name,
                 )
             target_name = prop_name
-            target_property = target_property[prop_name]
+            target_property = target_property[prop_name]  # type: ignore
 
-        if target_name is None or target_property is None:
-            raise ValueError(f"RefTypeParser: Invalid $ref {properties['$ref']}")
+        if not isinstance(target_name, str) or target_property is None:
+            raise InvalidSchemaException(
+                f"Invalid $ref {properties['$ref']}", invalid_field="$ref"
+            )
 
         return target_name, target_property

jambo/parser/string_type_parser.py

@@ -1,10 +1,13 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser._type_parser import GenericTypeParser
 from jambo.types.type_parser_options import TypeParserOptions
 
-from pydantic import EmailStr, HttpUrl, IPvAnyAddress
+from pydantic import AnyUrl, EmailStr, TypeAdapter, ValidationError
 from typing_extensions import Unpack
 
-from datetime import date, datetime, time
+from datetime import date, datetime, time, timedelta
+from ipaddress import IPv4Address, IPv6Address
+from uuid import UUID
 
 
 class StringTypeParser(GenericTypeParser):
@@ -16,18 +19,25 @@ class StringTypeParser(GenericTypeParser):
         "maxLength": "max_length",
         "minLength": "min_length",
         "pattern": "pattern",
-        "format": "format",
     }
 
     format_type_mapping = {
-        "email": EmailStr,
-        "uri": HttpUrl,
-        "ipv4": IPvAnyAddress,
-        "ipv6": IPvAnyAddress,
-        "hostname": str,
+        # [7.3.1](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3.1). Dates, Times, and Duration
         "date": date,
         "time": time,
         "date-time": datetime,
+        "duration": timedelta,
+        # [7.3.2](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3.2). Email Addresses
+        "email": EmailStr,
+        # [7.3.3](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3.3). Hostnames
+        "hostname": str,
+        # [7.3.4](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3.4). IP Addresses
+        "ipv4": IPv4Address,
+        "ipv6": IPv6Address,
+        # [7.3.5](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3.5). Resource Identifiers
+        "uri": AnyUrl,
+        # "iri" # Not supported by pydantic and currently not supported by jambo
+        "uuid": UUID,
     }
 
     format_pattern_mapping = {
@@ -37,19 +47,34 @@ class StringTypeParser(GenericTypeParser):
     def from_properties_impl(
         self, name, properties, **kwargs: Unpack[TypeParserOptions]
     ):
-        mapped_properties = self.mappings_properties_builder(
-            properties, **kwargs
-        )
+        mapped_properties = self.mappings_properties_builder(properties, **kwargs)
 
         format_type = properties.get("format")
         if not format_type:
             return str, mapped_properties
 
         if format_type not in self.format_type_mapping:
-            raise ValueError(f"Unsupported string format: {format_type}")
+            raise InvalidSchemaException(
+                f"Unsupported string format: {format_type}", invalid_field="format"
+            )
 
         mapped_type = self.format_type_mapping[format_type]
         if format_type in self.format_pattern_mapping:
             mapped_properties["pattern"] = self.format_pattern_mapping[format_type]
 
+        try:
+            if "examples" in mapped_properties:
+                mapped_properties["examples"] = [
+                    TypeAdapter(mapped_type).validate_python(example)
+                    for example in mapped_properties["examples"]
+                ]
+        except ValidationError as err:
+            raise InvalidSchemaException(
+                f"Invalid example type for field {name}."
+            ) from err
+
+        if "json_schema_extra" not in mapped_properties:
+            mapped_properties["json_schema_extra"] = {}
+        mapped_properties["json_schema_extra"]["format"] = format_type
+
         return mapped_type, mapped_properties

jambo/schema_converter.py

@@ -1,9 +1,11 @@
+from jambo.exceptions import InvalidSchemaException, UnsupportedSchemaException
 from jambo.parser import ObjectTypeParser, RefTypeParser
-from jambo.types.json_schema_type import JSONSchema
+from jambo.types import JSONSchema, RefCacheDict
 
 from jsonschema.exceptions import SchemaError
 from jsonschema.validators import validator_for
 from pydantic import BaseModel
+from typing_extensions import MutableMapping, Optional
 
 
 class SchemaConverter:
@@ -15,22 +17,69 @@ class SchemaConverter:
     fields and types. The generated model can be used for data validation and serialization.
     """
 
-    @staticmethod
-    def build(schema: JSONSchema) -> type[BaseModel]:
+    _namespace_registry: MutableMapping[str, RefCacheDict]
+
+    def __init__(
+        self, namespace_registry: Optional[MutableMapping[str, RefCacheDict]] = None
+    ) -> None:
+        if namespace_registry is None:
+            namespace_registry = dict()
+        self._namespace_registry = namespace_registry
+
+    def build_with_cache(
+        self,
+        schema: JSONSchema,
+        ref_cache: Optional[RefCacheDict] = None,
+        without_cache: bool = False,
+    ) -> type[BaseModel]:
         """
         Converts a JSON Schema to a Pydantic model.
-        :param schema: The JSON Schema to convert.
-        :return: A Pydantic model class.
+        This is the instance method version of `build` and uses the instance's reference cache if none is provided.
+        Use this method if you want to utilize the instance's reference cache.
+
+            :param schema: The JSON Schema to convert.
+            :param ref_cache: An optional reference cache to use during conversion.
+            :param without_cache: Whether to use a clean reference cache for this conversion.
+            :return: The generated Pydantic model.
         """
+        local_ref_cache: RefCacheDict
+
+        if without_cache:
+            local_ref_cache = dict()
+        elif ref_cache is None:
+            namespace = schema.get("$id", "default")
+            local_ref_cache = self._namespace_registry.setdefault(namespace, dict())
+        else:
+            local_ref_cache = ref_cache
+
+        return self.build(schema, local_ref_cache)
+
+    @staticmethod
+    def build(
+        schema: JSONSchema, ref_cache: Optional[RefCacheDict] = None
+    ) -> type[BaseModel]:
+        """
+        Converts a JSON Schema to a Pydantic model.
+        This method doesn't use a reference cache if none is provided.
+            :param schema: The JSON Schema to convert.
+            :param ref_cache: An optional reference cache to use during conversion, if provided `with_clean_cache` will be ignored.
+            :return: The generated Pydantic model.
+        """
+        if ref_cache is None:
+            ref_cache = dict()
 
         try:
             validator = validator_for(schema)
-            validator.check_schema(schema)
-        except SchemaError as e:
-            raise ValueError(f"Invalid JSON Schema: {e}")
+            validator.check_schema(schema)  # type: ignore
+        except SchemaError as err:
+            raise InvalidSchemaException(
+                "Validation of JSON Schema failed.", cause=err
+            ) from err
 
         if "title" not in schema:
-            raise ValueError("JSON Schema must have a title.")
+            raise InvalidSchemaException(
+                "Schema must have a title.", invalid_field="title"
+            )
 
         schema_type = SchemaConverter._get_schema_type(schema)
 
@@ -38,10 +87,12 @@ class SchemaConverter:
             case "object":
                 return ObjectTypeParser.to_model(
                     schema["title"],
-                    schema["properties"],
+                    schema.get("properties", {}),
                     schema.get("required", []),
+                    description=schema.get("description"),
                     context=schema,
-                    ref_cache=dict(),
+                    ref_cache=ref_cache,
+                    required=True,
                 )
 
             case "$ref":
@@ -49,14 +100,47 @@ class SchemaConverter:
                     schema["title"],
                     schema,
                     context=schema,
-                    ref_cache=dict(),
+                    ref_cache=ref_cache,
+                    required=True,
                 )
                 return parsed_model
             case _:
-                raise TypeError(f"Unsupported schema type: {schema_type}")
+                unsupported_type = (
+                    f"type:{schema_type}" if schema_type else "missing type"
+                )
+                raise UnsupportedSchemaException(
+                    "Only object and $ref schema types are supported.",
+                    unsupported_field=unsupported_type,
+                )
+
+    def clear_ref_cache(self, namespace: Optional[str] = "default") -> None:
+        """
+        Clears the reference cache.
+        """
+        if namespace is None:
+            self._namespace_registry.clear()
+            return
+
+        if namespace in self._namespace_registry:
+            self._namespace_registry[namespace].clear()
+
+    def get_cached_ref(
+        self, ref_name: str, namespace: str = "default"
+    ) -> Optional[type]:
+        """
+        Gets a cached reference from the reference cache.
+        :param ref_name: The name of the reference to get.
+        :return: The cached reference, or None if not found.
+        """
+        cached_type = self._namespace_registry.get(namespace, {}).get(ref_name)
+
+        if isinstance(cached_type, type):
+            return cached_type
+
+        return None
 
     @staticmethod
-    def _get_schema_type(schema: JSONSchema) -> str:
+    def _get_schema_type(schema: JSONSchema) -> str | None:
         """
         Returns the type of the schema.
         :param schema: The JSON Schema to check.
@@ -65,4 +149,11 @@ class SchemaConverter:
         if "$ref" in schema:
             return "$ref"
 
-        return schema.get("type", "undefined")
+        type_value = schema.get("type")
+        if isinstance(type_value, list):
+            raise InvalidSchemaException(
+                "Invalid schema: 'type' cannot be a list at the top level",
+                invalid_field=str(schema),
+            )
+
+        return type_value

jambo/types/__init__.py

@@ -0,0 +1,17 @@
+from .json_schema_type import (
+    JSONSchema,
+    JSONSchemaNativeTypes,
+    JSONSchemaType,
+    JSONType,
+)
+from .type_parser_options import RefCacheDict, TypeParserOptions
+
+
+__all__ = [
+    "JSONSchemaType",
+    "JSONSchemaNativeTypes",
+    "JSONType",
+    "JSONSchema",
+    "RefCacheDict",
+    "TypeParserOptions",
+]

jambo/types/json_schema_type.py

@@ -1,93 +1,80 @@
-from typing_extensions import Dict, List, Literal, TypedDict, Union
+from __future__ import annotations
+
+from typing_extensions import (
+    Dict,
+    List,
+    Literal,
+    TypedDict,
+    Union,
+)
 
 from types import NoneType
 
 
+# Primitive JSON types
 JSONSchemaType = Literal[
     "string", "number", "integer", "boolean", "object", "array", "null"
 ]
 
-
 JSONSchemaNativeTypes: tuple[type, ...] = (
     str,
-    int,
     float,
+    int,
     bool,
     list,
     set,
     NoneType,
 )
 
-
 JSONType = Union[str, int, float, bool, None, Dict[str, "JSONType"], List["JSONType"]]
 
-
-class JSONSchema(TypedDict, total=False):
-    # Basic metadata
-    title: str
-    description: str
-    default: JSONType
-    examples: List[JSONType]
-
-    # Type definitions
-    type: Union[JSONSchemaType, List[JSONSchemaType]]
-
-    # Object-specific keywords
-    properties: Dict[str, "JSONSchema"]
-    required: List[str]
-    additionalProperties: Union[bool, "JSONSchema"]
-    minProperties: int
-    maxProperties: int
-    patternProperties: Dict[str, "JSONSchema"]
-    dependencies: Dict[str, Union[List[str], "JSONSchema"]]
-
-    # Array-specific keywords
-    items: Union["JSONSchema", List["JSONSchema"]]
-    additionalItems: Union[bool, "JSONSchema"]
-    minItems: int
-    maxItems: int
-    uniqueItems: bool
-
-    # String-specific keywords
-    minLength: int
-    maxLength: int
-    pattern: str
-    format: str
-
-    # Number-specific keywords
-    minimum: float
-    maximum: float
-    exclusiveMinimum: float
-    exclusiveMaximum: float
-    multipleOf: float
-
-    # Enum and const
-    enum: List[JSONType]
-    const: JSONType
-
-    # Conditionals
-    if_: "JSONSchema"  # 'if' is a reserved word in Python
-    then: "JSONSchema"
-    else_: "JSONSchema"  # 'else' is also a reserved word
-
-    # Combination keywords
-    allOf: List["JSONSchema"]
-    anyOf: List["JSONSchema"]
-    oneOf: List["JSONSchema"]
-    not_: "JSONSchema"  # 'not' is a reserved word
-
-
-# Fix forward references
-JSONSchema.__annotations__["properties"] = Dict[str, JSONSchema]
-JSONSchema.__annotations__["items"] = Union[JSONSchema, List[JSONSchema]]
-JSONSchema.__annotations__["additionalItems"] = Union[bool, JSONSchema]
-JSONSchema.__annotations__["additionalProperties"] = Union[bool, JSONSchema]
-JSONSchema.__annotations__["patternProperties"] = Dict[str, JSONSchema]
-JSONSchema.__annotations__["dependencies"] = Dict[str, Union[List[str], JSONSchema]]
-JSONSchema.__annotations__["if_"] = JSONSchema
-JSONSchema.__annotations__["then"] = JSONSchema
-JSONSchema.__annotations__["else_"] = JSONSchema
-JSONSchema.__annotations__["allOf"] = List[JSONSchema]
-JSONSchema.__annotations__["anyOf"] = List[JSONSchema]
-JSONSchema.__annotations__["oneOf"] = List[JSONSchema]
-JSONSchema.__annotations__["not_"] = JSONSchema
+# Dynamically define TypedDict with JSON Schema keywords
+JSONSchema = TypedDict(
+    "JSONSchema",
+    {
+        "$id": str,
+        "$schema": str,
+        "$ref": str,
+        "$anchor": str,
+        "$comment": str,
+        "$defs": Dict[str, "JSONSchema"],
+        "title": str,
+        "description": str,
+        "default": JSONType,
+        "examples": List[JSONType],
+        "type": JSONSchemaType | List[JSONSchemaType],
+        "enum": List[JSONType],
+        "const": JSONType,
+        "properties": Dict[str, "JSONSchema"],
+        "patternProperties": Dict[str, "JSONSchema"],
+        "additionalProperties": Union[bool, "JSONSchema"],
+        "required": List[str],
+        "minProperties": int,
+        "maxProperties": int,
+        "dependencies": Dict[str, Union[List[str], "JSONSchema"]],
+        "items": "JSONSchema",
+        "prefixItems": List["JSONSchema"],
+        "additionalItems": Union[bool, "JSONSchema"],
+        "contains": "JSONSchema",
+        "minItems": int,
+        "maxItems": int,
+        "uniqueItems": bool,
+        "minLength": int,
+        "maxLength": int,
+        "pattern": str,
+        "format": str,
+        "minimum": float,
+        "maximum": float,
+        "exclusiveMinimum": Union[bool, float],
+        "exclusiveMaximum": Union[bool, float],
+        "multipleOf": float,
+        "if": "JSONSchema",
+        "then": "JSONSchema",
+        "else": "JSONSchema",
+        "allOf": List["JSONSchema"],
+        "anyOf": List["JSONSchema"],
+        "oneOf": List["JSONSchema"],
+        "not": "JSONSchema",
+    },
+    total=False,  # all fields optional
+)

jambo/types/type_parser_options.py

@@ -1,9 +1,12 @@
 from jambo.types.json_schema_type import JSONSchema
 
-from typing_extensions import TypedDict
+from typing_extensions import ForwardRef, MutableMapping, TypedDict
+
+
+RefCacheDict = MutableMapping[str, ForwardRef | type | None]
 
 
 class TypeParserOptions(TypedDict):
     required: bool
     context: JSONSchema
-    ref_cache: dict[str, type]
+    ref_cache: RefCacheDict

pyproject.toml

@@ -17,26 +17,30 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
-license = { file = "LICENSE" }
+license = "MIT"
 readme = "README.md"
 
 # Project Dependencies
 dependencies = [
     "email-validator>=2.2.0",
     "jsonschema>=4.23.0",
-    "pydantic>=2.10.6",
+    "pydantic>=2.12.4",
 ]
 
 [dependency-groups]
 dev = [
     "coverage>=7.8.0",
+    "mypy>=1.18.1",
     "poethepoet>=0.33.1",
     "pre-commit>=4.2.0",
     "ruff>=0.11.4",
     "sphinx>=8.1.3",
     "sphinx-autobuild>=2024.10.3",
+    "sphinx-autodoc-typehints>=3.0.1",
     "sphinx-rtd-theme>=3.0.2",
+    "types-jsonschema>=4.25.1.20250822",
 ]
 
 
@@ -50,7 +54,8 @@ repository = "https://github.com/HideyoshiNakazone/jambo.git"
 create-hooks        = "bash .githooks/set-hooks.sh"
 tests               = "python -m coverage run -m unittest discover -v"
 tests-report        = "python -m coverage xml"
-serve-docs         = "sphinx-autobuild docs/source docs/build"
+type-check          = "mypy jambo"
+serve-docs          = "sphinx-autobuild docs/source docs/build"
 
 # Build System
 [tool.hatch.version]
@@ -83,3 +88,8 @@ section-order=[
     "standard-library",
 ]
 lines-after-imports = 2
+
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv" 

tests/exceptions/test_internal_assertion_exception.py

@@ -0,0 +1,21 @@
+from jambo.exceptions.internal_assertion_exception import InternalAssertionException
+
+from unittest import TestCase
+
+
+class TestInternalAssertionException(TestCase):
+    def test_inheritance(self):
+        self.assertTrue(issubclass(InternalAssertionException, RuntimeError))
+
+    def test_message(self):
+        message = "This is an internal assertion error."
+
+        expected_message = (
+            f"Internal Assertion Failed: {message}\n"
+            "This is likely a bug in Jambo. Please report it at"
+        )
+
+        with self.assertRaises(InternalAssertionException) as ctx:
+            raise InternalAssertionException(message)
+
+        self.assertEqual(str(ctx.exception), expected_message)

tests/exceptions/test_invalid_schema_exception.py

@@ -0,0 +1,44 @@
+from jambo.exceptions.invalid_schema_exception import InvalidSchemaException
+
+from unittest import TestCase
+
+
+class TestInternalAssertionException(TestCase):
+    def test_inheritance(self):
+        self.assertTrue(issubclass(InvalidSchemaException, ValueError))
+
+    def test_message(self):
+        message = "This is an internal assertion error."
+
+        expected_message = f"Invalid JSON Schema: {message}"
+
+        with self.assertRaises(InvalidSchemaException) as ctx:
+            raise InvalidSchemaException(message)
+
+        self.assertEqual(str(ctx.exception), expected_message)
+
+    def test_invalid_field(self):
+        message = "This is an internal assertion error."
+        invalid_field = "testField"
+
+        expected_message = (
+            f"Invalid JSON Schema: {message} (invalid field: {invalid_field})"
+        )
+
+        with self.assertRaises(InvalidSchemaException) as ctx:
+            raise InvalidSchemaException(message, invalid_field=invalid_field)
+
+        self.assertEqual(str(ctx.exception), expected_message)
+
+    def test_cause(self):
+        message = "This is an internal assertion error."
+        cause = ValueError("Underlying cause")
+
+        expected_message = (
+            f"Invalid JSON Schema: {message} (caused by ValueError: Underlying cause)"
+        )
+
+        with self.assertRaises(InvalidSchemaException) as ctx:
+            raise InvalidSchemaException(message, cause=cause)
+
+        self.assertEqual(str(ctx.exception), expected_message)

tests/exceptions/test_unsupported_schema_exception.py

@@ -0,0 +1,31 @@
+from jambo.exceptions.unsupported_schema_exception import UnsupportedSchemaException
+
+from unittest import TestCase
+
+
+class TestUnsupportedSchemaException(TestCase):
+    def test_inheritance(self):
+        self.assertTrue(issubclass(UnsupportedSchemaException, ValueError))
+
+    def test_message(self):
+        message = "This is an internal assertion error."
+
+        expected_message = f"Unsupported JSON Schema: {message}"
+
+        with self.assertRaises(UnsupportedSchemaException) as ctx:
+            raise UnsupportedSchemaException(message)
+
+        self.assertEqual(str(ctx.exception), expected_message)
+
+    def test_unsupported_field(self):
+        message = "This is an internal assertion error."
+        invalid_field = "testField"
+
+        expected_message = (
+            f"Unsupported JSON Schema: {message} (unsupported field: {invalid_field})"
+        )
+
+        with self.assertRaises(UnsupportedSchemaException) as ctx:
+            raise UnsupportedSchemaException(message, unsupported_field=invalid_field)
+
+        self.assertEqual(str(ctx.exception), expected_message)

tests/parser/test_allof_type_parser.py

@@ -1,5 +1,8 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser.allof_type_parser import AllOfTypeParser
 
+from pydantic import ValidationError
+
 from unittest import TestCase
 
 
@@ -39,16 +42,16 @@ class TestAllOfTypeParser(TestCase):
         }
 
         type_parsing, type_validator = AllOfTypeParser().from_properties(
-            "placeholder", properties
+            "placeholder", properties, ref_cache={}
         )
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             type_parsing(name="John", age=101)
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             type_parsing(name="", age=30)
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             type_parsing(name="John Invalid", age=30)
 
         obj = type_parsing(name="John", age=30)
@@ -84,13 +87,13 @@ class TestAllOfTypeParser(TestCase):
         }
 
         type_parsing, type_validator = AllOfTypeParser().from_properties(
-            "placeholder", properties
+            "placeholder", properties, ref_cache={}
         )
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             type_parsing(name="John")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             type_parsing(age=30)
 
         obj = type_parsing(name="John", age=30)
@@ -113,7 +116,7 @@ class TestAllOfTypeParser(TestCase):
         }
 
         type_parsing, type_validator = AllOfTypeParser().from_properties(
-            "placeholder", properties
+            "placeholder", properties, ref_cache={}
         )
 
         self.assertEqual(type_parsing, str)
@@ -134,7 +137,7 @@ class TestAllOfTypeParser(TestCase):
         }
 
         type_parsing, type_validator = AllOfTypeParser().from_properties(
-            "placeholder", properties
+            "placeholder", properties, ref_cache={}
         )
 
         self.assertEqual(type_parsing, str)
@@ -154,8 +157,8 @@ class TestAllOfTypeParser(TestCase):
             ]
         }
 
-        with self.assertRaises(ValueError):
-            AllOfTypeParser().from_properties("placeholder", properties)
+        with self.assertRaises(InvalidSchemaException):
+            AllOfTypeParser().from_properties("placeholder", properties, ref_cache={})
 
     def test_all_of_invalid_type_not_present(self):
         properties = {
@@ -167,8 +170,8 @@ class TestAllOfTypeParser(TestCase):
             ]
         }
 
-        with self.assertRaises(ValueError):
-            AllOfTypeParser().from_properties("placeholder", properties)
+        with self.assertRaises(InvalidSchemaException):
+            AllOfTypeParser().from_properties("placeholder", properties, ref_cache={})
 
     def test_all_of_invalid_type_in_fields(self):
         properties = {
@@ -180,8 +183,8 @@ class TestAllOfTypeParser(TestCase):
             ]
         }
 
-        with self.assertRaises(ValueError):
-            AllOfTypeParser().from_properties("placeholder", properties)
+        with self.assertRaises(InvalidSchemaException):
+            AllOfTypeParser().from_properties("placeholder", properties, ref_cache={})
 
     def test_all_of_invalid_type_not_all_equal(self):
         """
@@ -196,8 +199,8 @@ class TestAllOfTypeParser(TestCase):
             ]
         }
 
-        with self.assertRaises(ValueError):
-            AllOfTypeParser().from_properties("placeholder", properties)
+        with self.assertRaises(InvalidSchemaException):
+            AllOfTypeParser().from_properties("placeholder", properties, ref_cache={})
 
     def test_all_of_description_field(self):
         """
@@ -234,7 +237,9 @@ class TestAllOfTypeParser(TestCase):
             ],
         }
 
-        type_parsing, _ = AllOfTypeParser().from_properties("placeholder", properties)
+        type_parsing, _ = AllOfTypeParser().from_properties(
+            "placeholder", properties, ref_cache={}
+        )
 
         self.assertEqual(
             type_parsing.model_json_schema()["properties"]["name"]["description"],
@@ -272,7 +277,9 @@ class TestAllOfTypeParser(TestCase):
             ],
         }
 
-        type_parsing, _ = AllOfTypeParser().from_properties("placeholder", properties)
+        type_parsing, _ = AllOfTypeParser().from_properties(
+            "placeholder", properties, ref_cache={}
+        )
         obj = type_parsing()
         self.assertEqual(obj.name, "John")
         self.assertEqual(obj.age, 30)
@@ -304,5 +311,52 @@ class TestAllOfTypeParser(TestCase):
             ],
         }
 
-        with self.assertRaises(ValueError):
-            AllOfTypeParser().from_properties("placeholder", properties)
+        with self.assertRaises(InvalidSchemaException):
+            AllOfTypeParser().from_properties("placeholder", properties, ref_cache={})
+
+    def test_all_of_with_root_examples(self):
+        """
+        Tests the AllOfTypeParser with examples.
+        """
+
+        properties = {
+            "type": "object",
+            "allOf": [
+                {
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "minLength": 1,
+                        }
+                    },
+                },
+                {
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "maxLength": 4,
+                        }
+                    },
+                },
+            ],
+            "examples": [
+                {"name": "John"},
+                {"name": "Jane"},
+                {"name": "Doe"},
+                {"name": "Jack"},
+            ],
+        }
+
+        type_parsed, type_properties = AllOfTypeParser().from_properties(
+            "placeholder", properties, ref_cache={}
+        )
+
+        self.assertEqual(
+            type_properties["examples"],
+            [
+                type_parsed(name="John"),
+                type_parsed(name="Jane"),
+                type_parsed(name="Doe"),
+                type_parsed(name="Jack"),
+            ],
+        )

tests/parser/test_anyof_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser.anyof_type_parser import AnyOfTypeParser
 
 from typing_extensions import Annotated, Union, get_args, get_origin
@@ -14,7 +15,7 @@ class TestAnyOfTypeParser(TestCase):
             ],
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             AnyOfTypeParser().from_properties("placeholder", properties)
 
     def test_any_of_with_invalid_properties(self):
@@ -22,7 +23,7 @@ class TestAnyOfTypeParser(TestCase):
             "anyOf": None,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             AnyOfTypeParser().from_properties("placeholder", properties)
 
     def test_any_of_string_or_int(self):
@@ -95,5 +96,48 @@ class TestAnyOfTypeParser(TestCase):
             "default": 3.14,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             AnyOfTypeParser().from_properties("placeholder", properties)
+
+    def test_anyof_with_examples(self):
+        """
+        Tests the AnyOfTypeParser with a string or int type and examples.
+        """
+
+        properties = {
+            "anyOf": [
+                {
+                    "type": "string",
+                    "examples": ["example string"],
+                },
+                {
+                    "type": "integer",
+                    "examples": [123],
+                },
+            ],
+        }
+
+        parsed_type, _ = AnyOfTypeParser().from_properties("placeholder", properties)
+
+        type_1, type_2 = get_args(parsed_type)
+
+        self.assertEqual(get_args(type_1)[1].examples, ["example string"])
+
+        self.assertEqual(get_args(type_2)[1].examples, [123])
+
+    def test_any_of_with_root_examples(self):
+        """
+        Tests the AnyOfTypeParser with a string or int type and examples.
+        """
+
+        properties = {
+            "anyOf": [
+                {"type": "string"},
+                {"type": "integer"},
+            ],
+            "examples": ["100", 100],
+        }
+
+        _, type_validator = AnyOfTypeParser().from_properties("placeholder", properties)
+
+        self.assertEqual(type_validator["examples"], ["100", 100])

tests/parser/test_array_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser import ArrayTypeParser
 
 from typing_extensions import get_args
@@ -18,6 +19,17 @@ class TestArrayTypeParser(TestCase):
         self.assertEqual(type_parsing.__origin__, list)
         self.assertEqual(element_type, str)
 
+    def test_array_parser_with_no_items(self):
+        parser = ArrayTypeParser()
+
+        properties = {
+            "default": ["a", "b", "c", "d"],
+            "maxItems": 3,
+        }
+
+        with self.assertRaises(InvalidSchemaException):
+            parser.from_properties("placeholder", properties)
+
     def test_array_parser_with_options_unique(self):
         parser = ArrayTypeParser()
 
@@ -67,7 +79,7 @@ class TestArrayTypeParser(TestCase):
 
         properties = {"items": {"type": "string"}, "default": ["a", 1, "c"]}
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_array_parser_with_invalid_default_type(self):
@@ -75,15 +87,15 @@ class TestArrayTypeParser(TestCase):
 
         properties = {"items": {"type": "string"}, "default": 000}
 
-        with self.assertRaises(ValueError):
-            parser.from_properties("placeholder", properties)
+        with self.assertRaises(InvalidSchemaException):
+            parser.from_properties("placeholder", properties=properties)
 
     def test_array_parser_with_invalid_default_min(self):
         parser = ArrayTypeParser()
 
         properties = {"items": {"type": "string"}, "default": ["a"], "minItems": 2}
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_array_parser_with_invalid_default_max(self):
@@ -95,5 +107,21 @@ class TestArrayTypeParser(TestCase):
             "maxItems": 3,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
+
+    def test_array_parser_with_examples(self):
+        parser = ArrayTypeParser()
+
+        properties = {
+            "items": {"type": "integer"},
+            "examples": [
+                [1, 2, 3],
+                [4, 5, 6],
+            ],
+        }
+
+        type_parsing, type_validator = parser.from_properties("placeholder", properties)
+
+        self.assertEqual(type_parsing.__origin__, list)
+        self.assertEqual(type_validator["examples"], [[1, 2, 3], [4, 5, 6]])

tests/parser/test_bool_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser import BooleanTypeParser
 
 from unittest import TestCase
@@ -39,5 +40,21 @@ class TestBoolTypeParser(TestCase):
             "default": "invalid",
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties_impl("placeholder", properties)
+
+    def test_bool_parser_with_examples(self):
+        parser = BooleanTypeParser()
+
+        properties = {
+            "type": "boolean",
+            "examples": [True, False],
+        }
+
+        type_parsing, type_validator = parser.from_properties_impl(
+            "placeholder", properties
+        )
+
+        self.assertEqual(type_parsing, bool)
+        self.assertEqual(type_validator["default"], None)
+        self.assertEqual(type_validator["examples"], [True, False])

tests/parser/test_const_type_parser.py

@@ -1,25 +1,83 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser import ConstTypeParser
 
-from typing_extensions import Annotated, get_args, get_origin
+from typing_extensions import Annotated, Literal, get_args, get_origin
 
 from unittest import TestCase
 
 
 class TestConstTypeParser(TestCase):
-    def test_const_type_parser(self):
+    def test_const_type_parser_hashable_value(self):
+        """Test const parser with hashable values (uses Literal)"""
         parser = ConstTypeParser()
 
         expected_const_value = "United States of America"
-        properties = {"const": expected_const_value}
+        properties = {"const": expected_const_value, "examples": [expected_const_value]}
 
         parsed_type, parsed_properties = parser.from_properties_impl(
             "country", properties
         )
 
-        self.assertEqual(get_origin(parsed_type), Annotated)
-        self.assertIn(str, get_args(parsed_type))
+        # Check that we get a Literal type for hashable values
+        self.assertEqual(get_origin(parsed_type), Literal)
+        self.assertEqual(get_args(parsed_type), (expected_const_value,))
 
         self.assertEqual(parsed_properties["default"], expected_const_value)
+        self.assertEqual(parsed_properties["examples"], [expected_const_value])
+
+    def test_const_type_parser_non_hashable_value(self):
+        """Test const parser with non-hashable values (uses Annotated with validator)"""
+        parser = ConstTypeParser()
+
+        expected_const_value = [1, 2, 3]  # Lists are not hashable
+        properties = {"const": expected_const_value, "examples": [expected_const_value]}
+
+        parsed_type, parsed_properties = parser.from_properties_impl(
+            "list_const", properties
+        )
+
+        # Check that we get an Annotated type for non-hashable values
+        self.assertEqual(get_origin(parsed_type), Annotated)
+        self.assertIn(list, get_args(parsed_type))
+
+        self.assertEqual(parsed_properties["default"], expected_const_value)
+        self.assertEqual(parsed_properties["examples"], [expected_const_value])
+
+    def test_const_type_parser_integer_value(self):
+        """Test const parser with integer values (uses Literal)"""
+        parser = ConstTypeParser()
+
+        expected_const_value = 42
+        properties = {"const": expected_const_value, "examples": [expected_const_value]}
+
+        parsed_type, parsed_properties = parser.from_properties_impl(
+            "int_const", properties
+        )
+
+        # Check that we get a Literal type for hashable values
+        self.assertEqual(get_origin(parsed_type), Literal)
+        self.assertEqual(get_args(parsed_type), (expected_const_value,))
+
+        self.assertEqual(parsed_properties["default"], expected_const_value)
+        self.assertEqual(parsed_properties["examples"], [expected_const_value])
+
+    def test_const_type_parser_boolean_value(self):
+        """Test const parser with boolean values (uses Literal)"""
+        parser = ConstTypeParser()
+
+        expected_const_value = True
+        properties = {"const": expected_const_value, "examples": [expected_const_value]}
+
+        parsed_type, parsed_properties = parser.from_properties_impl(
+            "bool_const", properties
+        )
+
+        # Check that we get a Literal type for hashable values
+        self.assertEqual(get_origin(parsed_type), Literal)
+        self.assertEqual(get_args(parsed_type), (expected_const_value,))
+
+        self.assertEqual(parsed_properties["default"], expected_const_value)
+        self.assertEqual(parsed_properties["examples"], [expected_const_value])
 
     def test_const_type_parser_invalid_properties(self):
         parser = ConstTypeParser()
@@ -27,7 +85,7 @@ class TestConstTypeParser(TestCase):
         expected_const_value = "United States of America"
         properties = {"notConst": expected_const_value}
 
-        with self.assertRaises(ValueError) as context:
+        with self.assertRaises(InvalidSchemaException) as context:
             parser.from_properties_impl("invalid_country", properties)
 
         self.assertIn(
@@ -40,7 +98,7 @@ class TestConstTypeParser(TestCase):
 
         properties = {"const": {}}
 
-        with self.assertRaises(ValueError) as context:
+        with self.assertRaises(InvalidSchemaException) as context:
             parser.from_properties_impl("invalid_country", properties)
 
         self.assertIn(

tests/parser/test_enum_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser import EnumTypeParser
 
 from enum import Enum
@@ -10,7 +11,7 @@ class TestEnumTypeParser(TestCase):
 
         schema = {}
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parsed_type, parsed_properties = parser.from_properties_impl(
                 "TestEnum",
                 schema,
@@ -23,7 +24,7 @@ class TestEnumTypeParser(TestCase):
             "enum": "not_a_list",
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parsed_type, parsed_properties = parser.from_properties_impl(
                 "TestEnum",
                 schema,
@@ -48,6 +49,20 @@ class TestEnumTypeParser(TestCase):
         )
         self.assertEqual(parsed_properties, {"default": None})
 
+    def test_enum_type_parser_creates_enum_with_description(self):
+        parser = EnumTypeParser()
+
+        schema = {
+            "description": "an enum",
+            "enum": ["value1"],
+        }
+
+        parsed_type, parsed_properties = parser.from_properties_impl(
+            "TestEnum",
+            schema,
+        )
+        self.assertEqual(parsed_type.__doc__, "an enum")
+
     def test_enum_type_parser_creates_enum_with_default(self):
         parser = EnumTypeParser()
 
@@ -86,5 +101,29 @@ class TestEnumTypeParser(TestCase):
             "enum": ["value1", 42, dict()],
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties_impl("TestEnum", schema)
+
+    def test_enum_type_parser_creates_enum_with_examples(self):
+        parser = EnumTypeParser()
+
+        schema = {
+            "enum": ["value1", "value2", "value3"],
+            "examples": ["value1", "value3"],
+        }
+
+        parsed_type, parsed_properties = parser.from_properties_impl(
+            "TestEnum",
+            schema,
+        )
+
+        self.assertIsInstance(parsed_type, type)
+        self.assertTrue(issubclass(parsed_type, Enum))
+        self.assertEqual(
+            set(parsed_type.__members__.keys()), {"VALUE1", "VALUE2", "VALUE3"}
+        )
+        self.assertEqual(parsed_properties["default"], None)
+        self.assertEqual(
+            parsed_properties["examples"],
+            [getattr(parsed_type, "VALUE1"), getattr(parsed_type, "VALUE3")],
+        )

tests/parser/test_float_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser import FloatTypeParser
 
 from unittest import TestCase
@@ -22,6 +23,7 @@ class TestFloatTypeParser(TestCase):
             "maximum": 10.5,
             "minimum": 1.0,
             "multipleOf": 0.5,
+            "examples": [1.5, 2.5],
         }
 
         type_parsing, type_validator = parser.from_properties("placeholder", properties)
@@ -30,6 +32,7 @@ class TestFloatTypeParser(TestCase):
         self.assertEqual(type_validator["le"], 10.5)
         self.assertEqual(type_validator["ge"], 1.0)
         self.assertEqual(type_validator["multiple_of"], 0.5)
+        self.assertEqual(type_validator["examples"], [1.5, 2.5])
 
     def test_float_parser_with_default(self):
         parser = FloatTypeParser()
@@ -61,7 +64,7 @@ class TestFloatTypeParser(TestCase):
             "multipleOf": 0.5,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_float_parser_with_default_invalid_maximum(self):
@@ -75,7 +78,7 @@ class TestFloatTypeParser(TestCase):
             "multipleOf": 0.5,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_float_parser_with_default_invalid_minimum(self):
@@ -89,7 +92,7 @@ class TestFloatTypeParser(TestCase):
             "multipleOf": 0.5,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_float_parser_with_default_invalid_exclusive_maximum(self):
@@ -103,7 +106,7 @@ class TestFloatTypeParser(TestCase):
             "multipleOf": 0.5,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_float_parser_with_default_invalid_exclusive_minimum(self):
@@ -117,7 +120,7 @@ class TestFloatTypeParser(TestCase):
             "multipleOf": 0.5,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_float_parser_with_default_invalid_multiple(self):
@@ -131,5 +134,5 @@ class TestFloatTypeParser(TestCase):
             "multipleOf": 2.0,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)

tests/parser/test_int_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser import IntTypeParser
 
 from unittest import TestCase
@@ -22,6 +23,7 @@ class TestIntTypeParser(TestCase):
             "maximum": 10,
             "minimum": 1,
             "multipleOf": 2,
+            "examples": [2, 4],
         }
 
         type_parsing, type_validator = parser.from_properties("placeholder", properties)
@@ -30,6 +32,7 @@ class TestIntTypeParser(TestCase):
         self.assertEqual(type_validator["le"], 10)
         self.assertEqual(type_validator["ge"], 1)
         self.assertEqual(type_validator["multiple_of"], 2)
+        self.assertEqual(type_validator["examples"], [2, 4])
 
     def test_int_parser_with_default(self):
         parser = IntTypeParser()
@@ -61,7 +64,7 @@ class TestIntTypeParser(TestCase):
             "multipleOf": 2,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_int_parser_with_default_invalid_maximum(self):
@@ -75,7 +78,7 @@ class TestIntTypeParser(TestCase):
             "multipleOf": 2,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_int_parser_with_default_invalid_minimum(self):
@@ -89,7 +92,7 @@ class TestIntTypeParser(TestCase):
             "multipleOf": 2,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_int_parser_with_default_invalid_exclusive_maximum(self):
@@ -103,7 +106,7 @@ class TestIntTypeParser(TestCase):
             "multipleOf": 2,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_int_parser_with_default_invalid_exclusive_minimum(self):
@@ -117,7 +120,7 @@ class TestIntTypeParser(TestCase):
             "multipleOf": 2,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_int_parser_with_default_invalid_multipleOf(self):
@@ -131,5 +134,5 @@ class TestIntTypeParser(TestCase):
             "multipleOf": 2,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)

tests/parser/test_null_type_parser.py

@@ -0,0 +1,45 @@
+from jambo.parser import NullTypeParser
+
+from unittest import TestCase
+
+
+class TestNullTypeParser(TestCase):
+    def test_null_parser_no_options(self):
+        parser = NullTypeParser()
+
+        properties = {"type": "null"}
+
+        type_parsing, type_validator = parser.from_properties_impl(
+            "placeholder", properties
+        )
+
+        self.assertEqual(type_parsing, type(None))
+        self.assertEqual(type_validator, {"default": None})
+
+    def test_null_parser_with_examples(self):
+        parser = NullTypeParser()
+
+        properties = {
+            "type": "null",
+            "examples": [None],
+        }
+
+        type_parsing, type_validator = parser.from_properties_impl(
+            "placeholder", properties
+        )
+
+        self.assertEqual(type_parsing, type(None))
+        self.assertEqual(type_validator["default"], None)
+        self.assertEqual(type_validator["examples"], [None])
+
+    def test_null_parser_with_invalid_default(self):
+        parser = NullTypeParser()
+
+        properties = {"type": "null", "default": "invalid"}
+
+        type_parsing, type_validator = parser.from_properties_impl(
+            "placeholder", properties
+        )
+
+        self.assertEqual(type_parsing, type(None))
+        self.assertEqual(type_validator, {"default": None})

tests/parser/test_object_type_parser.py

@@ -1,10 +1,11 @@
+from jambo.exceptions import InternalAssertionException
 from jambo.parser import ObjectTypeParser
 
 from unittest import TestCase
 
 
 class TestObjectTypeParser(TestCase):
-    def test_object_type_parser(self):
+    def test_object_type_parser_throws_without_ref_cache(self):
         parser = ObjectTypeParser()
 
         properties = {
@@ -15,13 +16,57 @@ class TestObjectTypeParser(TestCase):
             },
         }
 
-        Model, _args = parser.from_properties_impl("placeholder", properties)
+        with self.assertRaises(InternalAssertionException):
+            parser.from_properties_impl("placeholder", properties)
+
+    def test_object_type_parser(self):
+        parser = ObjectTypeParser()
+
+        properties = {
+            "type": "object",
+            "description": "obj desc",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+            },
+        }
+
+        Model, _args = parser.from_properties_impl(
+            "placeholder", properties, ref_cache={}
+        )
+        self.assertEqual(Model.__doc__, "obj desc")
 
         obj = Model(name="name", age=10)
 
         self.assertEqual(obj.name, "name")
         self.assertEqual(obj.age, 10)
 
+    def test_object_type_parser_with_object_example(self):
+        parser = ObjectTypeParser()
+
+        properties = {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+            },
+            "examples": [
+                {
+                    "name": "example_name",
+                    "age": 30,
+                }
+            ],
+        }
+
+        _, type_validator = parser.from_properties_impl(
+            "placeholder", properties, ref_cache={}
+        )
+
+        test_example = type_validator["examples"][0]
+
+        self.assertEqual(test_example.name, "example_name")
+        self.assertEqual(test_example.age, 30)
+
     def test_object_type_parser_with_default(self):
         parser = ObjectTypeParser()
 
@@ -37,7 +82,9 @@ class TestObjectTypeParser(TestCase):
             },
         }
 
-        _, type_validator = parser.from_properties_impl("placeholder", properties)
+        _, type_validator = parser.from_properties_impl(
+            "placeholder", properties, ref_cache={}
+        )
 
         # Check default value
         default_obj = type_validator["default_factory"]()
@@ -47,3 +94,18 @@ class TestObjectTypeParser(TestCase):
         # Chekc default factory new object id
         new_obj = type_validator["default_factory"]()
         self.assertNotEqual(id(default_obj), id(new_obj))
+
+    def test_object_type_parser_warns_if_object_override_in_cache(self):
+        ref_cache = {}
+
+        parser = ObjectTypeParser()
+
+        properties = {"type": "object", "properties": {}}
+
+        with self.assertWarns(UserWarning):
+            _, type_validator = parser.from_properties_impl(
+                "placeholder", properties, ref_cache=ref_cache
+            )
+            _, type_validator = parser.from_properties_impl(
+                "placeholder", properties, ref_cache=ref_cache
+            )

tests/parser/test_oneof_type_parser.py

@@ -0,0 +1,602 @@
+from jambo import SchemaConverter
+from jambo.exceptions import InvalidSchemaException
+from jambo.parser.oneof_type_parser import OneOfTypeParser
+
+from pydantic import ValidationError
+
+from unittest import TestCase
+
+
+class TestOneOfTypeParser(TestCase):
+    def test_oneof_raises_on_invalid_property(self):
+        with self.assertRaises(InvalidSchemaException):
+            OneOfTypeParser().from_properties_impl(
+                "test_field",
+                {
+                    # Invalid schema, should have property "oneOf"
+                },
+                required=True,
+                context={},
+                ref_cache={},
+            )
+
+        with self.assertRaises(InvalidSchemaException):
+            OneOfTypeParser().from_properties_impl(
+                "test_field",
+                {
+                    "oneOf": [],  # should throw because oneOf must be a list with at least one item
+                },
+                required=True,
+                context={},
+                ref_cache={},
+            )
+
+        with self.assertRaises(InvalidSchemaException):
+            SchemaConverter.build(
+                {
+                    "title": "Test",
+                    "type": "object",
+                    "properties": {
+                        "value": {
+                            "oneOf": [],  # should throw because oneOf requires at least one schema
+                        }
+                    },
+                }
+            )
+
+    def test_oneof_basic_integer_and_string(self):
+        schema = {
+            "title": "Person",
+            "description": "A person with an ID that can be either an integer or a formatted string",
+            "type": "object",
+            "properties": {
+                "id": {
+                    "oneOf": [
+                        {"type": "integer", "minimum": 1},
+                        {"type": "string", "pattern": "^[A-Z]{2}[0-9]{4}$"},
+                    ]
+                },
+            },
+            "required": ["id"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        obj1 = Model(id=123)
+        self.assertEqual(obj1.id, 123)
+
+        obj2 = Model(id="AB1234")
+        self.assertEqual(obj2.id, "AB1234")
+
+    def test_oneof_validation_failures(self):
+        schema = {
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "id": {
+                    "oneOf": [
+                        {"type": "integer", "minimum": 1},
+                        {"type": "string", "pattern": "^[A-Z]{2}[0-9]{4}$"},
+                    ]
+                },
+            },
+            "required": ["id"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        with self.assertRaises(ValidationError):
+            Model(id=-5)
+
+        with self.assertRaises(ValidationError):
+            Model(id="invalid")
+
+        with self.assertRaises(ValidationError):
+            Model(id=123.45)
+
+    def test_oneof_with_conflicting_schemas(self):
+        schema = {
+            "title": "Value",
+            "type": "object",
+            "properties": {
+                "data": {
+                    "oneOf": [
+                        {"type": "number", "multipleOf": 2},
+                        {"type": "number", "multipleOf": 3},
+                    ]
+                },
+            },
+            "required": ["data"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        obj1 = Model(data=4)
+        self.assertEqual(obj1.data, 4)
+
+        obj2 = Model(data=9)
+        self.assertEqual(obj2.data, 9)
+
+        with self.assertRaises(ValidationError) as cm:
+            Model(data=6)
+        self.assertIn("matches multiple oneOf schemas", str(cm.exception))
+
+        with self.assertRaises(ValidationError):
+            Model(data=5)
+
+    def test_oneof_with_objects(self):
+        schema = {
+            "title": "Contact",
+            "type": "object",
+            "properties": {
+                "contact_info": {
+                    "oneOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "email": {"type": "string", "format": "email"}
+                            },
+                            "required": ["email"],
+                            "additionalProperties": False,
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "phone": {"type": "string", "pattern": "^[0-9-]+$"}
+                            },
+                            "required": ["phone"],
+                            "additionalProperties": False,
+                        },
+                    ]
+                },
+            },
+            "required": ["contact_info"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        obj1 = Model(contact_info={"email": "user@example.com"})
+        self.assertEqual(obj1.contact_info.email, "user@example.com")
+
+        obj2 = Model(contact_info={"phone": "123-456-7890"})
+        self.assertEqual(obj2.contact_info.phone, "123-456-7890")
+
+        with self.assertRaises(ValidationError):
+            Model(contact_info={"email": "user@example.com", "phone": "123-456-7890"})
+
+    def test_oneof_with_discriminator_basic(self):
+        schema = {
+            "title": "Pet",
+            "type": "object",
+            "properties": {
+                "pet": {
+                    "oneOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "type": {"const": "cat"},
+                                "meows": {"type": "boolean"},
+                            },
+                            "required": ["type", "meows"],
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "type": {"const": "dog"},
+                                "barks": {"type": "boolean"},
+                            },
+                            "required": ["type", "barks"],
+                        },
+                    ],
+                    "discriminator": {"propertyName": "type"},
+                }
+            },
+            "required": ["pet"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        cat = Model(pet={"type": "cat", "meows": True})
+        self.assertEqual(cat.pet.type, "cat")
+        self.assertEqual(cat.pet.meows, True)
+
+        dog = Model(pet={"type": "dog", "barks": False})
+        self.assertEqual(dog.pet.type, "dog")
+        self.assertEqual(dog.pet.barks, False)
+
+        with self.assertRaises(ValidationError):
+            Model(pet={"type": "cat", "barks": True})
+
+        with self.assertRaises(ValidationError):
+            Model(pet={"type": "bird", "flies": True})
+
+    def test_oneof_with_invalid_types(self):
+        with self.assertRaises(InvalidSchemaException):
+            SchemaConverter.build(
+                {
+                    "title": "Pet",
+                    "type": "object",
+                    "properties": {
+                        "pet": {
+                            "oneOf": [
+                                {
+                                    "type": "number",
+                                },
+                                {
+                                    "type": "string",
+                                },
+                            ],
+                            "discriminator": {"propertyName": "type"},
+                        }
+                    },
+                    "required": ["pet"],
+                }
+            )
+
+    def test_oneof_with_discriminator_mapping(self):
+        schema = {
+            "title": "Vehicle",
+            "type": "object",
+            "properties": {
+                "vehicle": {
+                    "oneOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "vehicle_type": {"const": "car"},
+                                "doors": {
+                                    "type": "integer",
+                                    "minimum": 2,
+                                    "maximum": 4,
+                                },
+                            },
+                            "required": ["vehicle_type", "doors"],
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "vehicle_type": {"const": "motorcycle"},
+                                "engine_size": {"type": "number", "minimum": 125},
+                            },
+                            "required": ["vehicle_type", "engine_size"],
+                        },
+                    ],
+                    "discriminator": {
+                        "propertyName": "vehicle_type",
+                        "mapping": {
+                            "car": "#/properties/vehicle/oneOf/0",
+                            "motorcycle": "#/properties/vehicle/oneOf/1",
+                        },
+                    },
+                }
+            },
+            "required": ["vehicle"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        car = Model(vehicle={"vehicle_type": "car", "doors": 4})
+        self.assertEqual(car.vehicle.vehicle_type, "car")
+        self.assertEqual(car.vehicle.doors, 4)
+
+        motorcycle = Model(vehicle={"vehicle_type": "motorcycle", "engine_size": 600.0})
+        self.assertEqual(motorcycle.vehicle.vehicle_type, "motorcycle")
+        self.assertEqual(motorcycle.vehicle.engine_size, 600.0)
+
+    def test_oneof_with_discriminator_invalid_values(self):
+        schema = {
+            "title": "Shape",
+            "type": "object",
+            "properties": {
+                "shape": {
+                    "oneOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "type": {"const": "circle"},
+                                "radius": {"type": "number", "minimum": 0},
+                            },
+                            "required": ["type", "radius"],
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "type": {"const": "square"},
+                                "side": {"type": "number", "minimum": 0},
+                            },
+                            "required": ["type", "side"],
+                        },
+                    ],
+                    "discriminator": {"propertyName": "type"},
+                }
+            },
+            "required": ["shape"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        with self.assertRaises(ValidationError):
+            Model(shape={"type": "triangle", "base": 5, "height": 3})
+
+        with self.assertRaises(ValidationError):
+            Model(shape={"type": "circle", "side": 5})
+
+        with self.assertRaises(ValidationError):
+            Model(shape={"radius": 5})
+
+    def test_oneof_missing_properties(self):
+        schema = {
+            "title": "Test",
+            "type": "object",
+            "properties": {
+                "value": {
+                    "notOneOf": [
+                        {"type": "string"},
+                        {"type": "integer"},
+                    ]
+                },
+            },
+        }
+
+        with self.assertRaises(InvalidSchemaException):
+            SchemaConverter.build(schema)
+
+    def test_oneof_invalid_properties(self):
+        schema = {
+            "title": "Test",
+            "type": "object",
+            "properties": {
+                "value": {"oneOf": None},
+            },
+        }
+
+        with self.assertRaises(InvalidSchemaException):
+            SchemaConverter.build(schema)
+
+    def test_oneof_with_default_value(self):
+        schema = {
+            "title": "Test",
+            "type": "object",
+            "properties": {
+                "value": {
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "integer"},
+                    ],
+                    "default": "test",
+                },
+            },
+        }
+
+        Model = SchemaConverter.build(schema)
+        obj = Model()
+        self.assertEqual(obj.value, "test")
+
+    def test_oneof_with_invalid_default_value(self):
+        schema = {
+            "title": "Test",
+            "type": "object",
+            "properties": {
+                "value": {
+                    "oneOf": [
+                        {"type": "string", "minLength": 5},
+                        {"type": "integer", "minimum": 10},
+                    ],
+                    "default": "hi",
+                },
+            },
+        }
+
+        with self.assertRaises(InvalidSchemaException):
+            SchemaConverter.build(schema)
+
+    def test_oneof_discriminator_without_property_name(self):
+        # Should throw because the spec determines propertyName is required for discriminator
+        with self.assertRaises(InvalidSchemaException):
+            SchemaConverter.build(
+                {
+                    "title": "Test",
+                    "type": "object",
+                    "properties": {
+                        "value": {
+                            "oneOf": [
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "type": {"const": "a"},
+                                        "value": {"type": "string"},
+                                    },
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "type": {"const": "b"},
+                                        "value": {"type": "integer"},
+                                    },
+                                },
+                            ],
+                            "discriminator": {},  # discriminator without propertyName
+                        }
+                    },
+                }
+            )
+
+    def test_oneof_discriminator_with_invalid_discriminator(self):
+        # Should throw because a valid discriminator is required
+        with self.assertRaises(InvalidSchemaException):
+            SchemaConverter.build(
+                {
+                    "title": "Test",
+                    "type": "object",
+                    "properties": {
+                        "value": {
+                            "oneOf": [
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "type": {"const": "a"},
+                                        "value": {"type": "string"},
+                                    },
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "type": {"const": "b"},
+                                        "value": {"type": "integer"},
+                                    },
+                                },
+                            ],
+                            "discriminator": "invalid",  # discriminator without propertyName
+                        }
+                    },
+                }
+            )
+
+    def test_oneof_overlapping_strings_from_docs(self):
+        """Test the overlapping strings example from documentation"""
+        schema = {
+            "title": "SimpleExample",
+            "type": "object",
+            "properties": {
+                "value": {
+                    "oneOf": [
+                        {"type": "string", "maxLength": 6},
+                        {"type": "string", "minLength": 4},
+                    ]
+                }
+            },
+            "required": ["value"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        # Valid: Short string (matches first schema only)
+        obj1 = Model(value="hi")
+        self.assertEqual(obj1.value, "hi")
+
+        # Valid: Long string (matches second schema only)
+        obj2 = Model(value="very long string")
+        self.assertEqual(obj2.value, "very long string")
+
+        # Invalid: Medium string (matches BOTH schemas - violates oneOf)
+        with self.assertRaises(ValidationError) as cm:
+            Model(value="hello")  # 5 chars: matches maxLength=6 AND minLength=4
+
+        self.assertIn("matches multiple oneOf schemas", str(cm.exception))
+
+    def test_oneof_shapes_discriminator_from_docs(self):
+        """Test the shapes discriminator example from documentation"""
+        schema = {
+            "title": "Shape",
+            "type": "object",
+            "properties": {
+                "shape": {
+                    "oneOf": [
+                        {
+                            "type": "object",
+                            "properties": {
+                                "type": {"const": "circle"},
+                                "radius": {"type": "number", "minimum": 0},
+                            },
+                            "required": ["type", "radius"],
+                        },
+                        {
+                            "type": "object",
+                            "properties": {
+                                "type": {"const": "rectangle"},
+                                "width": {"type": "number", "minimum": 0},
+                                "height": {"type": "number", "minimum": 0},
+                            },
+                            "required": ["type", "width", "height"],
+                        },
+                    ],
+                    "discriminator": {"propertyName": "type"},
+                }
+            },
+            "required": ["shape"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        # Valid: Circle
+        circle = Model(shape={"type": "circle", "radius": 5.0})
+        self.assertEqual(circle.shape.type, "circle")
+        self.assertEqual(circle.shape.radius, 5.0)
+
+        # Valid: Rectangle
+        rectangle = Model(shape={"type": "rectangle", "width": 10, "height": 20})
+        self.assertEqual(rectangle.shape.type, "rectangle")
+        self.assertEqual(rectangle.shape.width, 10)
+        self.assertEqual(rectangle.shape.height, 20)
+
+        # Invalid: Wrong properties for the type
+        with self.assertRaises(ValidationError):
+            Model(shape={"type": "circle", "width": 10})
+
+    def test_oneof_with_examples(self):
+        schema = {
+            "title": "ExampleTest",
+            "type": "object",
+            "properties": {
+                "value": {
+                    "oneOf": [
+                        {
+                            "type": "string",
+                            "examples": ["example1", "example2"],
+                        },
+                        {
+                            "type": "integer",
+                            "examples": [1, 2, 3],
+                        },
+                    ]
+                }
+            },
+            "required": ["value"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        # Since Pydantic does not natively support oneOf and the validation
+        # is done via a custom validator, the `value` is represented using `anyOf`
+        model_schema = Model.model_json_schema()
+
+        self.assertEqual(
+            model_schema["properties"]["value"]["anyOf"][0]["examples"],
+            ["example1", "example2"],
+        )
+
+        self.assertEqual(
+            model_schema["properties"]["value"]["anyOf"][1]["examples"],
+            [1, 2, 3],
+        )
+
+    def test_oneof_with_root_examples(self):
+        schema = {
+            "title": "ExampleTest",
+            "type": "object",
+            "properties": {
+                "value": {
+                    "oneOf": [
+                        {
+                            "type": "string",
+                        },
+                        {
+                            "type": "integer",
+                        },
+                    ],
+                    "examples": ["example1", 2],
+                }
+            },
+            "required": ["value"],
+        }
+
+        Model = SchemaConverter.build(schema)
+
+        # Since Pydantic does not natively support oneOf and the validation
+        # is done via a custom validator, the `value` is represented using `anyOf`
+        model_schema = Model.model_json_schema()
+
+        self.assertEqual(
+            model_schema["properties"]["value"]["examples"],
+            ["example1", 2],
+        )

tests/parser/test_ref_type_parser.py

@@ -1,6 +1,9 @@
+from jambo.exceptions import InternalAssertionException, InvalidSchemaException
 from jambo.parser import ObjectTypeParser, RefTypeParser
 
-from typing import ForwardRef
+from pydantic import ValidationError
+from typing_extensions import ForwardRef
+
 from unittest import TestCase
 
 
@@ -16,7 +19,7 @@ class TestRefTypeParser(TestCase):
             "required": ["name", "age"],
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             RefTypeParser().from_properties(
                 "person",
                 properties,
@@ -40,7 +43,7 @@ class TestRefTypeParser(TestCase):
             },
         }
 
-        with self.assertRaises(RuntimeError):
+        with self.assertRaises(InternalAssertionException):
             RefTypeParser().from_properties(
                 "person",
                 properties,
@@ -63,7 +66,7 @@ class TestRefTypeParser(TestCase):
             },
         }
 
-        with self.assertRaises(RuntimeError):
+        with self.assertRaises(InternalAssertionException):
             RefTypeParser().from_properties(
                 "person",
                 properties,
@@ -77,7 +80,7 @@ class TestRefTypeParser(TestCase):
             "$ref": "https://example.com/schemas/person.json",
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             RefTypeParser().from_properties(
                 "person",
                 properties,
@@ -110,7 +113,7 @@ class TestRefTypeParser(TestCase):
             },
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             ObjectTypeParser().from_properties(
                 "person",
                 properties,
@@ -126,7 +129,7 @@ class TestRefTypeParser(TestCase):
             "$defs": {},
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             RefTypeParser().from_properties(
                 "person",
                 properties,
@@ -142,7 +145,7 @@ class TestRefTypeParser(TestCase):
             "$defs": {"person": None},
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             RefTypeParser().from_properties(
                 "person",
                 properties,
@@ -232,7 +235,7 @@ class TestRefTypeParser(TestCase):
             "required": ["name", "age"],
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             ObjectTypeParser().from_properties(
                 "person",
                 properties,
@@ -264,7 +267,7 @@ class TestRefTypeParser(TestCase):
         )
 
         # checks if when created via FowardRef the model is validated correctly.
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(
                 name="John",
                 age=30,
@@ -421,7 +424,7 @@ class TestRefTypeParser(TestCase):
             },
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             ref_strategy, ref_name, ref_property = RefTypeParser()._parse_from_strategy(
                 "invalid_strategy",
                 "person",
@@ -482,3 +485,38 @@ class TestRefTypeParser(TestCase):
 
         self.assertEqual(obj.name, "John")
         self.assertEqual(obj.age, 30)
+
+    def test_ref_type_parser_with_def_with_examples(self):
+        properties = {
+            "title": "person",
+            "$ref": "#/$defs/person",
+            "$defs": {
+                "person": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "age": {"type": "integer"},
+                    },
+                }
+            },
+            "examples": [
+                {"name": "John", "age": 30},
+                {"name": "Jane", "age": 25},
+            ],
+        }
+
+        _, type_validator = RefTypeParser().from_properties(
+            "person",
+            properties,
+            context=properties,
+            ref_cache={},
+            required=True,
+        )
+
+        self.assertEqual(
+            type_validator.get("examples"),
+            [
+                {"name": "John", "age": 30},
+                {"name": "Jane", "age": 25},
+            ],
+        )

tests/parser/test_string_type_parser.py

@@ -1,9 +1,12 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser import StringTypeParser
 
-from pydantic import EmailStr, HttpUrl, IPvAnyAddress
+from pydantic import AnyUrl, EmailStr
 
-from datetime import date, datetime, time
+from datetime import date, datetime, time, timedelta, timezone
+from ipaddress import IPv4Address, IPv6Address, ip_address
 from unittest import TestCase
+from uuid import UUID
 
 
 class TestStringTypeParser(TestCase):
@@ -24,6 +27,7 @@ class TestStringTypeParser(TestCase):
             "maxLength": 10,
             "minLength": 1,
             "pattern": "^[a-zA-Z]+$",
+            "examples": ["test", "TEST"],
         }
 
         type_parsing, type_validator = parser.from_properties("placeholder", properties)
@@ -32,6 +36,7 @@ class TestStringTypeParser(TestCase):
         self.assertEqual(type_validator["max_length"], 10)
         self.assertEqual(type_validator["min_length"], 1)
         self.assertEqual(type_validator["pattern"], "^[a-zA-Z]+$")
+        self.assertEqual(type_validator["examples"], ["test", "TEST"])
 
     def test_string_parser_with_default_value(self):
         parser = StringTypeParser()
@@ -60,7 +65,7 @@ class TestStringTypeParser(TestCase):
             "minLength": 5,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_string_parser_with_default_invalid_maxlength(self):
@@ -73,7 +78,7 @@ class TestStringTypeParser(TestCase):
             "minLength": 1,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_string_parser_with_default_invalid_minlength(self):
@@ -86,7 +91,7 @@ class TestStringTypeParser(TestCase):
             "minLength": 2,
         }
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             parser.from_properties("placeholder", properties)
 
     def test_string_parser_with_email_format(self):
@@ -95,11 +100,13 @@ class TestStringTypeParser(TestCase):
         properties = {
             "type": "string",
             "format": "email",
+            "examples": ["test@example.com"],
         }
 
         type_parsing, type_validator = parser.from_properties("placeholder", properties)
 
         self.assertEqual(type_parsing, EmailStr)
+        self.assertEqual(type_validator["examples"], ["test@example.com"])
 
     def test_string_parser_with_uri_format(self):
         parser = StringTypeParser()
@@ -107,26 +114,53 @@ class TestStringTypeParser(TestCase):
         properties = {
             "type": "string",
             "format": "uri",
+            "examples": ["test://domain/resource"],
         }
 
         type_parsing, type_validator = parser.from_properties("placeholder", properties)
 
-        self.assertEqual(type_parsing, HttpUrl)
+        self.assertEqual(type_parsing, AnyUrl)
+        self.assertEqual(type_validator["examples"], [AnyUrl("test://domain/resource")])
 
     def test_string_parser_with_ip_formats(self):
         parser = StringTypeParser()
 
-        for ip_format in ["ipv4", "ipv6"]:
+        formats = {"ipv4": IPv4Address, "ipv6": IPv6Address}
+        examples = {"ipv4": ["192.168.1.1"], "ipv6": ["::1"]}
+
+        for ip_format, expected_type in formats.items():
+            example = examples[ip_format]
+
             properties = {
                 "type": "string",
                 "format": ip_format,
+                "examples": example,
             }
 
             type_parsing, type_validator = parser.from_properties(
                 "placeholder", properties
             )
 
-            self.assertEqual(type_parsing, IPvAnyAddress)
+            self.assertEqual(type_parsing, expected_type)
+            self.assertEqual(
+                type_validator["examples"], [ip_address(e) for e in example]
+            )
+
+    def test_string_parser_with_uuid_format(self):
+        parser = StringTypeParser()
+
+        properties = {
+            "type": "string",
+            "format": "uuid",
+            "examples": ["ab71aaf4-ab6e-43cd-a369-cebdd9f7a4c6"],
+        }
+
+        type_parsing, type_validator = parser.from_properties("placeholder", properties)
+
+        self.assertEqual(type_parsing, UUID)
+        self.assertEqual(
+            type_validator["examples"], [UUID("ab71aaf4-ab6e-43cd-a369-cebdd9f7a4c6")]
+        )
 
     def test_string_parser_with_time_format(self):
         parser = StringTypeParser()
@@ -134,19 +168,33 @@ class TestStringTypeParser(TestCase):
         properties = {
             "type": "string",
             "format": "time",
+            "examples": ["14:30:00", "09:15:30.500", "10:00:00+02:00"],
         }
 
         type_parsing, type_validator = parser.from_properties("placeholder", properties)
 
         self.assertEqual(type_parsing, time)
+        self.assertEqual(
+            type_validator["examples"],
+            [
+                time(hour=14, minute=30, second=0),
+                time(hour=9, minute=15, second=30, microsecond=500_000),
+                time(hour=10, minute=0, second=0, tzinfo=timezone(timedelta(hours=2))),
+            ],
+        )
 
     def test_string_parser_with_pattern_based_formats(self):
         parser = StringTypeParser()
 
-        for format_type in ["hostname"]:
+        format_types = {
+            "hostname": "example.com",
+        }
+
+        for format_type, example_type in format_types.items():
             properties = {
                 "type": "string",
                 "format": format_type,
+                "examples": [example_type],
             }
 
             type_parsing, type_validator = parser.from_properties(
@@ -158,6 +206,7 @@ class TestStringTypeParser(TestCase):
             self.assertEqual(
                 type_validator["pattern"], parser.format_pattern_mapping[format_type]
             )
+            self.assertEqual(type_validator["examples"], [example_type])
 
     def test_string_parser_with_unsupported_format(self):
         parser = StringTypeParser()
@@ -167,11 +216,12 @@ class TestStringTypeParser(TestCase):
             "format": "unsupported-format",
         }
 
-        with self.assertRaises(ValueError) as context:
+        with self.assertRaises(InvalidSchemaException) as context:
             parser.from_properties("placeholder", properties)
 
         self.assertEqual(
-            str(context.exception), "Unsupported string format: unsupported-format"
+            str(context.exception),
+            "Invalid JSON Schema: Unsupported string format: unsupported-format (invalid field: format)",
         )
 
     def test_string_parser_with_date_format(self):
@@ -180,11 +230,20 @@ class TestStringTypeParser(TestCase):
         properties = {
             "type": "string",
             "format": "date",
+            "examples": ["2025-11-17", "1999-12-31", "2000-01-01"],
         }
 
         type_parsing, type_validator = parser.from_properties("placeholder", properties)
 
         self.assertEqual(type_parsing, date)
+        self.assertEqual(
+            type_validator["examples"],
+            [
+                date(year=2025, month=11, day=17),
+                date(year=1999, month=12, day=31),
+                date(year=2000, month=1, day=1),
+            ],
+        )
 
     def test_string_parser_with_datetime_format(self):
         parser = StringTypeParser()
@@ -192,8 +251,71 @@ class TestStringTypeParser(TestCase):
         properties = {
             "type": "string",
             "format": "date-time",
+            "examples": [
+                "2025-11-17T11:15:00",
+                "2025-11-17T11:15:00+01:00",
+                "2025-11-17T11:15:00.123456-05:00",
+            ],
         }
 
         type_parsing, type_validator = parser.from_properties("placeholder", properties)
 
         self.assertEqual(type_parsing, datetime)
+        self.assertEqual(
+            type_validator["examples"],
+            [
+                datetime(year=2025, month=11, day=17, hour=11, minute=15, second=0),
+                datetime(
+                    year=2025,
+                    month=11,
+                    day=17,
+                    hour=11,
+                    minute=15,
+                    second=0,
+                    tzinfo=timezone(timedelta(hours=1)),
+                ),
+                datetime(
+                    year=2025,
+                    month=11,
+                    day=17,
+                    hour=11,
+                    minute=15,
+                    second=0,
+                    microsecond=123456,
+                    tzinfo=timezone(timedelta(hours=-5)),
+                ),
+            ],
+        )
+
+    def test_string_parser_with_invalid_example_value(self):
+        with self.assertRaises(InvalidSchemaException):
+            StringTypeParser().from_properties(
+                "placeholder",
+                {
+                    "type": "string",
+                    "format": "email",
+                    "examples": ["invalid-email"],
+                },
+            )
+
+    def test_string_parser_with_timedelta_format(self):
+        parser = StringTypeParser()
+
+        properties = {
+            "type": "string",
+            "format": "duration",
+            "examples": ["P1Y2M3DT4H5M6S", "PT30M", "P7D", "PT0.5S"],
+        }
+
+        type_parsing, type_validator = parser.from_properties("placeholder", properties)
+
+        self.assertEqual(type_parsing, timedelta)
+        self.assertEqual(
+            type_validator["examples"],
+            [
+                timedelta(days=428, hours=4, minutes=5, seconds=6),
+                timedelta(minutes=30),
+                timedelta(days=7),
+                timedelta(seconds=0.5),
+            ],
+        )

tests/parser/test_type_parser.py

@@ -1,3 +1,4 @@
+from jambo.exceptions import InvalidSchemaException
 from jambo.parser import StringTypeParser
 from jambo.parser._type_parser import GenericTypeParser
 
@@ -17,5 +18,16 @@ class TestGenericTypeParser(TestCase):
         StringTypeParser.json_schema_type = "type:string"
 
     def test_get_impl_invalid_type(self):
-        with self.assertRaises(ValueError):
+        with self.assertRaises(InvalidSchemaException):
             GenericTypeParser._get_impl({"type": "invalid_type"})
+
+    def test_invalid_examples_not_list(self):
+        parser = StringTypeParser()
+
+        properties = {
+            "type": "integer",
+            "examples": "this should be a list",
+        }
+
+        with self.assertRaises(InvalidSchemaException):
+            parser.from_properties("placeholder", properties)

tests/test_schema_converter.py

@@ -1,9 +1,13 @@
 from jambo import SchemaConverter
+from jambo.exceptions import InvalidSchemaException, UnsupportedSchemaException
+from jambo.types import JSONSchema
 
-from pydantic import BaseModel, HttpUrl
+from pydantic import AnyUrl, BaseModel, ValidationError
+from typing_extensions import get_args
 
 from ipaddress import IPv4Address, IPv6Address
 from unittest import TestCase
+from uuid import UUID
 
 
 def is_pydantic_model(cls):
@@ -11,6 +15,12 @@ def is_pydantic_model(cls):
 
 
 class TestSchemaConverter(TestCase):
+    def setUp(self):
+        self.converter = SchemaConverter()
+
+    def tearDown(self):
+        self.converter.clear_ref_cache(namespace=None)
+
     def test_invalid_schema(self):
         schema = {
             "title": 1,
@@ -22,8 +32,22 @@ class TestSchemaConverter(TestCase):
             },
         }
 
-        with self.assertRaises(ValueError):
-            SchemaConverter.build(schema)
+        with self.assertRaises(InvalidSchemaException):
+            self.converter.build_with_cache(schema)
+
+    def test_invalid_schema_type(self):
+        schema = {
+            "title": 1,
+            "description": "A person",
+            "type": 1,
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+            },
+        }
+
+        with self.assertRaises(InvalidSchemaException):
+            self.converter.build_with_cache(schema)
 
     def test_build_expects_title(self):
         schema = {
@@ -35,8 +59,8 @@ class TestSchemaConverter(TestCase):
             },
         }
 
-        with self.assertRaises(ValueError):
-            SchemaConverter.build(schema)
+        with self.assertRaises(InvalidSchemaException):
+            self.converter.build_with_cache(schema)
 
     def test_build_expects_object(self):
         schema = {
@@ -45,8 +69,8 @@ class TestSchemaConverter(TestCase):
             "type": "string",
         }
 
-        with self.assertRaises(TypeError):
-            SchemaConverter.build(schema)
+        with self.assertRaises(UnsupportedSchemaException):
+            self.converter.build_with_cache(schema)
 
     def test_is_invalid_field(self):
         schema = {
@@ -61,8 +85,8 @@ class TestSchemaConverter(TestCase):
             # 'required': ['name', 'age', 'is_active', 'friends', 'address'],
         }
 
-        with self.assertRaises(ValueError) as context:
-            SchemaConverter.build(schema)
+        with self.assertRaises(InvalidSchemaException) as context:
+            self.converter.build_with_cache(schema)
             self.assertTrue("Unknown type" in str(context.exception))
 
     def test_jsonschema_to_pydantic(self):
@@ -77,7 +101,7 @@ class TestSchemaConverter(TestCase):
             "required": ["name"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         self.assertTrue(is_pydantic_model(model))
 
@@ -98,20 +122,20 @@ class TestSchemaConverter(TestCase):
             "required": ["name"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         self.assertEqual(model(name="John", age=30).name, "John")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(name=123, age=30, email="teste@hideyoshi.com")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(name="John Invalid", age=45, email="teste@hideyoshi.com")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(name="", age=45, email="teste@hideyoshi.com")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(name="John", age=45, email="hideyoshi.com")
 
     def test_validation_integer(self):
@@ -129,14 +153,14 @@ class TestSchemaConverter(TestCase):
             "required": ["age"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         self.assertEqual(model(age=30).age, 30)
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(age=-1)
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(age=121)
 
     def test_validation_float(self):
@@ -154,14 +178,14 @@ class TestSchemaConverter(TestCase):
             "required": ["age"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         self.assertEqual(model(age=30).age, 30.0)
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(age=-1.0)
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(age=121.0)
 
     def test_validation_boolean(self):
@@ -175,13 +199,13 @@ class TestSchemaConverter(TestCase):
             "required": ["is_active"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         self.assertEqual(model(is_active=True).is_active, True)
 
         self.assertEqual(model(is_active="true").is_active, True)
 
-    def test_validation_list(self):
+    def test_validation_list_with_valid_items(self):
         schema = {
             "title": "Person",
             "description": "A person",
@@ -198,18 +222,39 @@ class TestSchemaConverter(TestCase):
             "required": ["friends"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         self.assertEqual(
             model(friends=["John", "Jane", "John"]).friends, {"John", "Jane"}
         )
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(friends=[])
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             model(friends=["John", "Jane", "Invalid"])
 
+    def test_validation_list_with_missing_items(self):
+        model = self.converter.build_with_cache(
+            {
+                "title": "Person",
+                "description": "A person",
+                "type": "object",
+                "properties": {
+                    "friends": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "minItems": 1,
+                        "maxItems": 2,
+                    },
+                },
+                "required": ["friends"],
+            }
+        )
+
+        with self.assertRaises(ValidationError):
+            model()
+
     def test_validation_object(self):
         schema = {
             "title": "Person",
@@ -228,13 +273,17 @@ class TestSchemaConverter(TestCase):
             "required": ["address"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
+        self.assertEqual(model.__doc__, "A person")
 
         obj = model(address={"street": "123 Main St", "city": "Springfield"})
 
         self.assertEqual(obj.address.street, "123 Main St")
         self.assertEqual(obj.address.city, "Springfield")
 
+        with self.assertRaises(ValidationError):
+            model()
+
     def test_default_for_string(self):
         schema = {
             "title": "Person",
@@ -249,7 +298,7 @@ class TestSchemaConverter(TestCase):
             "required": ["name"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         obj = model(name="John")
 
@@ -271,8 +320,8 @@ class TestSchemaConverter(TestCase):
             "required": ["name"],
         }
 
-        with self.assertRaises(ValueError):
-            SchemaConverter.build(schema_max_length)
+        with self.assertRaises(InvalidSchemaException):
+            self.converter.build_with_cache(schema_max_length)
 
     def test_default_for_list(self):
         schema_list = {
@@ -289,10 +338,11 @@ class TestSchemaConverter(TestCase):
             "required": ["friends"],
         }
 
-        model_list = SchemaConverter.build(schema_list)
+        model_list = self.converter.build_with_cache(schema_list)
 
         self.assertEqual(model_list().friends, ["John", "Jane"])
 
+    def test_default_for_list_with_unique_items(self):
         # Test for default with uniqueItems
         schema_set = {
             "title": "Person",
@@ -309,7 +359,7 @@ class TestSchemaConverter(TestCase):
             "required": ["friends"],
         }
 
-        model_set = SchemaConverter.build(schema_set)
+        model_set = self.converter.build_with_cache(schema_set)
 
         self.assertEqual(model_set().friends, {"John", "Jane"})
 
@@ -331,7 +381,7 @@ class TestSchemaConverter(TestCase):
             "required": ["address"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         obj = model(address={"street": "123 Main St", "city": "Springfield"})
 
@@ -355,7 +405,7 @@ class TestSchemaConverter(TestCase):
             },
         }
 
-        Model = SchemaConverter.build(schema)
+        Model = self.converter.build_with_cache(schema)
 
         obj = Model(
             name="J",
@@ -363,10 +413,10 @@ class TestSchemaConverter(TestCase):
 
         self.assertEqual(obj.name, "J")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             Model(name="John Invalid")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             Model(name="")
 
     def test_any_of(self):
@@ -384,7 +434,7 @@ class TestSchemaConverter(TestCase):
             },
         }
 
-        Model = SchemaConverter.build(schema)
+        Model = self.converter.build_with_cache(schema)
 
         obj = Model(id=1)
         self.assertEqual(obj.id, 1)
@@ -392,13 +442,13 @@ class TestSchemaConverter(TestCase):
         obj = Model(id="12345678901")
         self.assertEqual(obj.id, "12345678901")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             Model(id="")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             Model(id="12345678901234567890")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             Model(id=11)
 
     def test_string_format_email(self):
@@ -407,9 +457,11 @@ class TestSchemaConverter(TestCase):
             "type": "object",
             "properties": {"email": {"type": "string", "format": "email"}},
         }
-        model = SchemaConverter.build(schema)
+
+        model = self.converter.build_with_cache(schema)
         self.assertEqual(model(email="test@example.com").email, "test@example.com")
-        with self.assertRaises(ValueError):
+
+        with self.assertRaises(ValidationError):
             model(email="invalid-email")
 
     def test_string_format_uri(self):
@@ -418,11 +470,13 @@ class TestSchemaConverter(TestCase):
             "type": "object",
             "properties": {"website": {"type": "string", "format": "uri"}},
         }
-        model = SchemaConverter.build(schema)
+
+        model = self.converter.build_with_cache(schema)
         self.assertEqual(
-            model(website="https://example.com").website, HttpUrl("https://example.com")
+            model(website="https://example.com").website, AnyUrl("https://example.com")
         )
-        with self.assertRaises(ValueError):
+
+        with self.assertRaises(ValidationError):
             model(website="invalid-uri")
 
     def test_string_format_ipv4(self):
@@ -431,9 +485,11 @@ class TestSchemaConverter(TestCase):
             "type": "object",
             "properties": {"ip": {"type": "string", "format": "ipv4"}},
         }
-        model = SchemaConverter.build(schema)
+
+        model = self.converter.build_with_cache(schema)
         self.assertEqual(model(ip="192.168.1.1").ip, IPv4Address("192.168.1.1"))
-        with self.assertRaises(ValueError):
+
+        with self.assertRaises(ValidationError):
             model(ip="256.256.256.256")
 
     def test_string_format_ipv6(self):
@@ -442,23 +498,44 @@ class TestSchemaConverter(TestCase):
             "type": "object",
             "properties": {"ip": {"type": "string", "format": "ipv6"}},
         }
-        model = SchemaConverter.build(schema)
+
+        model = self.converter.build_with_cache(schema)
         self.assertEqual(
             model(ip="2001:0db8:85a3:0000:0000:8a2e:0370:7334").ip,
             IPv6Address("2001:0db8:85a3:0000:0000:8a2e:0370:7334"),
         )
-        with self.assertRaises(ValueError):
+
+        with self.assertRaises(ValidationError):
             model(ip="invalid-ipv6")
 
+    def test_string_format_uuid(self):
+        schema = {
+            "title": "UUIDTest",
+            "type": "object",
+            "properties": {"id": {"type": "string", "format": "uuid"}},
+        }
+
+        model = self.converter.build_with_cache(schema)
+
+        self.assertEqual(
+            model(id="123e4567-e89b-12d3-a456-426614174000").id,
+            UUID("123e4567-e89b-12d3-a456-426614174000"),
+        )
+
+        with self.assertRaises(ValidationError):
+            model(id="invalid-uuid")
+
     def test_string_format_hostname(self):
         schema = {
             "title": "HostnameTest",
             "type": "object",
             "properties": {"hostname": {"type": "string", "format": "hostname"}},
         }
-        model = SchemaConverter.build(schema)
+
+        model = self.converter.build_with_cache(schema)
         self.assertEqual(model(hostname="example.com").hostname, "example.com")
-        with self.assertRaises(ValueError):
+
+        with self.assertRaises(ValidationError):
             model(hostname="invalid..hostname")
 
     def test_string_format_datetime(self):
@@ -467,12 +544,14 @@ class TestSchemaConverter(TestCase):
             "type": "object",
             "properties": {"timestamp": {"type": "string", "format": "date-time"}},
         }
-        model = SchemaConverter.build(schema)
+
+        model = self.converter.build_with_cache(schema)
         self.assertEqual(
             model(timestamp="2024-01-01T12:00:00Z").timestamp.isoformat(),
             "2024-01-01T12:00:00+00:00",
         )
-        with self.assertRaises(ValueError):
+
+        with self.assertRaises(ValidationError):
             model(timestamp="invalid-datetime")
 
     def test_string_format_time(self):
@@ -481,11 +560,13 @@ class TestSchemaConverter(TestCase):
             "type": "object",
             "properties": {"time": {"type": "string", "format": "time"}},
         }
-        model = SchemaConverter.build(schema)
+
+        model = self.converter.build_with_cache(schema)
         self.assertEqual(
             model(time="20:20:39+00:00").time.isoformat(), "20:20:39+00:00"
         )
-        with self.assertRaises(ValueError):
+
+        with self.assertRaises(ValidationError):
             model(time="25:00:00")
 
     def test_string_format_unsupported(self):
@@ -494,8 +575,9 @@ class TestSchemaConverter(TestCase):
             "type": "object",
             "properties": {"field": {"type": "string", "format": "unsupported"}},
         }
-        with self.assertRaises(ValueError):
-            SchemaConverter.build(schema)
+
+        with self.assertRaises(InvalidSchemaException):
+            self.converter.build_with_cache(schema)
 
     def test_ref_with_root_ref(self):
         schema = {
@@ -511,7 +593,7 @@ class TestSchemaConverter(TestCase):
             "required": ["name", "age"],
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         obj = model(
             name="John",
@@ -546,7 +628,7 @@ class TestSchemaConverter(TestCase):
             },
         }
 
-        model = SchemaConverter.build(schema)
+        model = self.converter.build_with_cache(schema)
 
         obj = model(
             name="John",
@@ -585,7 +667,7 @@ class TestSchemaConverter(TestCase):
             },
         }
 
-        Model = SchemaConverter.build(schema)
+        Model = self.converter.build_with_cache(schema)
 
         obj = Model(
             name="John",
@@ -611,7 +693,7 @@ class TestSchemaConverter(TestCase):
             "required": ["status"],
         }
 
-        Model = SchemaConverter.build(schema)
+        Model = self.converter.build_with_cache(schema)
 
         obj = Model(status="active")
         self.assertEqual(obj.status.value, "active")
@@ -630,7 +712,7 @@ class TestSchemaConverter(TestCase):
             "required": ["status"],
         }
 
-        Model = SchemaConverter.build(schema)
+        Model = self.converter.build_with_cache(schema)
 
         obj = Model()
         self.assertEqual(obj.status.value, "active")
@@ -647,13 +729,445 @@ class TestSchemaConverter(TestCase):
             "required": ["name"],
         }
 
-        Model = SchemaConverter.build(schema)
+        Model = self.converter.build_with_cache(schema)
 
         obj = Model()
         self.assertEqual(obj.name, "United States of America")
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             obj.name = "Canada"
 
-        with self.assertRaises(ValueError):
+        with self.assertRaises(ValidationError):
             Model(name="Canada")
+
+    def test_const_type_parser_with_non_hashable_value(self):
+        schema = {
+            "title": "Country",
+            "type": "object",
+            "properties": {
+                "name": {
+                    "const": ["Brazil"],
+                }
+            },
+            "required": ["name"],
+        }
+
+        Model = self.converter.build_with_cache(schema)
+
+        obj = Model()
+        self.assertEqual(obj.name, ["Brazil"])
+
+        with self.assertRaises(ValidationError):
+            obj.name = ["Argentina"]
+
+        with self.assertRaises(ValidationError):
+            Model(name=["Argentina"])
+
+    def test_null_type_parser(self):
+        schema = {
+            "title": "Test",
+            "type": "object",
+            "properties": {
+                "a_thing": {"type": "null"},
+            },
+        }
+
+        Model = self.converter.build_with_cache(schema)
+
+        obj = Model()
+        self.assertIsNone(obj.a_thing)
+
+        obj = Model(a_thing=None)
+        self.assertIsNone(obj.a_thing)
+
+        with self.assertRaises(ValidationError):
+            Model(a_thing="not none")
+
+    def test_scoped_ref_schema(self):
+        schema: JSONSchema = {
+            "title": "Example Schema",
+            "type": "object",
+            "properties": {
+                "operating_system": {
+                    "oneOf": [
+                        {"$ref": "#/$defs/operating_system"},
+                        {
+                            "type": "object",
+                            "properties": {
+                                "creation": {"$ref": "#/$defs/operating_system"},
+                                "reinstallation": {"$ref": "#/$defs/operating_system"},
+                            },
+                            "required": ["creation", "reinstallation"],
+                        },
+                    ]
+                },
+            },
+            "$defs": {
+                "operating_system": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "version": {"type": "string"},
+                    },
+                    "required": ["name", "version"],
+                }
+            },
+        }
+
+        schema_type = self.converter.build_with_cache(schema)
+
+        # check for me that the types generated by the oneOf in the typing.Annotated have different names
+        operating_system_field = schema_type.model_fields["operating_system"]
+
+        arg1, arg2 = get_args(operating_system_field.annotation)
+
+        first_type = get_args(arg1)[0]
+        second_type = get_args(arg2)[0]
+
+        self.assertNotEqual(first_type.__name__, second_type.__name__)
+
+    def test_object_invalid_require(self):
+        # https://github.com/HideyoshiNakazone/jambo/issues/60
+        object_ = self.converter.build_with_cache(
+            {
+                "$schema": "https://json-schema.org/draft/2020-12/schema",
+                "title": "TEST",
+                "type": "object",
+                "required": ["title"],
+                "properties": {
+                    "title": {
+                        "type": "string",
+                        "description": "The title of the object",
+                    },
+                    "description": {
+                        "type": "object",
+                        "properties": {
+                            "summary": {
+                                "type": "string",
+                            },
+                            "details": {
+                                "type": "string",
+                            },
+                        },
+                    },
+                },
+            }
+        )
+
+        self.assertFalse(object_.model_fields["description"].is_required())  # FAIL
+
+    def test_instance_level_ref_cache(self):
+        ref_cache = {}
+
+        schema = {
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "emergency_contact": {
+                    "$ref": "#",
+                },
+            },
+            "required": ["name", "age"],
+        }
+
+        converter1 = SchemaConverter(ref_cache)
+        model1 = converter1.build_with_cache(schema)
+
+        converter2 = SchemaConverter(ref_cache)
+        model2 = converter2.build_with_cache(schema)
+
+        self.assertIs(model1, model2)
+
+    def test_instance_level_ref_cache_isolation_via_without_cache_param(self):
+        schema = {
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "emergency_contact": {
+                    "$ref": "#",
+                },
+            },
+            "required": ["name", "age"],
+        }
+
+        model1 = self.converter.build_with_cache(schema, without_cache=True)
+        model2 = self.converter.build_with_cache(schema, without_cache=True)
+
+        self.assertIsNot(model1, model2)
+
+    def test_instance_level_ref_cache_isolation_via_provided_cache(self):
+        schema = {
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "emergency_contact": {
+                    "$ref": "#",
+                },
+            },
+            "required": ["name", "age"],
+        }
+
+        model1 = self.converter.build_with_cache(schema, ref_cache={})
+        model2 = self.converter.build_with_cache(schema, ref_cache={})
+
+        self.assertIsNot(model1, model2)
+
+    def test_get_type_from_cache(self):
+        schema = {
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "emergency_contact": {
+                    "$ref": "#",
+                },
+            },
+            "required": ["name", "age"],
+        }
+
+        model = self.converter.build_with_cache(schema)
+
+        cached_model = self.converter.get_cached_ref("Person")
+
+        self.assertIs(model, cached_model)
+
+    def test_get_type_from_cache_not_found(self):
+        cached_model = self.converter.get_cached_ref("NonExistentModel")
+
+        self.assertIsNone(cached_model)
+
+    def test_get_type_from_cache_nested_type(self):
+        schema = {
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "address": {
+                    "type": "object",
+                    "properties": {
+                        "street": {"type": "string"},
+                        "city": {"type": "string"},
+                    },
+                    "required": ["street", "city"],
+                },
+            },
+            "required": ["name", "age", "address"],
+        }
+
+        model = self.converter.build_with_cache(schema)
+
+        cached_model = self.converter.get_cached_ref("Person.address")
+
+        self.assertIsNotNone(cached_model)
+        self.assertIs(model.model_fields["address"].annotation, cached_model)
+
+    def test_get_type_from_cache_with_def(self):
+        schema = {
+            "title": "person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "address": {"$ref": "#/$defs/address"},
+            },
+            "$defs": {
+                "address": {
+                    "type": "object",
+                    "properties": {
+                        "street": {"type": "string"},
+                        "city": {"type": "string"},
+                    },
+                    "required": ["street", "city"],
+                }
+            },
+        }
+
+        person_model = self.converter.build_with_cache(schema)
+        cached_person_model = self.converter.get_cached_ref("person")
+
+        self.assertIs(person_model, cached_person_model)
+
+        cached_address_model = self.converter.get_cached_ref("address")
+
+        self.assertIsNotNone(cached_address_model)
+
+    def test_parse_list_type_multiple_values(self):
+        schema = {
+            "title": "TestListType",
+            "type": "object",
+            "properties": {"values": {"type": ["string", "number"]}},
+        }
+
+        Model = self.converter.build_with_cache(schema)
+
+        obj1 = Model(values="a string")
+        self.assertEqual(obj1.values, "a string")
+
+        obj2 = Model(values=42)
+        self.assertEqual(obj2.values, 42)
+
+    def test_parse_list_type_one_value(self):
+        schema = {
+            "title": "TestListType",
+            "type": "object",
+            "properties": {"values": {"type": ["string"]}},
+        }
+
+        Model = self.converter.build_with_cache(schema)
+
+        obj1 = Model(values="a string")
+        self.assertEqual(obj1.values, "a string")
+
+    def test_parse_list_type_empty(self):
+        schema = {
+            "title": "TestListType",
+            "type": "object",
+            "properties": {"values": {"type": []}},
+        }
+
+        with self.assertRaises(InvalidSchemaException):
+            self.converter.build_with_cache(schema)
+
+    def test_parse_list_type_root_level_throws(self):
+        schema = {"title": "TestListType", "type": ["string", "number"]}
+
+        with self.assertRaises(InvalidSchemaException):
+            self.converter.build_with_cache(schema)
+
+    def tests_instance_level_ref_cache_isolation_via_property_id(self):
+        schema1: JSONSchema = {
+            "$id": "http://example.com/schemas/person1.json",
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "emergency_contact": {
+                    "$ref": "#",
+                },
+            },
+            "required": ["name", "age"],
+        }
+
+        model1 = self.converter.build_with_cache(schema1)
+
+        schema2: JSONSchema = {
+            "$id": "http://example.com/schemas/person2.json",
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "address": {"type": "string"},
+            },
+            "required": ["name", "age", "address"],
+        }
+
+        model2 = self.converter.build_with_cache(schema2)
+
+        self.assertIsNot(model1, model2)
+
+    def tests_instance_level_ref_cache_colision_when_same_property_id(self):
+        schema1: JSONSchema = {
+            "$id": "http://example.com/schemas/person.json",
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "emergency_contact": {
+                    "$ref": "#",
+                },
+            },
+            "required": ["name", "age"],
+        }
+
+        model1 = self.converter.build_with_cache(schema1)
+
+        schema2: JSONSchema = {
+            "$id": "http://example.com/schemas/person.json",
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "address": {"type": "string"},
+            },
+            "required": ["name", "age", "address"],
+        }
+
+        model2 = self.converter.build_with_cache(schema2)
+
+        self.assertIs(model1, model2)
+
+    def test_namespace_isolation_via_on_call_config(self):
+        namespace = "namespace1"
+
+        schema: JSONSchema = {
+            "$id": namespace,
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "address": {
+                    "type": "object",
+                    "properties": {
+                        "street": {"type": "string"},
+                        "city": {"type": "string"},
+                    },
+                    "required": ["street", "city"],
+                },
+            },
+            "required": ["name", "age", "address"],
+        }
+
+        model = self.converter.build_with_cache(schema)
+
+        invalid_cached_model = self.converter.get_cached_ref("Person")
+        self.assertIsNone(invalid_cached_model)
+
+        cached_model = self.converter.get_cached_ref("Person", namespace=namespace)
+        self.assertIs(model, cached_model)
+
+    def test_clear_namespace_registry(self):
+        namespace = "namespace_to_clear"
+
+        schema: JSONSchema = {
+            "$id": namespace,
+            "title": "Person",
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer"},
+                "address": {
+                    "type": "object",
+                    "properties": {
+                        "street": {"type": "string"},
+                        "city": {"type": "string"},
+                    },
+                    "required": ["street", "city"],
+                },
+            },
+            "required": ["name", "age", "address"],
+        }
+
+        model = self.converter.build_with_cache(schema)
+
+        cached_model = self.converter.get_cached_ref("Person", namespace=namespace)
+        self.assertIs(model, cached_model)
+
+        self.converter.clear_ref_cache(namespace=namespace)
+
+        cleared_cached_model = self.converter.get_cached_ref(
+            "Person", namespace=namespace
+        )
+        self.assertIsNone(cleared_cached_model)