RAML 1.0 / 200 Tutorial: Schemas vs Types


#1

Hi,

TL;TR: Is the 200 Tutorial up to RAML 1.0 regarding the canonical use of Types vs (included) Schemas?

The 200 Tutorial explains a useful feature of schemas, how to extract them into .schema file and include in .raml file.

RAML supported features is the possibility of defining schemas (…)
One interesting RAML feature is the ability to extract the schemas and reference them by name
(…) Improve RAML readability

This seems obvious and I had no question about it. Until, I stumbled upon the Using RAML 1.0 Like a Pro
presentation by MuleSoft.
Slide 23 says:

RAML 0.8 was a good start
The bad stuff:

  • JSON Schema
  • YAML !include

Then, I came across RAML 1.0 introductory articles by Baeldung, where the author(s) first mention:

legacy APIs that use JSON schema

and

JSON schema can be used in lieu of data types for backward compatibility with an earlier version of RAML.
cover basic RAML 1.0 syntax and file structure.

and eventually:

Before data types were introduced in RAML 1.0, objects, request bodies, and response bodies were defined using JSON Schema. Using data types can be very powerful, but there are cases where you still want to use JSON Schema. In RAML 0.8 you defined your schemas using the root level schemas section. That is still valid, but it is recommended to use the types section instead since the use of schemas may be deprecated in a future version.

Combinging all the cues together, I have an impression that starting off with JSON Schema is no longer recommended in RAML 1.0 and Types are preferred. That also means the RAML 200 Tutorial is out of date.

Is my deduction correct?

BTW, reporting Issues is not available for https://github.com/raml-org/raml-tutorial-200

I have just found the RAML 1.0 DataTypes vs JSON/XML discussion thread which sounds helpful, but it does not clarify all the pros & cons.

Regards,
Mateusz


#2

Hi, we are currently planning out the new tutorial that will use RAML 1.0. See here for more information http://forums.raml.org/t/sneak-peek-raml-org-tutorial-whats-gonna-happen/1425. I will give you an answer on the other thread about RAML 1.0 DataTypes vs JSON/XML, but let me quickly summarize. RAML DataTypes gives you an abstraction layer on top of JSON / XML using a very user-friendly language (YAML). It is not a “vs” between the different formats as the serialization of the RAML types will be JSON or XML.


#3

The new tutorial plan looks great.

Thanks for the clarification, it makes sense.

Hopefully, I will deduce it right, that since RAML DataTypes are a user-friendly abstraction, it is recommended to try it first, especially while starting with RAML. In case a designer notices shortage of DataTypes features, she might switch to JSON / XML schema notation.


#4

Please take the survey if you want to help improving it. We will shortly publish the outline on our Github repo (also linked in the post).


#5

Sure, ~I will~. Done.

p.s. I’ve updated my answer above.


#6

I have been consistently using the JSON Schema associated with each example in my applications directly for request validation (using express-jsonschema-validator), and returning 400’s when and endpoint received a malformed request.

Can I ask what was wrong with the 1-to-1 relationship between an example (or array of examples) and a schema that’s used to describe valid objects?


#7

Not completely sure what you ask. Could you please elaborate a little bit more on your use case?