Proposal: add '$schema' property at root of the spec 2.x

[dolmen]

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 (following previous versions). 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. That would allow to write a Swagger spec that explicitely points to the JSON schema that validates those extensions.

So I propose to add /$schema, with a default value of http://swagger.io/schema/v2.0/schema.json (see swagger-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 (/$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.0.1/2.1 of the specification is published with that extension.

An implementation in the JSON Schema is proposed in #485.

[MrTrick]

I agree, it would be very useful.

Several validation libraries will use the "$schema" property to automatically validate the document against that schema. I can include "$schema": "http://swagger.io/schema/v2.0/schema.json" in my swagger spec, but all it will do is tell me that it's invalid because of that attribute. ^_^

[dolmen]

@webron Proposal for OpenAPI.next

[jpstrikesback]

#561 provides a nice reason to endorse this, some of the benefits past that are listed above.

[dolmen]

@webron about your comment in #561

The OpenAPI spec is not JSON Schema. It uses it to describe input/output, it provides it as a limited form of validation, but it is not the same.

I agree that the OpenAPI spec is not JSON Schema. But an OpenAPI document is written in JSON and the OpenAPI specification itself is described with a JSON Schema (that I agree does not validate the spec rules comprehensively) and it would be helpful to be able to use a JSON Schema validator to do the basic validations.
And it would be also particularly useful to be able to use a JSON Schema validator to validate an (OpenAPI+extensions) document against a JSON Schema of that OpenAPI+extensions. That would be helpful to be able to benefit from existing tools.

[webron]

I'm afraid I still fail to see why this needs to be part of the spec. For JSON Schema documents, I get the benefit, but to have each OpenAPI specification point to a JSON Schema that partially validates it, and it would be the same JSON Schema for all specs, there's no added value in it. This is a tooling issue - it can read the version of the spec and map that to the JSON Schema it can use to validate it with which is constant. Why bloat specs to add that detail which is constant and can be derived from other parts of the spec? If this comes instead of #561 - that may make sense.

[webron]

Parent issue: #560

[fehguy]

This is helpful for validation, but not helpful from the tooling point of view. Please see my comments here for what I feel are pros and cons.

[webron]

We have decided to not add support for $schema.