feat(models): add shared strict schema transformation utility

Add ensure_strict_json_schema utility that recursively injects
additionalProperties: false on all object types in tool input schemas.
Handles $defs, definitions, anyOf, allOf, oneOf, items, and $ref
resolution. Includes require_all_properties flag for OpenAI support.

From PR strands-agents#1862

Author: BV-Venky

src/strands/models/_strict_schema.py

@@ -0,0 +1,144 @@
+"""Strict JSON schema transformation for tool definitions.
+
+When model providers require `strict: true` on tool definitions, they also require
+`"additionalProperties": false` on every `object` type in the input schema. This module
+provides a utility to recursively apply that constraint.
+
+Modeled after OpenAI's `_ensure_strict_json_schema`:
+https://github.com/openai/openai-python/blob/main/src/openai/lib/_pydantic.py
+"""
+
+import copy
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def ensure_strict_json_schema(
+    schema: dict[str, Any],
+    *,
+    require_all_properties: bool = False,
+) -> dict[str, Any]:
+    """Ensure a JSON schema conforms to strict tool use requirements.
+
+    Creates a deep copy of the schema and recursively:
+    1. Adds ``"additionalProperties": false`` to all ``object`` types that do not already define it
+    2. Optionally adds all properties to the ``required`` array (needed for OpenAI)
+    3. Handles ``$defs``, ``definitions``, ``anyOf``, ``allOf``, ``items``, and ``$ref``
+
+    Args:
+        schema: The JSON schema to process. A deep copy is made internally so the original is not mutated.
+        require_all_properties: If True, set ``required`` to include all property keys. OpenAI strict mode
+            requires this; Bedrock and Anthropic do not.
+
+    Returns:
+        A new schema dict with strict-mode constraints applied.
+    """
+    schema_copy = copy.deepcopy(schema)
+    _apply_strict(schema_copy, root=schema_copy, require_all_properties=require_all_properties)
+    return schema_copy
+
+
+def _apply_strict(
+    schema: dict[str, Any],
+    *,
+    root: dict[str, Any],
+    require_all_properties: bool,
+) -> None:
+    """Recursively apply strict-mode constraints to a JSON schema in place.
+
+    Args:
+        schema: The schema node to process (modified in place).
+        root: The root schema, used for resolving ``$ref`` pointers.
+        require_all_properties: If True, add all properties to ``required``.
+    """
+    # Process $defs / definitions blocks
+    for defs_key in ("$defs", "definitions"):
+        defs = schema.get(defs_key)
+        if isinstance(defs, dict):
+            for def_schema in defs.values():
+                if isinstance(def_schema, dict):
+                    _apply_strict(def_schema, root=root, require_all_properties=require_all_properties)
+
+    # Add additionalProperties: false to object types that lack it
+    if schema.get("type") == "object" and "additionalProperties" not in schema:
+        schema["additionalProperties"] = False
+
+    # Process properties and optionally enforce required
+    properties = schema.get("properties")
+    if isinstance(properties, dict):
+        if require_all_properties:
+            schema["required"] = list(properties.keys())
+
+        for prop_schema in properties.values():
+            if isinstance(prop_schema, dict):
+                _apply_strict(prop_schema, root=root, require_all_properties=require_all_properties)
+
+    # Process array items
+    items = schema.get("items")
+    if isinstance(items, dict):
+        _apply_strict(items, root=root, require_all_properties=require_all_properties)
+
+    # Process anyOf variants
+    any_of = schema.get("anyOf")
+    if isinstance(any_of, list):
+        for variant in any_of:
+            if isinstance(variant, dict):
+                _apply_strict(variant, root=root, require_all_properties=require_all_properties)
+
+    # Process allOf variants
+    all_of = schema.get("allOf")
+    if isinstance(all_of, list):
+        for entry in all_of:
+            if isinstance(entry, dict):
+                _apply_strict(entry, root=root, require_all_properties=require_all_properties)
+
+    # Process oneOf variants
+    one_of = schema.get("oneOf")
+    if isinstance(one_of, list):
+        for variant in one_of:
+            if isinstance(variant, dict):
+                _apply_strict(variant, root=root, require_all_properties=require_all_properties)
+
+    # Resolve $ref combined with other keys by inlining the referenced schema
+    ref = schema.get("$ref")
+    if isinstance(ref, str) and len(schema) > 1:
+        resolved = _resolve_ref(root, ref)
+        if isinstance(resolved, dict):
+            # Inline the resolved schema, giving priority to existing keys
+            merged = {**resolved, **schema}
+            merged.pop("$ref", None)
+            schema.clear()
+            schema.update(merged)
+            # Re-apply strict to the inlined schema
+            _apply_strict(schema, root=root, require_all_properties=require_all_properties)
+
+
+def _resolve_ref(root: dict[str, Any], ref: str) -> dict[str, Any] | None:
+    """Resolve a JSON Schema ``$ref`` pointer against the root schema.
+
+    Args:
+        root: The root schema containing definitions.
+        ref: A JSON pointer string (e.g., ``#/$defs/MyModel``).
+
+    Returns:
+        The resolved schema dict, or None if resolution fails.
+    """
+    if not ref.startswith("#/"):
+        logger.warning("ref=<%s> | unexpected $ref format, skipping resolution", ref)
+        return None
+
+    path = ref[2:].split("/")
+    current: Any = root
+    for key in path:
+        if not isinstance(current, dict) or key not in current:
+            logger.warning("ref=<%s> | failed to resolve $ref path", ref)
+            return None
+        current = current[key]
+
+    if not isinstance(current, dict):
+        logger.warning("ref=<%s> | resolved to non-dict value", ref)
+        return None
+
+    return current

