feat(core): add explicit examples field to JsonSchema

JsonSchema previously accepted `examples` only via `extra="allow"`, leaving
it untyped, undocumented, and invisible to type checkers. Declare it as
Optional[List[JsonType]] so the JSON Schema `examples` keyword is a
first-class, validated field.

Supports PR universal-tool-calling-protocol#88 (OpenAPI converter examples parsing), which currently
relies on the extra-field fallback.

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

Author: h3xxit

core/src/utcp/data/tool.py

@@ -38,6 +38,7 @@ class JsonSchema(BaseModel):
         default: Optional schema default value.
         format: Optional schema format.
         additionalProperties: Optional schema additional properties.
+        examples: Optional list of example values for the schema.
     """
     schema_: Optional[str] = Field(None, alias="$schema")
     id_: Optional[str] = Field(None, alias="$id")
@@ -50,6 +51,7 @@ class JsonSchema(BaseModel):
     enum: Optional[List[JsonType]] = None
     const: Optional[JsonType] = None
     default: Optional[JsonType] = None
+    examples: Optional[List[JsonType]] = None
     format: Optional[str] = None
     additionalProperties: Optional[Union[bool, "JsonSchema"]] = None
     pattern: Optional[str] = None

core/tests/data/__init__.py

@@ -0,0 +1,38 @@
+"""Tests for the JsonSchema model, including the `examples` field."""
+
+from utcp.data.tool import JsonSchema, JsonSchemaSerializer
+
+
+def test_jsonschema_examples_field_is_typed():
+    """`examples` is a declared field, not just an extra attribute."""
+    assert "examples" in JsonSchema.model_fields
+
+    schema = JsonSchema(type="string", examples=["user123", "user456"])
+    assert schema.examples == ["user123", "user456"]
+
+
+def test_jsonschema_examples_default_none():
+    """`examples` defaults to None when absent."""
+    schema = JsonSchema(type="string")
+    assert schema.examples is None
+
+
+def test_jsonschema_examples_roundtrip():
+    """`examples` survives serialize -> validate roundtrip."""
+    serializer = JsonSchemaSerializer()
+    schema = JsonSchema(
+        type="object",
+        examples=[{"id": "user123", "name": "John Doe"}],
+    )
+
+    as_dict = serializer.to_dict(schema)
+    assert as_dict["examples"] == [{"id": "user123", "name": "John Doe"}]
+
+    restored = serializer.validate_dict(as_dict)
+    assert restored.examples == schema.examples
+
+
+def test_jsonschema_examples_allows_mixed_json_types():
+    """`examples` accepts any JSON value (string, bool, number, object)."""
+    schema = JsonSchema(examples=["a", True, 1, 1.5, None, {"k": "v"}, [1, 2]])
+    assert schema.examples == ["a", True, 1, 1.5, None, {"k": "v"}, [1, 2]]