feat!: reject legacy RootModel envelope in function parameters

The updated bare dict for OpenAI API compatibility would still
accept a key named RootModel, but the behavior would be wrong.
To assist in migration add validation and reject the legacy
wrapper.

BREAKING CHANGE: FunctionParameters validator now rejects {"RootModel": {...}}
envelope pattern. Send parameters as bare JSON Schema objects instead.

Signed-off-by: Mark Sturdevant <mark.sturdevant@ibm.com>
Assisted-by: Mark Sturdevant <mark.sturdevant@ibm.com>

Author: markstur

cli/serve/models.py

@@ -22,6 +22,20 @@ class FunctionParameters(RootModel[dict[str, Any]]):
 
     root: dict[str, Any]
 
+    @model_validator(mode="after")
+    def _reject_legacy_envelope(self) -> "FunctionParameters":
+        """Reject legacy RootModel envelope pattern.
+
+        Ensures parameters are sent as a bare JSON Schema object, not wrapped
+        in a {"RootModel": {...}} envelope which would be invalid.
+        """
+        if set(self.root.keys()) == {"RootModel"}:
+            raise ValueError(
+                "Legacy {'RootModel': {...}} envelope is no longer accepted. "
+                "Send parameters as a bare JSON Schema object."
+            )
+        return self
+
 
 class FunctionDefinition(BaseModel):
     name: str

test/cli/test_serve_integration.py

@@ -571,3 +571,43 @@ def test_server_error_returns_500(self, client, mock_module):
         assert data["error"]["type"] == "server_error"
         assert "Internal error" not in data["error"]["message"]
         assert "Internal server error" in data["error"]["message"]
+
+    def test_legacy_root_model_envelope_rejected_via_http(self, client, mock_module):
+        """Test that legacy {'RootModel': {...}} envelope is rejected at HTTP layer.
+
+        Verifies that the FunctionParameters validator catches the legacy envelope
+        pattern and returns a proper 400 error via the HTTP API.
+        """
+        # Send request with legacy envelope in function parameters
+        response = client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "test-model",
+                "messages": [{"role": "user", "content": "What's the weather?"}],
+                "tools": [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "get_weather",
+                            "description": "Get weather",
+                            "parameters": {
+                                "RootModel": {
+                                    "type": "object",
+                                    "properties": {"location": {"type": "string"}},
+                                }
+                            },
+                        },
+                    }
+                ],
+            },
+        )
+
+        # Should return 400 with validation error
+        assert response.status_code == 400
+        data = response.json()
+        assert "error" in data
+        assert data["error"]["type"] == "invalid_request_error"
+        assert (
+            "Legacy {'RootModel': {...}} envelope is no longer accepted"
+            in data["error"]["message"]
+        )

test/cli/test_serve_models.py

@@ -3,7 +3,7 @@
 import pytest
 from pydantic import ValidationError
 
-from cli.serve.models import StreamOptions
+from cli.serve.models import FunctionParameters, StreamOptions
 
 
 class TestStreamOptions:
@@ -79,3 +79,51 @@ def test_model_dump_json_serialization(self):
         json_str = options.model_dump_json()
         assert "include_usage" in json_str
         assert "true" in json_str.lower()
+
+
+class TestFunctionParameters:
+    """Tests for the FunctionParameters RootModel validator."""
+
+    def test_valid_json_schema_accepted(self):
+        """Test that a valid JSON Schema dict is accepted."""
+        schema = {
+            "type": "object",
+            "properties": {"location": {"type": "string"}},
+            "required": ["location"],
+        }
+        params = FunctionParameters(root=schema)
+        assert params.root == schema
+
+    def test_legacy_root_model_envelope_rejected(self):
+        """Test that legacy {'RootModel': {...}} envelope is rejected."""
+        legacy_envelope = {
+            "RootModel": {
+                "type": "object",
+                "properties": {"location": {"type": "string"}},
+            }
+        }
+        with pytest.raises(ValidationError) as exc_info:
+            FunctionParameters(root=legacy_envelope)
+
+        errors = exc_info.value.errors()
+        assert len(errors) == 1
+        error_msg = str(exc_info.value)
+        assert "Legacy {'RootModel': {...}} envelope is no longer accepted" in error_msg
+
+    def test_root_model_with_additional_keys_accepted(self):
+        """Test that a dict with 'RootModel' plus other keys is accepted."""
+        # This is a valid schema that happens to have a property named "RootModel"
+        schema = {
+            "type": "object",
+            "properties": {
+                "RootModel": {"type": "string"},
+                "other_field": {"type": "number"},
+            },
+        }
+        params = FunctionParameters(root=schema)
+        assert params.root == schema
+
+    def test_empty_dict_accepted(self):
+        """Test that an empty dict is accepted (though not a useful schema)."""
+        params = FunctionParameters(root={})
+        assert params.root == {}