RAML 1.0 DataTypes vs JSON/XML


#1

Hi all,

I’ve been working with RAML for quite a while now. With the release of RAML 1.0, ‘RAML Types’ have been added to the standard. According to the documentation, RAML Types can be used instead of JSON and XML schemas.

I do have a few questions regarding ‘RAML Types’:

  1. How about validation? Is it of the same level as XSD’s or JSON Schemas?
  2. If you may create an API from the ground up, when/why should you choose ‘RAML Types’ above JSON or XML?

Thanks in advance!


#2

I would argue about that types can be used “instead” of JSON/XML. It’s more a complimentary ability to that and helps to easier describe your data w/o much overhead. Consumer in the end will still consume JSON, XML, or something else. Types are used only for description of your data, not the consumption yet.

How about validation? Is it of the same level as XSD’s or JSON Schemas?

Mhmhmm as types are based on the YAML language the overall syntax is validated and all examples are validated against the type definition as well. Is that what you were looking for?

If you may create an API from the ground up, when/why should you choose ‘RAML Types’ above JSON or XML?

See my response in the beginning. Its not an “either … or” here. Types are definitely easier to describe your data w/o all the overhead that comes with JSON or XML.


#3

Hi,

This topic is unclear to me too and I have asked related question in RAML 1.0 / 200 Tutorial: Schemas vs Types.

Types are used only for description of your data, not the consumption yet

I assume RAML file is the description part here, then what is the consumption?

Its not an “either … or” here.

Then, when to use / prefer Types and when Schemas?

I’d appreciate any clarifications about these two animals.

Regards,
Mateusz


#4

It is not a when to use what. RAML DataTypes gives you an abstraction on top of JSON or XML taking away the burden to care about the serialization format when modeling your data and w/o all the overhead that comes with JSON or XML. In the end, RAML DataTypes get serialized into its respective format (JSON / XML) depending on your media type.

In this case, the consumption and what your API returns will still be JSON / XML.


#5

Christian, this makes perfect sense now.
Thanks a lot!


#6

I would sum it up that you can describe your models with RAML Types in a more readable format than JSON Schema of XML Schema. If your team uses something to do diffs against changes, it will be easier to understand in my opinion than trying to diff JSON Schemas to see what has changed. I think it lends well to the ease of using RAML in a similar way. One nice thing I have seen from the Atom IDE is you can view RAML Types in the generated console API window as JSON or XML depending on the media type specified.


#7

Kevin,

That is a very helpful addition.

Regarding Atom IDE, do you mean the API Workbench?
I’ve just started using it myself and it’s proved very useful, but I haven’t discovered all its features yet.

Regards,
Mat


#8

Hi yes, I did mean API Workbench. Thank you for the correction. There is still work being done with fixes/updates, seems about every week or two I see updates for the API Workbench.


#9

Exactly. It was meant to be a playground to provide feedback on the early version of the specification and we are currently working on improving it a lot. We usually do weekly updates with bug fixes and improvements to the architecture.


#10

Thanks guys!

Yes, it’s an awesome tool, cheers.