fix: make descriptions/examples available in JSON schema output

[jsstevenson]

This PR makes two changes

1. it provides the Code example within json_schema_extra rather than the example keyword. This resolves a small but annoying deprecation warning. It also requires ticking up the Pydantic pin that just got changed a few days ago, though.

2. It handles descriptions in RootModels to ensure that they're included in the generated JSON schema output (as used by applications like FastAPI). Currently, we supply descriptions to primitive-y types like Condition and Code using the description keyword. Counterintuitively, that argument doesn't actually get used in the JSON schema output, as far as I can tell. Instead, Pydantic first checks if there's a description in the json_schema_extra arg, and if not, it just uses the class docstring (otherwise, no description).

The simple way out is to just take the description text and supply them as docstrings. This, however, includes a bunch of unsightly newlines and extra spaces. Alternatively, we could include descriptions a second time, but under json_schema_extra=, not description=.

from pprint import PrettyPrinter
from pydantic import BaseModel, RootModel, Field

class RootClassFirst(RootModel):
    """Docstring description"""
    root: str = Field(
        ...,
        description="Arg description",
        json_schema_extra={"description": "JSONschema description"}
    )

class RootClassSecond(RootModel):
    """Docstring description"""
    root: str = Field(..., description="Arg description")

class RootClassThird(RootModel):
    root: str = Field(..., description="Arg description")

class Container(BaseModel):
    one: RootClassFirst = Field(..., description="container arg description")
    two: RootClassSecond = Field(..., description="container arg description", json_schema_extra={"description": "container json schema description"})
    three: RootClassThird = Field(..., )
    four: RootClassSecond = Field(..., )


instance = Container(one="a", two="b", three="c", four="d")
ppr = PrettyPrinter(indent=2)
ppr.pprint(instance.model_json_schema())

[ 2-alpha ⚙ venv] ~/code/vrs-python % python3 scratch.py
{ '$defs': { 'RootClassFirst': { 'description': 'JSONschema description',
                                 'title': 'RootClassFirst',
                                 'type': 'string'},
             'RootClassSecond': { 'description': 'Docstring description',
                                  'title': 'RootClassSecond',
                                  'type': 'string'},
             'RootClassThird': {'title': 'RootClassThird', 'type': 'string'}},
  'properties': { 'four': {'$ref': '#/$defs/RootClassSecond'},
                  'one': { 'allOf': [{'$ref': '#/$defs/RootClassFirst'}],
                           'description': 'container arg description'},
                  'three': {'$ref': '#/$defs/RootClassThird'},
                  'two': { 'allOf': [{'$ref': '#/$defs/RootClassSecond'}],
                           'description': 'container json schema description'}},
  'required': ['one', 'two', 'three', 'four'],
  'title': 'Container',
  'type': 'object'}