4 ms·

I think we are talking about different things here. I love OpenAPI and wouldn't do a project without it. verify-json is a lightweight way to validate JSON schem

I think we are talking about different things here. I love OpenAPI and wouldn't do a project without it. verify-json is a lightweight way to validate JSON schema and does not intend to change/improve anything about OpenAPI. This is more for client-server JSON schema validations, comes handy when different teams are writing client and server side code. Especially in startups where iterations are rapid.

smoyer 6y ago
A long time ago in a galaxy far, far away, Corba implemented ICDs as "contracts" between parties. It seems like a client and server developed by different teams is still a good use-case for "something" that specifies the contract. In the 2000's, we wrote mil-spec style ICD documents that we attempted to enforce when writing code that had to interact (via a message bus). The benefit of a language/framework agnostic way of performing with something executed in code is a great step forward from just having an ICD document. Note that early Corba, XML-RPC and SOAP/XML could perform this function but people did horrible things to the data (using an indexed array of strings as parameters) that broke both typing and the ability to do type-specific validation. From the way you've phrased your comment, I'm going to assume that the different teams are within the same start-up ... having a versioned, executable is even better when iterations are rapid if there are breaking changes. I've been in enough start-ups to know that things are skipped over to get a product out the door. I also know that the marketing and sales guys will say "we're already using a RESTful/JSON API for our back-end, let's open our API to third-parties to accelerate adoption of our SaaS". Ouch! (but I've been there) I will admit that "back-filling" an OpenAPI specification for an existing service can be pretty daunting ... it's quite a bit easier if you start with the first MVP and iterate the ICD with each iteration of the client and server. Admittedly, we (software developers) still have issues versioning services. It's not so bad for incremental changes but breaking changes to a service where you have to support both older and newer clients is painful.

smoyer 6y ago

A long time ago in a galaxy far, far away, Corba implemented ICDs as "contracts" between parties. It seems like a client and server developed by different teams is still a good use-case for "something" that specifies the contract. In the 2000's, we wrote mil-spec style ICD documents that we attempted to enforce when writing code that had to interact (via a message bus). The benefit of a language/framework agnostic way of performing with something executed in code is a great step forward from just having an ICD document. Note that early Corba, XML-RPC and SOAP/XML could perform this function but people did horrible things to the data (using an indexed array of strings as parameters) that broke both typing and the ability to do type-specific validation. From the way you've phrased your comment, I'm going to assume that the different teams are within the same start-up ... having a versioned, executable is even better when iterations are rapid if there are breaking changes. I've been in enough start-ups to know that things are skipped over to get a product out the door. I also know that the marketing and sales guys will say "we're already using a RESTful/JSON API for our back-end, let's open our API to third-parties to accelerate adoption of our SaaS". Ouch! (but I've been there) I will admit that "back-filling" an OpenAPI specification for an existing service can be pretty daunting ... it's quite a bit easier if you start with the first MVP and iterate the ICD with each iteration of the client and server. Admittedly, we (software developers) still have issues versioning services. It's not so bad for incremental changes but breaking changes to a service where you have to support both older and newer clients is painful.