Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Add field descriptions to JSON schema

See original GitHub issue

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

    type: object
        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."
        type: object
          $ref: '#/definitions/Header'
        type: string
          - form
          - spaceDelimited
          - pipeDelimited
          - deepObject
        type: boolean
        type: boolean
        default: false
    additionalProperties: false

Example result: Screenshot from 2019-06-13 01-39-19

Issue Analytics

  • State:closed
  • Created 4 years ago
  • Reactions:1
  • Comments:6 (4 by maintainers)

github_iconTop GitHub Comments

tedepsteincommented, Jun 13, 2019

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.

rmannibucaucommented, Jun 2, 2020


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?


Read more comments on GitHub >

github_iconTop Results From Across the Web

What is the purpose of the "description" field in JSON Schemas?
fields is to decorate a user interface with information about the data produced by this user interface.
Read more >
Getting Started Step-By-Step - JSON Schema
In JSON Schema terms, we update our schema to add: The properties validation keyword. The productId key. description schema annotation and type validation ......
Read more >
JSON schema for creating a content type - Contentstack
JSON Schema of Fields · Note: The JSON Rich Text Editor will have the same formatting options as the HTML-based RTE that can...
Read more >
JSON Schema Examples Tutorial - MongoDB
JSON Schema is an IETF standard providing a format for what JSON data is required for a given application and how to interact...
Read more >
Specifying a schema | BigQuery - Google Cloud
Option 1: Use Add field and specify each field's name, type, and mode. · Option 2: Click Edit as text and paste the...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found