Add field descriptions to JSON schema

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:

[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.

[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