- May 17, 2016

The new version of the RAML API definition language is here, as announced on the RAML blog by Nial Darbey. In this article, we’ll briefly cover the novelties offered by this new release, and give you useful pointers to dig further.

Mike Stowe, Developer Relations Manager at MuleSoft, gave a presentation about RAML 1.0 and published his slide deck on SlideShare.

So what’s new?

Data models

RAML 1.0 brings a nice and elegant new YAML based syntax for defining data models, in addition to the existing JSON schema support. Here’s an example modeling a Product entity:

    id: number
    name: string
    price: number
    tags: string[]
        length: number
        width: number
        height: number
    warehouseLocation: string

Data models can be imported in other models, to compose them more easily, can be used as schemas or examples, in path variables, query parameters, headers…, and can be stored in external libraries and be namespaced.


Your data models, resourceTypes, traits, schemas, examples can all be stored in a reusable library. This is convenient when you want to share common elements between different APIs in the same project or company. Importing those resources can be done through a namespace, giving you the freedom to pick up what you need or ignore what you don’t need.

In your RAML spec, you’ll write for example:

  Songs: !include libraries/songs.raml

Songs will be your namespace, and then later on reference the Song model with:



When developing APIs, you certainly develop and test it in different environments before moving it to production. How do you deal with those different contexts? How do you change the host URL for example? With RAML 1.0, overlays come to the rescue, to override or complement existing values of your specification.

Your original RAML specification might look like the following:

#RAML 1.0

title: Book library API
  - title: Introduction
    content: Automated access to data
  - title: Licensing
    content: Please respect copyright on our books
  description: The collection of library books
            type: array
              type: object
                title: string
                title: RAML 1.0

And the overlay will define or override the author, title, description, and more, with the following:

#RAML 1.0 Overlay

  extLib: !include lib.raml
masterRef: librarybooks.raml

  author: Christian Vogel
  title: Example API
  description: Cool API
  license: MIT


Instead of vendor extensions in Swagger / Open API Specs, RAML 1.0 introduces “annotations”. Annotations are just new properties in your specification. Additionally, you can combine libraries and overlays to keep annotations separate from your main definition, so they don’t clutter your main definition and can be kept as an external concern.

Breaking changes

You can have a look at the differences between RC-1 and RC-2 if you had tried RC-1 already. And read about the details of the breaking changes between RAML 0.8 and 1.0, summarized below:

  • formParameters are replaced with properties.
  • Sequences and composition from global definitions are removed in favor of fragments and libraries.
  • The date type has been refined with more specialized types.
  • The OAuth 2 authorization grants have been renamed to match the RFC.
  • Support for inline anonymous definitions has been removed for resource types, traits and security schemes.
  • Optional nodes are now limited to methods in resource types only.
  • No support for baseUriParameters on root-level nodes.

Additional information

A couple of weeks ago, Christian Vogel announced the second release candidate for RAML 1.0. To play with RAML 1.0, you can use the JavaScript parser, as well as a brand new Java parser that groks 0.8 and 1.0 (in the v2 branch). The new Java parser still has a few missing bits, but this shouldn’t affect you too much.

If you want to discover RAML, don’t miss this interesting RAML tutorial which guides you through writing a sample API definition. Also have a look at Restlet Studio and APISpark capabilities for importing and exporting RAML definitions (there’s also a screencast). Soon, you’ll be able to use RAML 1.0 in our products as well when RAML 1.0 is ready!

  • Pingback: This week in API land #50 | Restlet - We Know About APIs()

  • Are you supporting raml 1 now?

  • Guillaume Laforge

    Hi Neil, we don’t support it yet, as the Java parser for RAML 1.0 still needs a bit of work before we can integrate it, but it’s definitely on the roadmap to support it! So you shouldn’t have to wait for too long before it’s available.

  • I had just made a RAML 1.0 parser to produce documentation in pdf format: wooooooh, that was really hard! 🙂

  • Johny Ledge

    Java is a high-level programming language.Due to its stability and scalability, you can find Java on mobiles, desktops, large scale applications etc. Java is also gaining big in the field of Internet of Things (IoT). choose the best institute for learning this one is the best
    Java training center in chennai