Thoughts on OpenAPI JSON Schema descriptions

I recently posted that I wish the OpenAPI JSON Schema still had descriptions like it used to on v2.0. My post triggered a discussion on the official OpenAPI Slack, explaining they had removed the descriptions to avoid maintenance costs related to keeping the descriptions in sync in several places. I joined the discussion on Slack to share my perspective. The following is a transcript of what I wrote for future reference.

I’m looking at https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.1/schema.yaml and using it as the JSON Schema I refer to in the following comments.

• Using $comment is great. However, according to the spec, “JSON schema implementations aren’t allowed to attach any meaning or behavior to it whatsoever.” Comments are useful for leaving notes to other editors that aren’t meant to be passed to the end user. (see https://json-schema.org/understanding-json-schema/reference/comments)
• Most $comments are being used to reference the corresponding section of the OpenAPI spec. While that’s interesting, the links to the reference are all broken (404). As an example, the $comment on paths has the value of https://spec.openapis.org/oas/v3.1#paths-object. Instead, It looks like the correct value should be https://spec.openapis.org/oas/v3.1.0.html#paths-object.
• The description on the exact section of the spec is great for human consumption. On the other hand, extracting the information in a programmatic way is not easy.

My suggestions:

• Using the JSON Schema description annotation to describe what each OpenAPI schema object is.
• Because I see that maintenance cost is the reason why descriptions were removed, why not use the JSON Schema as the source of truth? Then, the sections of the spec could be programmatically generated from the information on the schema, avoiding maintaining two separate documents.

I might, obviously, be missing many other details. However, I wanted to share my opinion in case anyone finds it interesting.