Search code examples
openapi

How to annotate a string property in OpenAPI as allowing multi-line text

Context: We want to control our UI as much as possible from the OpenAPI modelling of our entities.

Question: Using OpenAPI 3.1.0, is there an established way of declaring that a string property is meant to contain longer, multi-line text, and not just a short one?

E.g. we'd like to place such an annotation to properties like curriculumVitae, as opposed to surname, so that the UI knows to use a bigger text field and maybe a different layout.

Ideas that I came up with:

  • Use something like contentMediaType: text/plain. This does not exactly imply anything about the text length, but would typically not be used for "short" properties like surname. So, it could be perused in our context.
  • Introduce extension attributes like x-columns and x-rows. This feels out of place in an OpenAPI document.
  • Create a regex that allows line breaks and use it as pattern for the property. This only really discriminates if all single-line string properties carry a pattern that excludes newlines. So, it's not really practical.
  • Define my own format as e.g. format: multi-line. This would work within one system, but be useless to any tool outside that system. At least it is somehow in line with other hints for correct UI representation, like format: date-time or format: password.
Solution

  • Using OpenAPI 3.1.0, is there an established way of declaring that a string property is meant to contain longer, multi-line text, and not just a short one?

    No, JSON Schema (hence OpenAPI) doesn't have any concept / notation for multi-line strings.

    edit: I think the most semantic would be your 4th option (format: multi-line) and make your tooling understand that.