tests/strands/models/test_strict_schema.py

@@ -0,0 +1,158 @@
+from strands.models._strict_schema import ensure_strict_json_schema
+
+
+def test_ensure_strict_json_schema_basic():
+    schema = {
+        "type": "object",
+        "properties": {"x": {"type": "string"}},
+    }
+    strict_schema = ensure_strict_json_schema(schema)
+
+    assert strict_schema["additionalProperties"] is False
+    assert strict_schema["properties"]["x"] == {"type": "string"}
+    # Original should be untouched
+    assert "additionalProperties" not in schema
+
+
+def test_ensure_strict_json_schema_nested():
+    schema = {
+        "type": "object",
+        "properties": {
+            "outer": {
+                "type": "object",
+                "properties": {"inner": {"type": "integer"}},
+            }
+        },
+    }
+    strict_schema = ensure_strict_json_schema(schema)
+
+    assert strict_schema["additionalProperties"] is False
+    assert strict_schema["properties"]["outer"]["additionalProperties"] is False
+    assert strict_schema["properties"]["outer"]["properties"]["inner"] == {"type": "integer"}
+
+
+def test_ensure_strict_json_schema_with_defs():
+    schema = {
+        "type": "object",
+        "properties": {"item": {"$ref": "#/$defs/MyItem"}},
+        "$defs": {
+            "MyItem": {
+                "type": "object",
+                "properties": {"name": {"type": "string"}},
+            }
+        },
+    }
+    strict_schema = ensure_strict_json_schema(schema)
+
+    assert strict_schema["additionalProperties"] is False
+    assert strict_schema["$defs"]["MyItem"]["additionalProperties"] is False
+
+
+def test_ensure_strict_json_schema_with_ref_inline():
+    # When a $ref is combined with other keys, the reference should be inlined.
+    # Note: ensure_strict_json_schema resolves refs from the root schema.
+    schema = {
+        "type": "object",
+        "properties": {
+            "item": {
+                "$ref": "#/$defs/MyItem",
+                "description": "An item",
+            }
+        },
+        "$defs": {
+            "MyItem": {
+                "type": "object",
+                "properties": {"name": {"type": "string"}},
+            }
+        },
+    }
+    strict_schema = ensure_strict_json_schema(schema)
+
+    assert strict_schema["additionalProperties"] is False
+    # The reference should have been inlined, retaining 'description', and gaining additionalProperties
+    item_prop = strict_schema["properties"]["item"]
+    assert "$ref" not in item_prop
+    assert item_prop["type"] == "object"
+    assert item_prop["description"] == "An item"
+    assert item_prop["additionalProperties"] is False
+    assert item_prop["properties"]["name"] == {"type": "string"}
+
+
+def test_ensure_strict_json_schema_arrays_and_unions():
+    schema = {
+        "type": "object",
+        "properties": {
+            "items": {
+                "type": "array",
+                "items": {"type": "object", "properties": {"a": {"type": "string"}}},
+            },
+            "union": {
+                "anyOf": [
+                    {"type": "object", "properties": {"b": {"type": "string"}}},
+                    {"type": "object", "properties": {"c": {"type": "string"}}},
+                ]
+            },
+            "intersection": {
+                "allOf": [
+                    {"type": "object", "properties": {"d": {"type": "string"}}},
+                ]
+            },
+        },
+    }
+    strict_schema = ensure_strict_json_schema(schema)
+
+    assert strict_schema["additionalProperties"] is False
+    assert strict_schema["properties"]["items"]["items"]["additionalProperties"] is False
+    assert strict_schema["properties"]["union"]["anyOf"][0]["additionalProperties"] is False
+    assert strict_schema["properties"]["union"]["anyOf"][1]["additionalProperties"] is False
+    assert strict_schema["properties"]["intersection"]["allOf"][0]["additionalProperties"] is False
+
+
+def test_ensure_strict_json_schema_require_all_properties():
+    schema = {
+        "type": "object",
+        "properties": {
+            "required_field": {"type": "string"},
+            "optional_field": {"type": "string"},
+        },
+        "required": ["required_field"],
+    }
+
+    # Test without require_all_properties
+    strict_schema = ensure_strict_json_schema(schema)
+    assert strict_schema["required"] == ["required_field"]
+
+    # Test with require_all_properties
+    strict_req = ensure_strict_json_schema(schema, require_all_properties=True)
+    # The order of keys is typically preserved from the dict iteration
+    assert set(strict_req["required"]) == {"required_field", "optional_field"}
+
+
+def test_ensure_strict_json_schema_preserves_additional_properties_true():
+    schema = {
+        "type": "object",
+        "properties": {"x": {"type": "string"}},
+        "additionalProperties": True,
+    }
+    strict_schema = ensure_strict_json_schema(schema)
+
+    assert strict_schema["additionalProperties"] is True
+
+
+def test_ensure_strict_json_schema_oneOf():
+    schema = {
+        "type": "object",
+        "properties": {
+            "value": {
+                "oneOf": [
+                    {"type": "object", "properties": {"a": {"type": "string"}}},
+                    {"type": "object", "properties": {"b": {"type": "integer"}}},
+                ]
+            }
+        },
+    }
+    strict_schema = ensure_strict_json_schema(schema)
+
+    assert strict_schema["additionalProperties"] is False
+    assert strict_schema["properties"]["value"]["oneOf"][0]["additionalProperties"] is False
+    assert strict_schema["properties"]["value"]["oneOf"][1]["additionalProperties"] is False