voluptuous-openapi 0.2.0__tar.gz → 0.4.0__tar.gz

{voluptuous_openapi-0.2.0/voluptuous_openapi.egg-info → voluptuous_openapi-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voluptuous-openapi
-Version: 0.2.0
+Version: 0.4.0
 Summary: Convert voluptuous schemas to OpenAPI Schema object
 Author-email: Denis Shulyaka <Shulyaka@gmail.com>
 License-Expression: Apache-2.0
@@ -55,7 +55,7 @@ You can pass a custom serializer to be able to process custom validators. If the
 
 ```python
 
-from voluptuous_openai import UNSUPPORTED, convert
+from voluptuous_openapi import UNSUPPORTED, convert
 
 def custom_convert(value):
     if value is my_custom_validator:

{voluptuous_openapi-0.2.0 → voluptuous_openapi-0.4.0}/README.md

@@ -42,7 +42,7 @@ You can pass a custom serializer to be able to process custom validators. If the
 
 ```python
 
-from voluptuous_openai import UNSUPPORTED, convert
+from voluptuous_openapi import UNSUPPORTED, convert
 
 def custom_convert(value):
     if value is my_custom_validator:

{voluptuous_openapi-0.2.0 → voluptuous_openapi-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["setuptools>=77.0"]
 
 [project]
 name = "voluptuous-openapi"
-version = "0.2.0"
+version = "0.4.0"
 license = "Apache-2.0"
 description = "Convert voluptuous schemas to OpenAPI Schema object"
 readme = "README.md"

{voluptuous_openapi-0.2.0 → voluptuous_openapi-0.4.0}/tests/test_lib.py

@@ -410,6 +410,11 @@ def test_key_any():
         },
         "required": [],
         "type": "object",
+        "anyOf": [
+            {"required": ["hours"]},
+            {"required": ["minutes"]},
+            {"required": ["seconds"]},
+        ],
     } == convert(
         {
             vol.Required(vol.Any("hours", "minutes", "seconds")): int,
@@ -830,3 +835,483 @@ def test_convert_to_voluptuous_nullable_number_with_range():
 
     with pytest.raises(vol.Invalid):
         validator(101.0)  # too high
+
+
+TEST_TASK_ITEM = {"content": "a task ", "description": "a description"}
+TASK_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "tasks": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "content": {
+                        "type": "string",
+                        "description": "The content of the task to create.",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "The description of the task.",
+                    },
+                },
+                "required": ["content"],
+                "additionalProperties": False,
+            },
+        }
+    },
+}
+
+
+@pytest.mark.parametrize(
+    "extra_tasks_data, input_data",
+    [
+        ({"minItems": 1, "maxItems": 2}, {"tasks": [TEST_TASK_ITEM]}),
+        ({"minItems": 1, "maxItems": 2}, {"tasks": [TEST_TASK_ITEM, TEST_TASK_ITEM]}),
+        ({"minItems": 1}, {"tasks": [TEST_TASK_ITEM]}),
+        ({"maxItems": 2}, {"tasks": [TEST_TASK_ITEM, TEST_TASK_ITEM]}),
+    ],
+)
+def test_with_min_max_items_success(extra_tasks_data, input_data):
+    task_schema = TASK_SCHEMA.copy()
+    task_schema["properties"]["tasks"].update(extra_tasks_data)
+
+    validator = convert_to_voluptuous(task_schema)
+
+    validator(input_data)
+
+
+@pytest.mark.parametrize(
+    "extra_tasks_data, input_data",
+    [
+        ({"minItems": 1, "maxItems": 2}, {"tasks": []}),
+        (
+            {"minItems": 1, "maxItems": 2},
+            {"tasks": [TEST_TASK_ITEM, TEST_TASK_ITEM, TEST_TASK_ITEM]},
+        ),
+        ({"minItems": 1}, {"tasks": []}),
+        ({"maxItems": 2}, {"tasks": [TEST_TASK_ITEM, TEST_TASK_ITEM, TEST_TASK_ITEM]}),
+    ],
+)
+def test_with_min_max_items_fails_validation(extra_tasks_data, input_data):
+    task_schema = TASK_SCHEMA.copy()
+    task_schema["properties"]["tasks"].update(extra_tasks_data)
+
+    validator = convert_to_voluptuous(task_schema)
+
+    with pytest.raises(vol.Invalid):
+        validator(input_data)
+
+
+def test_required_any_of():
+    """Test schemas with Required(Any(...)) constraints."""
+    assert {
+        "properties": {
+            "color": {"type": "string"},
+            "temperature": {"type": "integer"},
+            "brightness": {"type": "integer"},
+        },
+        "required": [],
+        "type": "object",
+        "anyOf": [
+            {"required": ["color"]},
+            {"required": ["temperature"]},
+            {"required": ["brightness"]},
+        ],
+    } == convert(
+        {
+            vol.Required(vol.Any("color", "temperature", "brightness")): object,
+            vol.Optional("color"): str,
+            vol.Optional("temperature"): int,
+            vol.Optional("brightness"): int,
+        }
+    )
+
+    assert {
+        "properties": {
+            "color": {"type": "string"},
+            "temperature": {"type": "integer"},
+            "brightness": {"type": "integer"},
+            "mode": {"type": "string"},
+            "preset": {"type": "string"},
+        },
+        "required": [],
+        "type": "object",
+        "anyOf": [
+            {"required": ["color", "mode"]},
+            {"required": ["color", "preset"]},
+            {"required": ["temperature", "mode"]},
+            {"required": ["temperature", "preset"]},
+            {"required": ["brightness", "mode"]},
+            {"required": ["brightness", "preset"]},
+        ],
+    } == convert(
+        {
+            vol.Required(vol.Any("color", "temperature", "brightness")): object,
+            vol.Required(vol.Any("mode", "preset")): str,
+            vol.Optional("color"): str,
+            vol.Optional("temperature"): int,
+            vol.Optional("brightness"): int,
+            vol.Optional("mode"): str,
+            vol.Optional("preset"): str,
+        }
+    )
+
+    assert {
+        "properties": {
+            "entity_id": {"type": "string"},
+            "color": {"type": "string"},
+            "temperature": {"type": "integer"},
+        },
+        "required": ["entity_id"],
+        "type": "object",
+        "anyOf": [{"required": ["color"]}, {"required": ["temperature"]}],
+    } == convert(
+        {
+            vol.Required("entity_id"): str,
+            vol.Required(vol.Any("color", "temperature")): str,
+            vol.Optional("color"): str,
+            vol.Optional("temperature"): int,
+        }
+    )
+
+
+def test_required_any_of_description():
+    """Test that the description is preserved in a Required(Any(...)) constraint."""
+    assert {
+        "properties": {
+            "color": {"type": "string", "description": "Light appearance"},
+            "temperature": {"type": "string", "description": "Light appearance"},
+        },
+        "required": [],
+        "type": "object",
+        "anyOf": [{"required": ["color"]}, {"required": ["temperature"]}],
+    } == convert(
+        {
+            vol.Required(
+                vol.Any("color", "temperature"), description="Light appearance"
+            ): str,
+        }
+    )
+
+
+def test_required_any_of_inner_description():
+    """Test that inner descriptions are preferred in a Required(Any(...)) constraint."""
+    assert {
+        "properties": {
+            "color": {"type": "string", "description": "Inner color description"},
+            "temperature": {"type": "string", "description": "Outer description"},
+        },
+        "required": [],
+        "type": "object",
+        "anyOf": [{"required": ["color"]}, {"required": ["temperature"]}],
+    } == convert(
+        {
+            vol.Required(
+                vol.Any(
+                    vol.Optional("color", description="Inner color description"),
+                    "temperature",
+                ),
+                description="Outer description",
+            ): str,
+        }
+    )
+
+
+def test_simple_ref_defs() -> None:
+    """Test basic JSON pointer reference resolution using the $defs keyword."""
+    schema = {
+        "$defs": {"MyInt": {"type": "integer"}},
+        "type": "object",
+        "properties": {"age": {"$ref": "#/$defs/MyInt"}},
+    }
+    validator = convert_to_voluptuous(schema)
+    # Check it validates valid input
+    res = validator({"age": 42})
+    assert res == {"age": 42}
+
+    # Check it raises vol.Invalid on invalid input
+    with pytest.raises(vol.Invalid):
+        validator({"age": "hello"})
+
+
+def test_definitions_compatibility() -> None:
+    """Test compatibility with older JSON Schema drafts using definitions instead of $defs."""
+    schema = {
+        "definitions": {"MyInt": {"type": "integer"}},
+        "type": "object",
+        "properties": {"age": {"$ref": "#/definitions/MyInt"}},
+    }
+    validator = convert_to_voluptuous(schema)
+    res = validator({"age": 42})
+    assert res == {"age": 42}
+
+    with pytest.raises(vol.Invalid):
+        validator({"age": "not-an-int"})
+
+
+def test_chained_refs() -> None:
+    """Test chained references where one reference points to another reference."""
+    schema = {
+        "$defs": {"Level2": {"type": "integer"}, "Level1": {"$ref": "#/$defs/Level2"}},
+        "type": "object",
+        "properties": {"num": {"$ref": "#/$defs/Level1"}},
+    }
+    validator = convert_to_voluptuous(schema)
+    res = validator({"num": 42})
+    assert res == {"num": 42}
+
+    with pytest.raises(vol.Invalid):
+        validator({"num": "yes"})
+
+
+def test_root_self_ref_valid() -> None:
+    """Test root self-reference (#) with valid recursively nested structures."""
+    schema = {"type": "object", "properties": {"child": {"$ref": "#"}}}
+    validator = convert_to_voluptuous(schema)
+
+    # Single level
+    assert validator({"child": {}}) == {"child": {}}
+
+    # Nested level
+    assert validator({"child": {"child": {"child": {}}}}) == {
+        "child": {"child": {"child": {}}}
+    }
+
+
+def test_root_self_ref_invalid() -> None:
+    """Test root self-reference (#) with invalid type values."""
+    schema = {"type": "object", "properties": {"child": {"$ref": "#"}}}
+    validator = convert_to_voluptuous(schema)
+
+    with pytest.raises(vol.Invalid):
+        validator({"child": "not-an-object"})
+
+
+def test_recursive_tree_valid() -> None:
+    """Test recursive tree node reference validation with valid structures."""
+    schema = {
+        "$defs": {
+            "Node": {
+                "type": "object",
+                "properties": {
+                    "value": {"type": "string"},
+                    "children": {"type": "array", "items": {"$ref": "#/$defs/Node"}},
+                },
+                "required": ["value"],
+            }
+        },
+        "$ref": "#/$defs/Node",
+    }
+    validator = convert_to_voluptuous(schema)
+
+    # Leaf node
+    assert validator({"value": "leaf"}) == {"value": "leaf"}
+
+    # Deep recursive tree
+    tree = {
+        "value": "root",
+        "children": [
+            {"value": "child1", "children": [{"value": "grandchild1"}]},
+            {"value": "child2"},
+        ],
+    }
+    assert validator(tree) == tree
+
+
+def test_recursive_tree_invalid() -> None:
+    """Test recursive tree node reference validation with invalid type values."""
+    schema = {
+        "$defs": {
+            "Node": {
+                "type": "object",
+                "properties": {
+                    "value": {"type": "string"},
+                    "children": {"type": "array", "items": {"$ref": "#/$defs/Node"}},
+                },
+                "required": ["value"],
+            }
+        },
+        "$ref": "#/$defs/Node",
+    }
+    validator = convert_to_voluptuous(schema)
+
+    invalid_tree = {"value": "root", "children": [{"value": 123}]}  # Should be string
+    with pytest.raises(vol.Invalid):
+        validator(invalid_tree)
+
+
+def test_anonymized_field_definition_valid() -> None:
+    """Test anonymized FieldDefinition schema with valid primitive and complex structures."""
+    schema = {
+        "$defs": {
+            "FieldDefinition": {
+                "type": "object",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": ["BOOLEAN", "STRING", "INTEGER", "STRUCT", "LIST"],
+                    },
+                    "structFields": {
+                        "type": "object",
+                        "additionalProperties": {"$ref": "#/$defs/FieldDefinition"},
+                    },
+                    "listElement": {"$ref": "#/$defs/FieldDefinition"},
+                },
+                "required": ["type"],
+            }
+        },
+        "$ref": "#/$defs/FieldDefinition",
+    }
+    validator = convert_to_voluptuous(schema)
+
+    # Simple integer type definition
+    assert validator({"type": "INTEGER"}) == {"type": "INTEGER"}
+
+    # Complex struct containing other field definitions (including a list element)
+    complex_def = {
+        "type": "STRUCT",
+        "structFields": {
+            "name": {"type": "STRING"},
+            "tags": {"type": "LIST", "listElement": {"type": "STRING"}},
+        },
+    }
+    assert validator(complex_def) == complex_def
+
+
+def test_anonymized_field_definition_invalid() -> None:
+    """Test anonymized FieldDefinition schema with invalid enum values and recursive types."""
+    schema = {
+        "$defs": {
+            "FieldDefinition": {
+                "type": "object",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": ["BOOLEAN", "STRING", "INTEGER", "STRUCT", "LIST"],
+                    },
+                    "structFields": {
+                        "type": "object",
+                        "additionalProperties": {"$ref": "#/$defs/FieldDefinition"},
+                    },
+                    "listElement": {"$ref": "#/$defs/FieldDefinition"},
+                },
+                "required": ["type"],
+            }
+        },
+        "$ref": "#/$defs/FieldDefinition",
+    }
+    validator = convert_to_voluptuous(schema)
+
+    # Fails if enum value is wrong
+    with pytest.raises(vol.Invalid):
+        validator({"type": "FLOAT"})
+
+    # Fails if recursive validation fails
+    with pytest.raises(vol.Invalid):
+        validator(
+            {
+                "type": "STRUCT",
+                "structFields": {"invalid_field": {"type": 123}},  # type must be string
+            }
+        )
+
+
+def test_anonymized_ghp_home_automation_valid() -> None:
+    """Test anonymized GhpHomeAutomation schema with valid automation rules."""
+    schema = {
+        "$defs": {
+            "Comparison": {
+                "type": "object",
+                "properties": {
+                    "fieldToCompare": {"type": "string"},
+                    "operator": {"type": "string", "enum": ["EQUALS", "LESS_THAN"]},
+                    "nestedComparison": {"$ref": "#/$defs/Comparison"},
+                    "operands": {"type": "array", "items": {"$ref": "#/$defs/Operand"}},
+                },
+            },
+            "Operand": {
+                "type": "object",
+                "properties": {
+                    "comparison": {"$ref": "#/$defs/Comparison"},
+                    "value": {"type": "string"},
+                },
+            },
+            "ConditionBlock": {
+                "type": "object",
+                "properties": {
+                    "comparison": {"$ref": "#/$defs/Comparison"},
+                    "description": {"type": "string"},
+                },
+            },
+        },
+        "type": "object",
+        "properties": {
+            "conditions": {"type": "array", "items": {"$ref": "#/$defs/ConditionBlock"}}
+        },
+    }
+    validator = convert_to_voluptuous(schema)
+
+    valid_automation = {
+        "conditions": [
+            {
+                "description": "Check temperature",
+                "comparison": {
+                    "fieldToCompare": "temp",
+                    "operator": "LESS_THAN",
+                    "operands": [{"value": "72"}],
+                },
+            }
+        ]
+    }
+    assert validator(valid_automation) == valid_automation
+
+
+def test_anonymized_ghp_home_automation_invalid() -> None:
+    """Test anonymized GhpHomeAutomation schema with invalid operator constraints."""
+    schema = {
+        "$defs": {
+            "Comparison": {
+                "type": "object",
+                "properties": {
+                    "fieldToCompare": {"type": "string"},
+                    "operator": {"type": "string", "enum": ["EQUALS", "LESS_THAN"]},
+                    "nestedComparison": {"$ref": "#/$defs/Comparison"},
+                    "operands": {"type": "array", "items": {"$ref": "#/$defs/Operand"}},
+                },
+            },
+            "Operand": {
+                "type": "object",
+                "properties": {
+                    "comparison": {"$ref": "#/$defs/Comparison"},
+                    "value": {"type": "string"},
+                },
+            },
+            "ConditionBlock": {
+                "type": "object",
+                "properties": {
+                    "comparison": {"$ref": "#/$defs/Comparison"},
+                    "description": {"type": "string"},
+                },
+            },
+        },
+        "type": "object",
+        "properties": {
+            "conditions": {"type": "array", "items": {"$ref": "#/$defs/ConditionBlock"}}
+        },
+    }
+    validator = convert_to_voluptuous(schema)
+
+    # Invalid operator in nested comparison
+    invalid_automation = {
+        "conditions": [
+            {
+                "comparison": {
+                    "fieldToCompare": "temp",
+                    "operator": "GREATER_THAN",  # Not in comparison enum ["EQUALS", "LESS_THAN"]
+                }
+            }
+        ]
+    }
+    with pytest.raises(vol.Invalid):
+        validator(invalid_automation)

