Host schema publicly

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#").

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.

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

Sure, just updated it

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

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.

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

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

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

👍 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. :)

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.

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?

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

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.

@earth2marsh

@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.

@webron

@webron I think we agreed this should be the issue tracking how/when we deploy schema updates. Including deploying new revisions of the OAS 3.1 JSON Schema vocabulary and dialect meta-schemas which don't currently have dates in their $ids. ~~Which I think happened because I wrote them as tentative proposals and then by the time OAS 3.1 shipped I wasn't around to catch that sort of thing.~~

I've been handling schema deployment. I don't usually prepare a deployment for every change, but tend to wait a little while in case more changes come in (they usually come in waves). There are currently two changes that have been merged but not deployed yet and one open PR.

Here's the process I've been following for deployment

Update release dates in
- schema.yaml
- schema-base.yaml (Don't forget the one in the $ref)
- tests/v3.1/test.js
Generate the JSON versions from the YAML versions
- The README says to only modify the YAML version, but contributors usually include changes to both. So, this step is usually just a sanity check.
Run the tests
- The tests are very minimal and haven't been added to since they were first added, but I make sure that we at least don't break what we have.
Deploy the schemas
- Add the schemas to the gh-pages branch
- Update the latest symlink to point to the newest version
Other stuff I'm forgetting about ???

Here's an example of a deploy I've done in the past

Including deploying new revisions of the OAS 3.1 JSON Schema vocabulary and dialect meta-schemas which don't currently have dates in their $ids. Which I think happened because I wrote them as tentative proposals and then by the time OAS 3.1 shipped I wasn't around to catch that sort of thing.

Actually, I wrote those meta-schemas. I didn't include a date in the schema for the same reasons we don't include one in JSON Schema meta-schemas. The $ids of meta-schemas are what schemas authors use in $schema to indicate the version of JSON Schema their schema is using. If we version meta-schemas, users would need to update all of their schemas that declare this dialect every time we release a bugfix. There are lots of reasons that's not a good user experience.

To avoid this, at JSON Schema, any time we need to make a fix in the meta-schema, we've always just fixed it and kept the same $id. This has never cause a problem. I intended for these meta-schemas to be maintained the same way, but so far, there hasn't been a need to update the vocabulary/dialect meta-schemas.

Ideally, I'd think that meta-schemas probably should be versioned, but there should also be an unversioned URI that's effectively a redirect to latest version that the vast majority of users would use for $schema rather than the versioned URI.

I'm happy to hand the schema maintenance and deployment process over to whoever wants it. I've always just done the minimum to keep it afloat, so it would benefit from someone actually putting effort into improving this process.

The date-in-$id policy should be the same for all the OAS schemas (whether they are JSON Schema meta-schemas or not). I'm fine with whatever policy @OAI/tsc wants (date or no date), as long as it is consistent. Having two different policies is worse UX than either individual policy. (Also, my apologies for mis-remembering who wrote those!)

I'm closing this now very long and very out-of-date (aside from the last three comments) issue as too confusing for current tracking. Please use the following:

Define and document our schema publishing process #3715 contains the last three comments above for continuing the discussion of publishing schemas on our own sites
Schema development: main or branch, in parallel or at release time? #3716 tracks the process questions around when and why we update schemas
Define and document branch strategy for the spec, both development and publishing #3677 tracks general branching policy decisions (most schema questions were split to Schema development: main or branch, in parallel or at release time? #3716 but this is still related)
npm package not published? #2400 tracks publishing schemas to NPM, which is distinct from our own site publishing in Define and document our schema publishing process #3715

fix: Correctly validate paths using $ref (#2485)

Navigation Menu

Repository navigation

Host schema publicly #151

16 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Host schema publicly #151

Description

Activity

fehguy commented on Oct 14, 2014

webron commented on Oct 14, 2014

fehguy commented on Oct 14, 2014

fehguy commented on Oct 14, 2014

fehguy commented on Oct 14, 2014

mohsen1 commented on Oct 14, 2014

fehguy commented on Oct 14, 2014

mohsen1 commented on Oct 14, 2014

earth2marsh commented on Oct 14, 2014

webron commented on Oct 14, 2014

earth2marsh commented on Oct 14, 2014

mohsen1 commented on Oct 14, 2014

webron commented on Oct 14, 2014

webron commented on Oct 14, 2014

16 remaining items

handrews commented on May 21, 2023

jdesrosiers commented on May 24, 2023

handrews commented on May 24, 2023

handrews commented on Apr 18, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions