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 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
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.
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.