Update on RAML 1.0 and Tooling

By : Uri Sarid , christianvogel
December 1, 2015
Category : News , Tooling , Updates
Tags

Wow, the 2 weeks since our last blog posts have been amazing, again. We’ve received an incredible amount of great feedback for the RAML 1.0 RC specification itself, and for the tooling (especially API Workbench), via email, and twitter, and the RAML.org forum, and github, even in person. Reading all these has been a real pleasure, and had demonstrated not only that things are on the right track with 1.0 and the tooling but also generally the value that a very broad community gets from RAML and its ecosystem. So where are things now – how close are we to finalizing 1.0?

It’s been a month since the 1.0 RC was published, and it’s now looking like it’ll take another couple of weeks or so to fully finalize it. We’re making a lot of improvements in the wording and in the specificity, correcting some typos and examples, disambiguating in a few remaining places, and also tweaking some functionality based on this very constructive feedback. Here are highlights of those tweaks and improvements:

  • the standard for the date format will change from RFC2616 to RFC3339 (see the forum discussion, issue 202, and issue 15)
  • we’re simplifying further how one specifies annotation values (see issue 196)
  • we will add a section on overloading to prescribe how RAML 1.0 handles overlapping resources and methods (see issue 199)
  • we’re clarifying the “deprecation for schemas” wording so it’s manifest that JSON and XML Schema support is not going away, just the keywords “schema” and “schemas” are deprecated in favor of “type” and “types” (see issue 200)
  • we’re improving how libraries are included into RAML specs via uses (see issue 207 and issue 204)

You have full visibility on all the issues mentioned above and more on the dedicated raml-spec Github account. To incorporate all this great feedback, we’re going to postpone a bit the finalization of RAML 1.0 until later in December, and make sure we get it right.

And on the tooling front?

Naturally, with the tweaked RAML 1.0 spec, we also need to tweak the parsers – plus we’ve been working with consumers of the parsers to improve and finalize their APIs. Look for those parsers (JavaScript and Java) to get updated and finalized later in December as well.

As for other tools – look for the latest announcements regarding API Workbench later this week on the MuleSoft blog as well as other RAML 1.0 tooling and projects we’ll be adding to the projects page.