RAML 1.0 Candidate Specification Announced

The RAML Workgroup has announced plans for RAML 1.0 Final Candidate to be published at the end of this month. RAML stands for RESTful API Modeling Language and is one of several API description specifications than can be used to design and document APIs. The announcement was made in a blog post on the RAML.org Web site by Uri Sarid, a founding member of RAML.org and CTO of MuleSoft (MuleSoft is the parent company of ProgrammableWeb). RAML 1.0 will include a few significant changes that will dramatically improve modeling capabilities while still maintaining the simplicity of RAML. RAML 1.0 will include improvements to data types, examples, annotations, overlays, libraries, and more.

The Box API expressed in RAML 1.0, showing a glimpse of the new unified data type system and of reusable API libraries.

The RAML Workgroup has been studying the growing list of candidates for the next version of RAML for nearly a year. The group also studied issues brought up in other API description language community groups like Swagger and API Blueprint.

While there was a fairly long list of changes and new features suggested by the RAML community, the workgroup decided to make a few changes that would greatly improve API modeling without adding code bloat or unnecessary complexity to RAML.

RAML 1.0 improvements will include (but not limited to):

  • Data Types – Data is now modeled as a set of reusable types, with a clean YAML-based syntax. This is a streamlined way to model data wherever it appears in an API.
  • Examples – RAML now allows every part of the API to be documented with multiple examples, expressed in YAML.
  • Annotations – Annotations can now be declared, typed, and then applied in various places in the RAML syntax.
  • Overlays – Non-structural aspects of the API such as descriptions, annotations, etc can be separated from the main RAML file and kept in separate files. A RAML processor can then overlay the separate files on the main RAML file making it possible for layers of metadata to be added without weighing down the interface itself.
  • Libraries - Sets of reusable assets can be contained in RAML 1.0 libraries. The libraries can be imported into an API definition using the standard RAML “!include” tag.

The RAML Workgroup plans on finalizing and publishing the RAML 1.0 specification by the end of this month. However, those that prefer RAML 0.8 may continue to use it. RAML 1.0 is a continuation of RAML's primary design principle, simplicity; RAML 1.0 will be simple to write, simple to read, simple to reuse.

Be sure to read the next RAML article: RAML Workgroup Ships Version 1.0 of the RESTful API Modeling Language