{voluptuous_openapi-0.2.0 → voluptuous_openapi-0.4.0}/tests/test_validation.py

@@ -576,3 +576,70 @@ def test_maybe(validator: Validator) -> None:
 
     with pytest.raises(InvalidFormat):
         validator({"key": "value"})
+
+
+@pytest.mark.parametrize(
+    "validator",
+    generate_validators(
+        {
+            "type": "object",
+            "properties": {
+                "color": {"type": "string"},
+                "temperature": {"type": "integer"},
+                "brightness": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 100,
+                },
+            },
+            "anyOf": [
+                {"required": ["color"]},
+                {"required": ["temperature"]},
+                {"required": ["brightness"]},
+            ],
+        },
+        vol.Schema(
+            {
+                vol.Required(vol.Any("color", "temperature", "brightness")): object,
+                vol.Optional("color"): str,
+                vol.Optional("temperature"): int,
+                vol.Optional("brightness"): vol.All(int, vol.Range(min=0, max=100)),
+            }
+        ),
+    ),
+    ids=TEST_IDS,
+)
+def test_any_of_constraint(validator: Validator) -> None:
+    """Test anyOf constraint for requiring at least one of multiple properties."""
+    # Test valid cases
+    validator({"color": "red"})
+    validator({"temperature": 20})
+    validator({"brightness": 80})
+    validator({"brightness": 0})
+    validator({"brightness": 100})
+    validator({"color": "blue", "temperature": 25})
+    validator({"color": "green", "brightness": 100})
+    validator({"temperature": 22, "brightness": 90})
+    validator({"color": "purple", "temperature": 21, "brightness": 70})
+
+    # Test invalid cases
+    with pytest.raises(InvalidFormat):
+        validator({})  # Missing all required properties
+
+    with pytest.raises(InvalidFormat):
+        validator({"other_field": "value"})  # Missing all required properties
+
+    with pytest.raises(InvalidFormat):
+        validator({"brightness": -1})  # Out of range
+
+    with pytest.raises(InvalidFormat):
+        validator({"brightness": 101})  # Out of range
+
+    with pytest.raises(InvalidFormat):
+        validator({"brightness": "abc"})  # Wrong type
+
+    with pytest.raises(InvalidFormat):
+        validator({"color": 123})  # Wrong type
+
+    with pytest.raises(InvalidFormat):
+        validator({"temperature": "abc"})  # Wrong type

