Host schema publicly

[webron]

In order to accomplish #103 elegantly, we should host the json schema for the 2.0 spec under the swagger.io domain. Probably something like http://swagger.io/schemas/v2.0/schema (based on json-schema's id declaration "id": "http://json-schema.org/draft-04/schema#").

[fehguy]

here you go:

http://swagger.io/v2/schema.json

This proxies to here: https://raw.githubusercontent.com/wordnik/swagger-spec/master/schemas/v2.0/schema.json

So updates are immediate.

[webron]

Is it possible to set the content-type to application/json?

[fehguy]

Sure, just updated it

[fehguy]

note, i can change the name to schema instead of schema.json if you prefer

[fehguy]

ok before we make this the "official" schema location, I may add a subdomain so it can live on a CDN instead of our server for performance.

[mohsen1]

How you handle versioning with this? Is it always going to server the latest? How can one get a fixed version?

NPM solves all those problems! Why don't you separate the schema folder into a separate repo and use it via npm here? that way it's going to be always up to date (because swagger-spec uses it) and people can use older versions much easier

[fehguy]

Because many people want to reference the spec outside of a copy that they maintain. It's not a requirement to use but this will make the latest schema available without npm, etc

Eventually I'd prefer to have this hosted on a cdn

[mohsen1]

Understood. Please make sure you leave older versions there too. I would like to lock my version if I were to use the schema from the CDN

[earth2marsh]

👍 to having versions addressable. Can this be treated like Google hosts libraries like jQuery?

Specify a version like:
//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js

So for the schema, it might live at:
//cdn.swagger.io/schemas/2.0.0.json

… and a minor rev might be:
//cdn.swagger.io/schemas/2.0.1.json

A nice-to-have might be if a digit could be replaced by an x, such as:
//cdn.swagger.io/schemas/2.x.x.json
… for all revs of the 2nd gen schema.

Minor revs could be:
//cdn.swagger.io/schemas/2.0.x.json

Also, this connotes a semver approach to schemas. :)

[webron]

I don't think that's the right approach. I'm trying to find out if we can add a property to the schema saying which version it is, but the schema is and always will be 2.0 until we release 2.1. Adding revisions or versions to the schema name itself will just confuse users. Since the schema itself is work in progress at the moment, it will have updates. Once that's done, it may have fixes but no additions.

[earth2marsh]

Over the last 6 weeks changes to the schema to correct bugs have broken projects like swagger-tools. Having a minor version like 2.0.1 be directly addressable would allow folks to control their dependency on the schema. If it were a property of the schema, then the ground could shift underneath your app, no?

[mohsen1]

In swagger-schema-official I used the short commit sha1 for versioning

versions:
   [ '1.2.0',
     '2.0.0-a33091a',
     '2.0.0-b6411e9' ]

It would be more semantic to follow the same approach as the NPM

[webron]

Yes, this what happens when things are being worked on concurrently. I'm not saying there shouldn't be a version control, I just don't think the file name is the correct way. The current schema has an "id" tag which points to a URL hosting the schema, and that's going to stay the same (though I admit we may change the location of the schema as stated in this issue, again, work in progress).

2.0 should always be the most up to date version. If you want to to have additional copies per revision, that's fine by me, but we need to see how and where that is managed.

[webron]

@earth2marsh, @mohsen1 - I have a feeling we're talking about two separate things (and please correct me if I'm wrong).

Your concern with the versioning of the schema is with regards to the packaged schema and keeping proper versions of it for development purposes.

I'm talking about the schema as it is presented in this repository and as it is exposed publicly per this issue.

If that's the case, then I think the solution should come in a different way, but I'll go into details if you confirm this.