RFC: Add '$schema' property at root of the spec 2.x #485
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
JSON schema specifies a standard way for a document to tell what JSON
Schema document can be used to validate it. This is the '/$schema'
property.
Unfortunately this property is strictly disallowed in the Swagger 2.0
JSON schema ('/additionalProperties' is set to false): Swagger authors
decided to use instead the '/swagger' property. This is enough for
humans, but the presence of '/$schema' could be useful for machines to
validate Swagger specifications that use vendor extensions and for which
a JSON schema specifying the schema of those extensions is available.
So we add '/$schema', with a default value of
http://swagger.io/schema/v2.0/schema.json (see
[swagger-api/swagger.io-docs#48](https://github.com/swagger-api/swagger.io/issues/#48))
As this feature is incompatible with the 2.0 schema
('/$schema' is forbidden in 2.0 because '/additionalProperties' is set
to false), setting this value in a document will only be possible if a
version 2.1 of the specification is published with that extension.
dolmen
force-pushed
the
feature/$schema
branch
from
adade9a to
bc06696
Compare
|
Thanks for the explanation, but the better way to make the proposal is by opening a ticket as a feature request rather than a PR. A PR will get lost in the list of proposal most likely, plus there's the risk of someone accidentally merging it. I'd very much appreciate it if you'd submit it as an actual proposal. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
JSON schema specifies a standard way for a document to tell what JSON Schema document can be used to validate it. This is the
/$schemaproperty.Unfortunately this property is strictly disallowed in the Swagger 2.0 JSON schema (
/additionalPropertiesis set to false): Swagger authors decided to use instead the/swaggerproperty. This is enough for humans, but the presence of/$schemacould be useful for machines tovalidate Swagger specifications that use vendor extensions and for which a JSON schema specifying the schema of those extensions is available. That would allow to write a Swagger spec that explicitely points to those extensions.
So we add
/$schema, with a default value of http://swagger.io/schema/v2.0/schema.json (seeswagger-api/swagger.io#48 which is a request to have canonical URLs for Swagger JSON schemas).
As this feature is incompatible with the 2.0 schema (
/$schemais forbidden in 2.0 because/additionalPropertiesis set to false), setting this value in a document will only be possible if a version 2.0.1/2.1 of the specification is published with that extension. So this patch is not designed to be directly merged to the existing schema, but instead to show the required changes to the spec to allow this feature.