Add field descriptions to JSON schema
See original GitHub issueA 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:
Issue Analytics
- State:
- Created 4 years ago
- Reactions:1
- Comments:6 (4 by maintainers)
Top 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 >
Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free
Top Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
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.
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