search

apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.63k stars 2.14k forks source link

Referencing external JSON Schema with schema in API Blueprint #389

Open pksunkara opened 7 years ago

philsturgeon commented 6 years ago

Reposted this comment as it went on #317 first.

We had a big chat about this stuff on http://apibusters.com/002-api-blueprint a while back, and privately elsewhere.

Please remember that most folks aren't asking for MSON keywords to handle validation right now, more that they'd absolutely love JSON Schema files to be referenced in API Blueprint as an input, essentially a replacement for MSON.

# Data Structures

## Cat

+ $schema: structures/foo.json

Or whatever. JSON Schema as an input would absolve a lot of concerns for you folks, and you could work on MSON validation keywords in the background for those interested in getting that done. It's been over a year since we started talking about JSON Schema as input, and I've had to switch everything to OpenAPI to get that, even if their JSON Schema support is a little funky :D

I think we as an API community at large should focus on supporting JSON Schema as a very portable contract and validation format. Building alternatives is probably ok, but we need to be ale to support the portable one and specialist homegrown solutions.

If API Blueprint supports MSON and JSON Schema, and OpenAPI decide support their own approach + JSON Schema, and everyone goes on like that... well at least we have one format for all the tools instead of a million formats that have lossy conversions using thousands of different random old unsupported NPM packages... 😅

grncdr commented 6 years ago

I completely agree with everything Phil said. For me at least, this has been the deciding factor to use Swagger/OAI over API blueprint on multiple projects.