feat(core): add explicit examples field to JsonSchema
What
Declares examples as a first-class field on JsonSchema:
examples: Optional[List[JsonType]] = None
Why
JsonSchema previously accepted examples only via model_config extra="allow". That works at runtime but leaves the field:
- untyped — no validation, type checkers blind to it
- undocumented — missing from the docstring
Attributes - fragile — relies on extra-field behavior that could change
This is the JSON Schema examples keyword and belongs in the model explicitly.
Context
Follow-up to #88 (OpenAPI converter examples parsing), which currently depends on the extra-field fallback to carry parsed examples through. With this field declared, that feature rests on a real, validated contract.
Tests
Adds core/tests/data/test_tool_schema.py:
- field is declared in
model_fields - defaults to
None - survives serialize → validate roundtrip
- accepts mixed JSON value types
All 4 pass. No serialization change (model_dump(by_alias=True) already included extra fields; now it's a declared one).
🤖 Generated with Claude Code
Summary by cubic
Add an explicit examples: Optional[List[JsonType]] field to JsonSchema so the JSON Schema examples keyword is typed, validated, and documented. This removes reliance on extra="allow", keeps serialization unchanged, and stabilizes the OpenAPI converter’s examples parsing.