Enhancing Pydantic Models: Programmatically Generating Titles for JSON Schema

Pydantic, a powerful Python library for data validation and settings management using type annotations, offers flexibility in defining data structures. However, when exporting these structures to JSON Schema, the ability to dynamically generate titles has been a missing piece. This article delves into a feature request proposing the addition of a title_generator to Pydantic, allowing for programmatic title generation for both models and their fields.

The Current State: Static Titles in Pydantic

Currently, Pydantic allows you to set titles for your models and fields using string literals. For models, this is done within the Config class:

from pydantic import BaseModel

class MyDataClass(BaseModel):
    class Config:
        title = "My Data Class"

For individual fields, you can specify a title using the Field constructor:

from pydantic import BaseModel, Field
from typing import List

class MyDataClass(BaseModel):
    matchCriteria: List[str] = Field(default_factory=list, title="Match Criteria")

    class Config:
        title = "My Data Class"

While this approach works, it lacks the dynamism needed in many real-world scenarios where titles need to be generated based on model or field names.

The Feature Request: title_generator for Dynamic Titles

The feature request proposes the introduction of a title_generator attribute within the Config class and a title_generator parameter in the Field constructor. This would enable developers to use Python callables to dynamically generate titles.

• title_generator in Config: This attribute would accept a callable that takes the BaseModel class name as input and returns the desired title.
• title_generator in Field: This parameter would accept a callable that takes the field alias as input and returns the title.

This approach mirrors the existing alias_generator functionality in Pydantic, providing a consistent and intuitive way to generate titles programmatically.

Benefits of Programmatic Title Generation

• Consistency: Enforces a consistent naming convention across your JSON schema.
• Automation: Automates the title generation process, reducing manual effort.
• Flexibility: Allows for complex title generation logic based on model and field names.
• Maintainability: Centralizes title generation logic, making it easier to maintain and update.

Example Implementation

The proposed implementation uses a regular expression to transform camel case or snake case names into more readable titles:

import re
from pydantic import BaseModel, Field
from typing import List

def make_title(name: str):
    def _capitalize(v: str):
        return v[0].upper() + v[1:]
    return re.sub(r"(?<=[a-z])([A-Z])", r" \1", _capitalize(name))

class MyDataClass(BaseModel):
    matchCriteria: List[str] = Field(default_factory=list, title_generator=make_title)

    class Config:
        title_generator=make_title

import json
print(json.dumps(MyDataClass.schema(), indent=2))

This code snippet will produce the following JSON Schema:

{
  "title": "My Data Class",
  "type": "object",
  "properties": {
    "matchCriteria": {
      "title": "Match Criteria",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

As you can see, the title_generator function effectively transformed the class and field names into readable titles.

Conclusion

The proposed addition of a title_generator to Pydantic represents a significant enhancement to the library's functionality. By enabling programmatic title generation, Pydantic models become even more flexible and adaptable to a wider range of use cases. This feature streamlines the development process by automating tasks like creating titles and improving consistency across large projects. This feature will greatly improve development efficiency and reduce manual errors. It is set to be included in future versions of Pydantic. While waiting for this feature, explore other features of Pydantic, such as field validation