feat(core): add explicit examples field to JsonSchema

Merged
H3
5mo ago
+40-0

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.