Automatically add title and description to generated schema

[alexvoronov]

Is there a way to add "title" and "description" attributes to the generated schema based on e.g. field name?

GUI toolkits like https://github.com/rjsf-team/react-jsonschema-form and https://jsonforms.io/ require "title" attribute to render the form. Pydantic even generates "title" based on the field name if title is not specified explicitly.

I wonder if it is possible to automatically add "title" to every property in the generated schema? Maybe using default conversions that would act on every class or add extra_schema?

Even better would be if I could add "description" to properties based on comment strings extracted by Sphinx, using the following get_field_comment_sphinx:

@functools.lru_cache()
def get_all_field_comments_sphinx(cls: Type) -> Dict[Tuple[str, str], str]:
    source = inspect.getsource(cls)
    parser = sphinx.pycode.parser.Parser(source)
    parser.parse()
    return parser.comments


def get_field_comment_sphinx(cls: Type, field_name: str) -> str:
    comments = get_all_field_comments_sphinx(cls)
    key = (cls.__name__, field_name)
    comment = comments.get(key, "")
    return comment

[wyfo]

Is there a way to add "title" and "description" attributes to the generated schema based on e.g. field name?

There are multiple ways, but they are not easy and documented.

GUI toolkits like https://github.com/rjsf-team/react-jsonschema-form and https://jsonforms.io/ require "title" attribute to render the form.

That's indeed an issue.

Pydantic even generates "title" based on the field name if title is not specified explicitly.

I did want to be as opinionated as Pydantic, and because I had no answer to the question "Should properties' title be capitalized or not?", I've preferred to not add title at all. But I should have given a way to do it easily.

I wonder if it is possible to automatically add "title" to every property in the generated schema?

The immediate solution for this is 8 lines of code:

def add_titles(schema):
    if isinstance(schema, dict):
        for name, prop in schema.get("properties", {}).items():
            prop["title"] = name.capitalize()  # or whatever
        for value in schema.values():
            add_titles(value)
    elif isinstance(schema, list):
        for elt in schema:
            add_titles(elt)

This function can be used to modify in place the schema generated by apischema. But I admit that it's kind of dirty.

apischema.settings.default_schema can also be used.

from typing import Any, Optional

from apischema import settings, schema
from apischema.objects import object_fields
from apischema.schemas import Schema

prev_default_schema = settings.default_schema

def default_schema(tp: Any) -> Optional[Schema]:
    try:
        fields = object_fields(tp)
        def add_titles(schema: dict[str, Any]):
            for field in fields.values():
                schema["properties"][field.alias]["title"] = field.alias.capitalize()
                # field description could be retrieved and inserted here
        return schema(extra=add_titles)
    except Exception:
        return prev_default_schema(tp)

settings.default_schema = default_schema

But this solution is not very convenient too, and settings.default_schema is only used when no schema is registered for a type.

That's the two options I've for now. I will think more about it tonight, but I think I have to add something to make object schema customization easier. I should have time to implement something to include it in v0.16 release this weekend.

[alexvoronov]

Thanks! I indeed already do a number of "patches" to the generated schema, just to conform to what a GUI toolkit wants, I can add titles there as well.

Solution with default_schema looks nice, I could even add comment extraction there, but I believe it will be ignored/lost if I add custom schema elements, like min and max values for a field? If field schema customizations does not count as registering schema for a type, and preserves my default_schema, I can live with that :)

[wyfo]

apischema.settings.default_schema has been deprecated with #215; it means a warning is emitted but it still works. Deprecation will be effective in the next version.
It has been replaced by apischema.settings.base_schema.type. As you can see in the documentation example, base_schema.type/base_schema.field/base_schema.method offers a better and simpler way to customize your schema.

I should have asked you opinion before merging the PR, but was in a hurry and I merged too quickly … However, if you have some remarks about it, don't hesitate and I will open a new PR if needed.

[alexvoronov]

I'm using your solution of modifying generated schema after it is generated, so this change would not affect my existing code. The example you pointed to looks promising, I'll try to switch to base_schema.field in a future version.