I'm curious to know the reasoning for going with JSON Schemas instead of Swagger

[c4milo]

I'm asking mostly because Swagger is being mentioned here. It seems you were aware of Swagger but you took a different path. It would be interesting to know the thought process that made you arrive to JSON Schemas instead.

[geemus]

@c4milo swagger seemed to be more of a prescriptive (this is how you should use this) than descriptive (this is how it works) methodology. ie swagger includes fields for what you should name methods in the generated client, which seems tricky given that this varies broadly across languages (and arguably if you are doing things consistently, you should be able to generate the names from docs without too much trouble and following language best practices).

I also found json-schema nice in that it was fairly simple and rather extensible. It seemed like "just enough" detail to have in a schema, whereas swagger felt like too much and too limiting. That said, over time our usage of json-schema grew to be more and more complex, but I still appreciate the simplicity/extensibility and the descriptive style. We have had to create our own tooling, which is a downside, but overall I still like the way the pieces fit together.

I hope that is at least somewhat informative, but certainly happy to discuss further. Thanks!

[zdne]

@geemus Interesting. Can you please point me to an example where you had to extend the JSON Schema? Also, with JSON Hyper Schema expired, do you know whether there is some ongoing development on it?

Thanks!

[geemus]

@zdne sure. A couple examples that come to mind are the example attribute, which we use to help us generate code samples and docs, and the stability attribute, which we use to document expectations around changes to an existing API. We also use a couple additional rel values to make a bit clearer some of the actions. I imagine there are some others, but those are the main ones. In one of the json-schema/hyperschema related repos there is a wiki with discussion about changes, but it seemed like it was moving rather slowly (at best). It is meant to be extensible though, so I think we are legit in what we did and that we can move forward even if the core standard is slower to change.

[c4milo]

@geemus what you mentioned were similar to my conclusions after spending some time with Swagger. It simply doesn't leverage HTTP enough, and instead redefines a lot of things already present in HTTP. I completely agree with you on that JSON Schema is a more concise and web like approach.

[geemus]

Yeah, I think that sums it up well. I felt like json-schema focused on the server side, whereas swagger focused more on the client side (and I was looking for server side descriptive, rather than client side prescriptive).