Add field descriptions to JSON schema

[ghost]

A lot of tooling implementations have homegrown JSON schema definitions for the OpenAPI format, often with field descriptions providing auto complete hints. Adding object field descriptions from the specification to the JSON schema would make the JSON schema definition more attractive and cover the auto complete use-case, which might be adoption blockers for some projects. If file size is a concern maybe two separate versions with and without descriptions should be created. Object descriptions and usage examples from the spec could be added too.

For example copying the Encoding.contentType field description from https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#encoding-object

Encoding:
    type: object
    properties:
      contentType:
        type: string
        description: "The Content-Type for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types."
      headers:
        type: object
        additionalProperties:
          $ref: '#/definitions/Header'
      style:
        type: string
        enum:
          - form
          - spaceDelimited
          - pipeDelimited
          - deepObject
      explode:
        type: boolean
      allowReserved:
        type: boolean
        default: false
    additionalProperties: false

Example result:

[MikeRalphson]

As previously discussed, I have a script which can port most of the object descriptions from PR #1236 to the work which was merged as #1270.

This would include only descriptions such as

An object representing multipart region encoding for requestBody objects.

for the Encoding object and not any descriptions (as in your example) for properties such as contentType.

Some reasons I feel we should not include full descriptions at the property level:

1. it will be additional work keeping these in sync with the latest patch level versions of the markdown documents
2. it may undermine the status of the markdown documents as the source of truth for the specification
3. JSON schema descriptions do not explicitly support markdown formatting (though this is surmountable)

I'd be interested in others' points of view.

[ghost]

it will be additional work keeping these in sync with the latest patch level versions of the markdown documents

I agree with you this would mean additional work. That can be reduced to some extent with automated extraction (extending your script?). Unfortunately the JSON schema is not a 1:1 mapping so the code would't be that simple.

My request aside, the schema needs to be maintained and changed for further versions anyways. Generating some parts and maybe even field descriptions based off the specification might reduce maintenance costs in the long run.

it may undermine the status of the markdown documents as the source of truth for the specification

If I understand correctly, your concern behind this is that fewer developers would read the specification if they wanted to know the specifics of a field and therefore undermine its status.

Not including field descriptions for the goal that more developers read the specification would not have much impact. A lot of tooling already have their own versions which include field descriptions. Adding them, would help tooling developers converge to the official schema which is often times closer to the official specification then their homegrown counterparts.

On top of that links to the specific section of the specification could be part of the field description, helping them to promote the offical markdown documents as the source of truth.

While the links in the descriptions would not be clickable, a lot of implementations are open source. Like Swagger Editor or VSCode. I can open an issue/feature request for Markdown rendering of the description, maybe behind a feature flag, if wanted.

[tedepstein]

I don't have a strong objection to adding these descriptions, and I am not usually the one to argue against scope creep. (More often than not, I am the scope creep.)

But this does seem like a slippery slope in terms of the TSC and TDC's area of responsibility, and allocation of time and bandwidth.

The primary purpose of this group is to evolve the specification. This meta-schema for OpenAPI was added by popular demand as a non-normative starting point or reference point for implementations. Any serious implementation will need to do a lot of things that are not encapsulated in this schema, including semantic validations, error reporting, code assist (specifically for editors), etc.

Different implementations, written on different platforms for different users and use cases, will have different perspectives on the optimal length, format, style, and content of these object and property descriptions. Writing and maintaining these will likely generate a fair amount of conversation and debate over time, with additional pull requests that have to be discussed and reviewed by the TSC, who are already coping with a large backlog of PRs. And if there are disparate opinions, based on different use cases, it just seems like this could be a distraction from the work that needs to happen on the spec.

Forking and modifying the schema to add descriptions is not hard. Scripting an overlay to merge descriptions into the schema is also feasible, as @MikeRalphson has described. Even setting up a separate repo to maintain a particular opinionated version of the schema is fine, if someone wants to do that. I just don't think the specification project is the best place for this.

[handrews]

@MikeRalphson I agree with you and @tedepstein on this one. We used to keep descriptions in the JSON Schema meta-schemas, but it became a source of bugs and confusion so we stripped them out. Different people will also have different priorities for what should be in the descriptions, how much detail they should have, what writing style they should use, and even what language(s) they should be in.

I'd recommend closing this as a wontfix since it's been half a year since the last comment anyway.

[handrews]

No objections to prior recommendation to close as wontfix, so closing.

[rmannibucau]

Hi,

what about providing a full described schema and having a build phase which drops it.
can enable to deliver openapi.described.json and openapi.json schemas and let consumers use it or not.

Current state makes it quite rough in any editor - implying it is forked.

Any hope it gets reopened and fixed?

Romain

[rmannibucau]

Up, any hope we get back descriptions since it is really important for human interactions on schema first or (generated) schema review. (coming from #2249)