Why use RAML data types?

I was recently asked: “Why should I use RAML data types when I can embed JSON schemas directly in my API definitions?”.

I thought providing a simple side-by-side example would speak for itself. As I was writing the example, I thought it would be worth sharing.

Here’s an API definition with two JSON schemas:

And here’s an equivalent using RAML data types:

Not that one is better than the other, and the nice part is that you can use either or both. However, the RAML type system makes schemas a lot easier to read, and a lot more concise because RAML types can be re-used and inherited from throughout an API definition.