Disclaimer

I understand that I am suggesting a breaking change, but the breaking changes are sometimes being implemented in telegram-bot-api (maintaining compatibility for some time). The introduction of ReplyParameters type kinda resembles what I am suggesting, yet it may be done for better reasons.

Problem

There are a lot of places in bot API where fields like text+entities+parse_mode come together. Together they represent formatting for the text. There are 4 kinds of these groups in different methods and the naming of the fields is barely consistent:

• text, entities, parse_mode
• caption, caption_entities, parse_mode
• quote, quote_entities, quote_parse_mode
• explanation, explanation_entities, explanation_parse_mode

Suggested solution

Group these fields into a type named (as a first suggestion) RichText, so that

{
  //...
  "caption": "123"
  "caption_entities": [...]
  "parse_mode": "HTML"
  //...
}

becomes

{
  //...
  "caption: {
    "text": "123",
    "entitites": [...]
    "parse_mode": "HTML"
  }
  //...
}

Note: I know that the example having both parse_mode and enities is incorrect, just didn't want to split it into two examples for each case.

Cons

• As mentioned before, it's a breaking change. The old formats of course can be supported for some time. This is also a change to a very core feature of the API
• More boilerplate nesting for simple cases (without formatting). This can be softened a bit by allowing a field caption in above example be of type RichText or String

Pros

• Less duplicates in documentation and client-library code.
• Client-library developers can provide type-safe means to produce this rich text and prevent library client form passing HTML text with Markdown parse mode. Nothing prevents library developers from doing so now, but in that case they're responsible for converting data from their input format to telegram-bot-api format which can cause bugs and also confusing for library clients (the more library API is aligned with Telegram API the better)

Additional concern: output rich text

Besides the method arguments, there are data returned as a response or update, which can also contain rich text. In that case there is always no parse_mode. This can be solved by splitting RichText into subtypes:

• RichTextWithEntities
• RichTextMarkdown
• RichTextMarkdownV2
• RichTextHTML

In this case, the input type would be RichText (or String?) and the output type would be RichTextWithEntities.