fix(openapi): validate HTTP method and normalize schema-level examples

Issue 2 — replace the blind cast on http_method with an explicit guard.
OpenAPI allows operations (options/head/trace) that HttpCallTemplate's
Literal type rejects; these are now skipped with a warning instead of
crashing conversion via a Pydantic ValidationError. A shared
SUPPORTED_HTTP_METHODS constant backs both the operation-loop filter and
the per-operation check, so the cast is now truthful rather than assumed.

Issue 3 — make example handling consistent across params, request bodies,
and responses. Examples that appear at the schema level (not just the media
type / parameter object) are now collected via _merge_examples and surfaced
in the normalized JSON Schema 'examples' keyword, and the raw OpenAPI
'example'/'examples' keys are stripped before the schema is spread onto the
property so they no longer leak through as untyped extra fields. This lines
up with the explicit examples field added to JsonSchema in core (#91).

Adds tests for unsupported-method skipping and schema-level example
normalization.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: h3xxit

plugins/communication_protocols/http/src/utcp_http/openapi_converter.py

@@ -29,6 +29,11 @@
 from utcp_http.http_call_template import HttpCallTemplate
 from utcp_http._security import ensure_secure_url, is_loopback_url
 
+# HTTP methods that HttpCallTemplate.http_method accepts. Kept as the single
+# source of truth for both the operation loop filter and per-operation
+# validation so the two can never drift apart.
+SUPPORTED_HTTP_METHODS: Tuple[str, ...] = ("GET", "POST", "PUT", "DELETE", "PATCH")
+
 class OpenApiConverter:
     """REQUIRED
     Converts OpenAPI specifications into UTCP tool definitions.
@@ -185,7 +190,7 @@ def convert(self) -> UtcpManual:
 
         for path, path_item in self.spec.get("paths", {}).items():
             for method, operation in path_item.items():
-                if method.lower() in ['get', 'post', 'put', 'delete', 'patch']:
+                if method.upper() in SUPPORTED_HTTP_METHODS:
                     tool = self._create_tool(path, method, operation, base_url)
                     if tool:
                         tools.append(tool)
@@ -370,8 +375,36 @@ def _extract_examples(self, obj: Dict[str, Any]) -> Optional[List[Any]]:
                     if "value" in example_obj:
                         examples.append(example_obj["value"])
                     # Note: externalValue is a URI reference, we skip it as it's not inline
-        
+
         return examples if examples else None
+
+    def _merge_examples(self, *objs: Optional[Dict[str, Any]]) -> Optional[List[Any]]:
+        """
+        Collect and de-duplicate examples from several OpenAPI objects, preserving order.
+
+        Used to combine examples that can appear at more than one level for the
+        same value, e.g. a Media Type Object and the Schema Object beneath it.
+        Returns a list suitable for the JSON Schema 'examples' keyword, or None.
+        """
+        merged: List[Any] = []
+        for obj in objs:
+            if not isinstance(obj, dict):
+                continue
+            for ex in self._extract_examples(obj) or []:
+                if ex not in merged:
+                    merged.append(ex)
+        return merged or None
+
+    @staticmethod
+    def _schema_without_example_keys(schema: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Return a copy of a schema dict with the raw 'example'/'examples' keys removed.
+
+        Examples are normalized into the JSON Schema 'examples' keyword via
+        _merge_examples, so the raw OpenAPI keys must not be spread back onto the
+        property or they would leak through as untyped extra fields.
+        """
+        return {k: v for k, v in schema.items() if k not in ("example", "examples")}
 
     def _create_auth_from_scheme(self, scheme: Dict[str, Any], scheme_name: str) -> Optional[Auth]:
         """Creates an Auth object from an OpenAPI security scheme."""
@@ -488,6 +521,20 @@ def _create_tool(self, path: str, method: str, operation: Dict[str, Any], base_u
         if not operation_id:
             return None
 
+        # Validate the HTTP method against what HttpCallTemplate accepts before
+        # building the tool. OpenAPI allows operations like 'options'/'head'/
+        # 'trace' that the call template's Literal type rejects; skip them with a
+        # warning instead of letting Pydantic raise mid-conversion. This explicit
+        # check is also what makes the cast below truthful rather than a blind
+        # assertion.
+        http_method = method.upper()
+        if http_method not in SUPPORTED_HTTP_METHODS:
+            print(
+                f"Skipping operation '{operation_id}': unsupported HTTP method '{method}'.",
+                file=sys.stderr,
+            )
+            return None
+
         description = operation.get("summary") or operation.get("description", "")
         tags = operation.get("tags", [])
 
@@ -500,7 +547,7 @@ def _create_tool(self, path: str, method: str, operation: Dict[str, Any], base_u
 
         call_template = HttpCallTemplate(
             name=self.call_template_name,
-            http_method=cast(Literal["GET", "POST", "PUT", "DELETE", "PATCH"], method.upper()),
+            http_method=cast(Literal["GET", "POST", "PUT", "DELETE", "PATCH"], http_method),
             url=full_url,
             body_field=body_field if body_field else None,
             header_fields=header_fields if header_fields else None,
@@ -549,17 +596,18 @@ def _extract_inputs(self, path: str, operation: Dict[str, Any]) -> Tuple[JsonSch
             if param.get("in") == "body":
                 body_field = "body"
                 json_schema = self._resolve_ref_obj(param.get("schema", {}), set()) or {}
-                
-                # Extract examples from body parameter
-                body_examples = self._extract_examples(param)
-                
+
+                # Examples can live on the parameter itself and on its schema;
+                # collect both into the normalized 'examples' keyword.
+                body_examples = self._merge_examples(param, json_schema)
+
                 prop = {
                     "description": param.get("description", "Request body"),
-                    **json_schema,
+                    **self._schema_without_example_keys(json_schema),
                 }
                 if body_examples:
                     prop["examples"] = body_examples
-                
+
                 properties[body_field] = prop
                 if param.get("required"):
                     required.append(body_field)
@@ -576,16 +624,17 @@ def _extract_inputs(self, path: str, operation: Dict[str, Any]) -> Tuple[JsonSch
                 if "enum" in param:
                     schema["enum"] = param.get("enum")
 
-            # Extract examples from parameter
-            param_examples = self._extract_examples(param)
-            
+            # Examples can live on the parameter itself and on its schema;
+            # collect both into the normalized 'examples' keyword.
+            param_examples = self._merge_examples(param, schema)
+
             prop = {
                 "description": param.get("description", ""),
-                **schema,
+                **self._schema_without_example_keys(schema),
             }
             if param_examples:
                 prop["examples"] = param_examples
-            
+
             properties[param_name] = prop
             if param.get("required"):
                 required.append(param_name)
@@ -597,20 +646,21 @@ def _extract_inputs(self, path: str, operation: Dict[str, Any]) -> Tuple[JsonSch
             json_schema = content.get("application/json", {}).get("schema")
             json_schema = self._resolve_ref_obj(json_schema, set()) if json_schema else None
 
-            # Extract examples from request body media type
+            # Examples can live on the media type object and on the schema;
+            # collect both into the normalized 'examples' keyword.
             media_type_obj = content.get("application/json", {})
-            body_examples = self._extract_examples(media_type_obj)
-            
+
             if json_schema:
+                body_examples = self._merge_examples(media_type_obj, json_schema)
                 # Add a single 'body' field to represent the request body
                 body_field = "body"
                 prop = {
                     "description": json_schema.get("description", "Request body"),
-                    **json_schema
+                    **self._schema_without_example_keys(json_schema)
                 }
                 if body_examples:
                     prop["examples"] = body_examples
-                
+
                 properties[body_field] = prop
                 if json_schema.get("required"):
                     required.append(body_field)
@@ -648,11 +698,7 @@ def _extract_outputs(self, operation: Dict[str, Any]) -> JsonSchema:
         json_schema = self._resolve_ref_obj(json_schema, set()) or {}
 
         # Extract examples from response media type and schema level
-        response_examples = list(self._extract_examples(media_type_obj) or []) if media_type_obj else []
-        for ex in self._extract_examples(json_schema) or []:
-            if ex not in response_examples:
-                response_examples.append(ex)
-        response_examples = response_examples or None
+        response_examples = self._merge_examples(media_type_obj, json_schema)
 
         schema_args = {
             "type": json_schema.get("type", "object"),

plugins/communication_protocols/http/tests/test_openapi_converter.py

@@ -218,3 +218,94 @@ def test_openapi_converter_parameter_examples():
     example_value = body_param.examples[0]
     assert example_value["name"] == "Jane Smith"
     assert example_value["email"] == "jane@example.com"
+
+
+def test_openapi_converter_skips_unsupported_methods():
+    """Operations with HTTP methods HttpCallTemplate cannot represent are skipped, not crashed on."""
+    openapi_spec = {
+        "openapi": "3.0.0",
+        "info": {"title": "Test API", "version": "1.0.0"},
+        "paths": {
+            "/things": {
+                "get": {
+                    "operationId": "listThings",
+                    "responses": {"200": {"description": "ok"}},
+                },
+                # OPTIONS/HEAD/TRACE are valid OpenAPI but not in the call template Literal
+                "options": {
+                    "operationId": "optionsThings",
+                    "responses": {"200": {"description": "ok"}},
+                },
+                "head": {
+                    "operationId": "headThings",
+                    "responses": {"200": {"description": "ok"}},
+                },
+                "trace": {
+                    "operationId": "traceThings",
+                    "responses": {"200": {"description": "ok"}},
+                },
+            }
+        },
+    }
+
+    converter = OpenApiConverter(openapi_spec)
+    manual = converter.convert()
+
+    tool_names = {tool.name for tool in manual.tools}
+    assert tool_names == {"listThings"}
+
+
+def test_openapi_converter_schema_level_examples_normalized():
+    """Examples declared at the schema level (not the media type) are normalized into 'examples'."""
+    openapi_spec = {
+        "openapi": "3.0.0",
+        "info": {"title": "Test API", "version": "1.0.0"},
+        "paths": {
+            "/widgets": {
+                "post": {
+                    "operationId": "createWidget",
+                    "requestBody": {
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {"name": {"type": "string"}},
+                                    # schema-level example, not a media-type 'examples' map
+                                    "example": {"name": "Widget A"},
+                                }
+                            }
+                        }
+                    },
+                    "responses": {
+                        "200": {
+                            "description": "ok",
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {"id": {"type": "string"}},
+                                        "example": {"id": "w_1"},
+                                    }
+                                }
+                            },
+                        }
+                    },
+                }
+            }
+        },
+    }
+
+    converter = OpenApiConverter(openapi_spec)
+    manual = converter.convert()
+
+    tool = next((t for t in manual.tools if t.name == "createWidget"), None)
+    assert tool is not None
+
+    body_param = tool.inputs.properties.get("body")
+    assert body_param is not None
+    # schema-level example surfaces in the normalized 'examples' keyword
+    assert body_param.examples == [{"name": "Widget A"}]
+    # raw 'example' key must not leak through as an extra field
+    assert "example" not in body_param.model_dump(by_alias=True)
+
+    assert tool.outputs.examples == [{"id": "w_1"}]