@sinzone how are the two different enough to not grant a comparison? I didn't mean to sound harsh with my previous comment, I'm looking for the best option, whether that's RAML, GraphQL or anything else. Just trying to learn a bit from the makers :)

@timdorr Keep in mind that expressiveness comes at a cost: the more expressive and flexible a standard, the less tooling (testing, documentation, SDK automation, etc) can be built around it. There is no perfect balance, which is why numerous standards (all with different levels of expressiveness) exist. To put it a different way: Take a look at who is behind, say, Blueprint and RAML. Blueprint is Apiary, which is an API design tool. Of course it's more expressive; that's the point of Apiary. RAML is made by Mulesoft, which is an API management company. Of course they want everything more semantic and machine-readable. There's a place for both; it's up to you to decide which fits your personal use-case the best.

@timdorr @rhabal @allnick on a side note on formats. The Linux Foundation is working with a couple of partners on creating the next generation of Swagger (which is 10X more adopted than everything else, also the oldest) under the OAI https://openapis.org/ (which we support as well - @Mashape we could have created our own format, and we thought about for long time, but decided to support a OSS initiative centered around true neutrality, compared to formats owned by a private business motivated by their own interests). An API description format, should be a commodity, that everybody can contribute & owned by anyone, not a mean to connect your commercial offering.

@bentossell we support Swagger currently; we'll support RAML with enough nudging :) Either way, I'm excited that there's a big movement toward semantically documenting APIs. It's going to create a proliferation of awesome API-related tools (including making @readmeio much better), and I'm excited for it.