{voluptuous_openapi-0.2.0 → voluptuous_openapi-0.4.0}/voluptuous_openapi/__init__.py

@@ -3,6 +3,7 @@
 from collections.abc import Callable, Mapping, Sequence
 from inspect import signature
 from enum import Enum, StrEnum
+import itertools
 import re
 from typing import Any, TypeVar, Union, get_args, get_origin, get_type_hints
 from types import NoneType, UnionType
@@ -24,11 +25,12 @@ UNSUPPORTED = object()
 OPENAPI_UNSUPPORTED_KEYWORDS = {
     "allOf",
     "multipleOf",
-    "minItems",
-    "maxItems",
     "uniqueItems",
 }
 
+# The standard JSON Schema reference keyword
+JSON_SCHEMA_REF = "$ref"
+
 
 class OpenApiVersion(StrEnum):
     """The OpenAPI version.
@@ -88,6 +90,9 @@ def convert(
     if isinstance(schema, Mapping):
         properties = {}
         required = []
+        any_of_constraint_groups: list[list[str]] = (
+            []
+        )  # List of lists, each containing candidate keys for a Required(Any(...))
 
         for key, value in schema.items():
             description = None
@@ -101,22 +106,57 @@ def convert(
             if description:
                 pval["description"] = key.description
 
-            if isinstance(key, (vol.Required, vol.Optional)):
+            if isinstance(key, vol.Required):
+                if not isinstance(key.schema, vol.Any):
+                    required.append(str(key.schema))
+                if key.default is not vol.UNDEFINED:
+                    pval["default"] = key.default()
+            elif isinstance(key, vol.Optional):
                 if key.default is not vol.UNDEFINED:
                     pval["default"] = key.default()
 
             pval = ensure_default(pval)
 
             if isinstance(pkey, vol.Any):
-                for val in pkey.validators:
-                    if isinstance(val, vol.Marker):
-                        if val.description:
-                            properties[str(val.schema)] = pval.copy()
-                            properties[str(val.schema)]["description"] = val.description
+                # Handle Required(Any(...)) pattern for anyOf constraints
+                if isinstance(key, vol.Required):
+                    # Extract candidate keys and their descriptions from Any validator
+                    candidate_items = []
+                    for val_item in pkey.validators:
+                        item_key = ""
+                        item_desc = None
+                        if isinstance(val_item, vol.Marker):
+                            item_key = str(val_item.schema)
+                            item_desc = val_item.description
                         else:
-                            properties[str(val)] = pval
-                    else:
-                        properties[str(val)] = pval
+                            item_key = str(val_item)
+                        candidate_items.append({"key": item_key, "desc": item_desc})
+
+                    candidate_keys = [item["key"] for item in candidate_items]
+                    any_of_constraint_groups.append(candidate_keys)
+
+                    # If the value is not a wildcard, create properties for each
+                    # candidate key, preserving any descriptions.
+                    if value is not object:
+                        for item in candidate_items:
+                            prop_schema = pval.copy()
+                            final_description = item["desc"] or description
+                            if final_description:
+                                prop_schema["description"] = final_description
+                            properties[item["key"]] = prop_schema
+                else:
+                    # Handle Optional(Any(...)) - expand to individual properties
+                    for val_item in pkey.validators:
+                        if isinstance(val_item, vol.Marker):
+                            if val_item.description:
+                                properties[str(val_item.schema)] = pval.copy()
+                                properties[str(val_item.schema)][
+                                    "description"
+                                ] = val_item.description
+                            else:
+                                properties[str(val_item)] = pval
+                        else:
+                            properties[str(val_item)] = pval
             elif isinstance(pkey, str):
                 properties[pkey] = pval
             else:
@@ -126,15 +166,21 @@ def convert(
                 if additional_properties is None:
                     additional_properties = pval
 
-            if isinstance(key, vol.Required) and not isinstance(pkey, vol.Any):
-                required.append(str(pkey))
-
         val = {"type": "object"}
         if properties or not additional_properties:
             val["properties"] = properties
             val["required"] = required
         if additional_properties:
             val["additionalProperties"] = additional_properties
+
+        # Generate anyOf constraints from the Cartesian product of constraint groups
+        if any_of_constraint_groups:
+            # Generate all combinations (Cartesian product) of the constraint groups
+            val["anyOf"] = [
+                {"required": list(combination)}
+                for combination in itertools.product(*any_of_constraint_groups)
+            ]
+
         return val
 
     if isinstance(schema, vol.All):
@@ -406,12 +452,112 @@ def convert(
     raise ValueError("Unable to convert schema: {}".format(schema))
 
 
-def convert_to_voluptuous(schema: dict) -> vol.Schema:
-    """Convert an OpenAPI Schema object to a voluptuous schema."""
+def resolve_ref(ref: str, root_schema: dict) -> dict:
+    """Resolve a JSON pointer reference within the root_schema.
+
+    A JSON pointer (defined in RFC 6901) is a string syntax for identifying a
+    specific value within a JSON document. It uses '/' to separate keys or list
+    indices. This function resolves local pointer references starting with '#'.
+
+    Example:
+        Given root_schema = {"$defs": {"User": {"type": "object"}}},
+        resolve_ref("#/$defs/User", root_schema) returns {"type": "object"}.
+    """
+    if not ref.startswith("#"):
+        raise ValueError(f"External/relative $ref not supported: {ref}")
+    if ref == "#" or ref == "":
+        return root_schema
+
+    parts = ref.lstrip("#").split("/")
+    # If the ref was '#/something', lstrip('#') is '/something', and split('/')
+    # produces ['', 'something']. We pop the first empty element.
+    if parts[0] == "":
+        parts.pop(0)
+
+    current = root_schema
+    for part in parts:
+        # RFC 6901 specifies '~1' represents '/' and '~0' represents '~'
+        part = part.replace("~1", "/").replace("~0", "~")
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        elif isinstance(current, list):
+            try:
+                idx = int(part)
+                current = current[idx]
+            except (ValueError, IndexError):
+                raise ValueError(f"Could not resolve ref {ref} in list at index {part}")
+        else:
+            raise ValueError(f"Could not resolve ref {ref} at key {part}")
+
+    return current
+
+
+class LazySchema:
+    """A wrapper validator that resolves and compiles a schema reference lazily.
+
+    This leverages voluptuous's ability to use any Python callable as a validator.
+    By returning a LazySchema instance during compilation, we avoid infinite
+    recursion/loops for circular or self-referential schemas. The schema is
+    resolved and compiled only on its first invocation, and cached for future runs.
+    """
+
+    def __init__(self, ref: str, root_schema: dict):
+        self.ref = ref
+        self.root_schema = root_schema
+        self._compiled_schema = None
+
+    def __call__(self, value: Any) -> Any:
+        """Validate the value against the lazily compiled schema.
+
+        On the first validation call, this resolves the JSON pointer reference
+        and compiles it into a voluptuous validator. Subsequent validation calls
+        bypass the compilation and reuse the cached validator.
+        """
+        if self._compiled_schema is None:
+            target_schema = resolve_ref(self.ref, self.root_schema)
+            self._compiled_schema = convert_to_voluptuous(
+                target_schema, self.root_schema
+            )
+        return self._compiled_schema(value)
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, LazySchema):
+            return False
+        return self.ref == other.ref and self.root_schema == other.root_schema
+
+    def __repr__(self) -> str:
+        return f"LazySchema({self.ref!r})"
+
+
+def convert_to_voluptuous(schema: dict, root_schema: dict | None = None) -> Any:
+    """Convert an OpenAPI/JSON Schema object to a voluptuous schema.
+
+    Args:
+        schema: The OpenAPI/JSON Schema dictionary to convert.
+        root_schema: The root schema document, which is propagated recursively
+            to resolve local JSON pointer references ($ref). If not provided,
+            defaults to the current schema.
+
+    Returns:
+        A voluptuous Schema, a type validator, or a custom validator callable.
+    """
 
     if not isinstance(schema, dict):
         raise ValueError("Invalid schema, expected a dictionary")
 
+    if root_schema is None:
+        root_schema = schema
+
+    if JSON_SCHEMA_REF in schema:
+        return LazySchema(schema[JSON_SCHEMA_REF], root_schema)
+
+    if (enum_values := schema.get("enum")) is not None:
+        if not isinstance(enum_values, list):
+            raise ValueError("Invalid schema, enum should be a list")
+        if schema.get("nullable") is True:
+            return vol.Any(vol.In(enum_values), None)
+        return vol.In(enum_values)
+
     for keyword in OPENAPI_UNSUPPORTED_KEYWORDS:
         if keyword in schema:
             raise ValueError(f"{keyword} is not supported")
@@ -421,12 +567,26 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
             raise ValueError("Invalid schema, oneOf should be a list")
         # This implements anyOf semantics sice it matches any of the subschemas,
         # not just one of them.
-        return vol.Any(*[convert_to_voluptuous(sub_schema) for sub_schema in one_of])
+        return vol.Any(
+            *[convert_to_voluptuous(sub_schema, root_schema) for sub_schema in one_of]
+        )
 
     if (any_of := schema.get("anyOf")) is not None:
         if not isinstance(any_of, list):
             raise ValueError("Invalid schema, anyOf should be a list")
-        return vol.Any(*[convert_to_voluptuous(sub_schema) for sub_schema in any_of])
+        # If the anyOf is a list of required properties, it's a constraint on an
+        # object and should be handled by the object validator.
+        is_required_constraint = all(
+            list(s.keys()) == ["required"] and isinstance(s["required"], list)
+            for s in any_of
+        )
+        if not (is_required_constraint and schema.get("type") == "object"):
+            return vol.Any(
+                *[
+                    convert_to_voluptuous(sub_schema, root_schema)
+                    for sub_schema in any_of
+                ]
+            )
 
     if (schema_type := schema.get("type")) is None:
         raise ValueError("Invalid schema, missing type")
@@ -446,7 +606,7 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
             else:
                 base_schema = schema.copy()
                 base_schema["type"] = t
-                validators.append(convert_to_voluptuous(base_schema))
+                validators.append(convert_to_voluptuous(base_schema, root_schema))
         return vol.Any(*validators)
 
     if (basic_type := TYPES_MAP_REV.get(schema_type)) is not None:
@@ -481,7 +641,7 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
         properties = {}
         required_properties = set(schema.get("required", []))
         for key, value in schema.get("properties", {}).items():
-            value_type = convert_to_voluptuous(value)
+            value_type = convert_to_voluptuous(value, root_schema)
             description: str | None = None
             if isinstance(value, dict):
                 description = value.get("description")
@@ -491,9 +651,19 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
                 key_type = vol.Optional
             properties[key_type(key, description=description)] = value_type
 
-        validator = None
-        if schema.get("additionalProperties") is True:
+        if (any_of := schema.get("anyOf")) is not None:
+            any_of_keys = [
+                key for sub_schema in any_of for key in sub_schema.get("required", [])
+            ]
+            if any_of_keys:
+                properties[vol.Required(vol.Any(*any_of_keys))] = object
+
+        extra_schema = schema.get("additionalProperties")
+        if extra_schema is True:
             validator = vol.Schema(properties, extra=vol.ALLOW_EXTRA)
+        elif isinstance(extra_schema, dict):
+            properties[vol.Extra] = convert_to_voluptuous(extra_schema, root_schema)
+            validator = vol.Schema(properties)
         else:
             validator = vol.Schema(properties)
 
@@ -504,7 +674,16 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
         return validator
 
     if schema_type == "array":
-        validator = vol.Schema([convert_to_voluptuous(schema["items"])])
+        item_validator = convert_to_voluptuous(schema["items"], root_schema)
+        min_items = schema.get("minItems")
+        max_items = schema.get("maxItems")
+
+        if min_items is not None or max_items is not None:
+            validator = vol.Schema(
+                vol.All([item_validator], vol.Length(min=min_items, max=max_items))
+            )
+        else:
+            validator = vol.Schema([item_validator])
 
         # Handle OpenAPI 3.0 nullable property
         if schema.get("nullable") is True:

{voluptuous_openapi-0.2.0 → voluptuous_openapi-0.4.0/voluptuous_openapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voluptuous-openapi
-Version: 0.2.0
+Version: 0.4.0
 Summary: Convert voluptuous schemas to OpenAPI Schema object
 Author-email: Denis Shulyaka <Shulyaka@gmail.com>
 License-Expression: Apache-2.0
@@ -55,7 +55,7 @@ You can pass a custom serializer to be able to process custom validators. If the
 
 ```python
 
-from voluptuous_openai import UNSUPPORTED, convert
+from voluptuous_openapi import UNSUPPORTED, convert
 
 def custom_convert(value):
     if value is my_custom_validator: