OAS and RAML are two popular API description formats. Although they were designed for slightly different purposes, many API owners only come to use one or the other, begging the question: which of the two should you choose?

In this article, we offer a concise comparison of OpenAPI Specification (OAS) and RESTful API Modeling Language (RAML). We discuss what they were built for and how well they’ve been maintained. We finish on why OAS is the industry standard and the logical spec format for most RESTful API providers — and why it’s set to stay that way.

What Is OAS?

OpenAPI Specification (OAS)

Chances are you’re already familiar with the OpenAPI Specification (OAS). This popular specification language positions itself as a tool to describe APIs — establishing something of a contract between the API provider and consumer — but also offers various automation benefits in documentation and testing.

It’s worth knowing that the OpenAPI Specification (then known as Swagger) once belonged to SmartBear Software. Although the organization still has close ties to the spec, it’s now governed by the OpenAPI Initiative, an open-source community supported by the Linux Foundation.

You can see an example of what an OAS 2.0 document looks like by loading up the Swagger Editor. The spec captures a lot of information about the API in question — covering basic metadata as well as resource methods, parameters, responses and more:

paths:
  /pet:
    post:
      tags:
      - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "addPet"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
      responses:
        "405":
          description: "Invalid input"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"

What Is RAML?

RESTful API Modeling Language (RAML)

RAML, or RESTful API Modeling Language, is a YAML-based API description format released by Mulesoft in late 2013. As a modeling language, the primary goal of RAML is to help you design new APIs — and not just to describe existing APIs.

While RAML was created with REST APIs in mind, it’s flexible enough that it can be used to model other architectural styles, including RPC and even GraphQL.

“Since RAML supports any schema languages, it can virtually support any API type as long as they are based on HTTP.” – Jonathan Stoikovitch, Open Standards Lead at MuleSoft

Now, let’s jump into some sample spec. Like other description standards, a RAML document starts with some essential API metadata:

title: e-BookMobile API
baseUri: https://api.e-bookmobile.com/{version}
version: v1

Subsequently, you can start describing your API’s various resources and subresources, such as the HTTP methods they take and the query parameters you can pass:

/books:
  /{bookTitle}
    get:
      queryParameters:
        author:
        publicationYear:
        rating:
        isbn:
    put:
      queryParameters:
        access_token:

And similarly, for each resource or subresource, you can describe the responses that your API will return for various calls, providing sample payloads:

/books:
  /{bookTitle}:
    get:
      description: Retrieve a specific book title
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "data": {
                    "id": "SbBGk",
                    "title": "Stiff: The Curious Lives of Human Cadavers",
                    "description": null,
                    "datetime": 1341533193,
                    "genre": "science",
                    "author": "Mary Roach",
                    "link": "https://e-bookmobile.com/books/Stiff"
                  },
                  "success": true,
                  "status": 200
                }

Choosing Between RAML vs. OAS

Although RAML focuses on modeling APIs and OAS on describing them, the truth is that either format can be used for either purpose: you can describe an existing API with RAML or model a new one with OAS. So, which format should you choose?

Features

For the most part, RAML and OAS 2.0 share a lot of the same features. You can describe (or model) resources, methods, and query parameters, share example responses, and define security schemes in both formats, just with slightly different structures.

It’s the newer version of OAS — 3.0 — which offers a great deal more functionality, such as additional security definitions, support for callbacks, and hypermedia references, as well as a streamlined file structure. Not to mention, version 3.1 is bringing even more developments:

“I’m really happy that in 3.1 schema definitions will rely on ”true“ JSON Schema without OpenAPI specific elements. And I’m even more happy (if not totally crazy) because we’ll at last be able to override some information, such as the description, coming from a schema referenced with $ref.” – Arnaud Lauret aka The API Handyman

With that said, one characteristic that RAML is still lauded for today is reuse:

“If I had to pick one aspect in which RAML excels, I would say it is the ”re-usability“ aspect. RAML ships with its own type system that helps model data structures using features like inheritance and even multiple inheritance, which helps make schema and API definitions very dry, making them much easier to read (and understand); RAML also has the ”security schemes,“ ”resource types“ and ”traits“ concepts that allow one to model, only once, the most common characteristics of HTTP resources and methods.” – Jonathan Stoikovitch

Activity

When it comes to community, the OpenAPI Specification is more established of the two description formats: the OAS repo has 18,000+ stars on GitHub, to RAML’s 3,700 or so. More community participation makes it easier to share between partners and increases the number of tools available.

Of course, with community comes activity. Unfortunately, this means that RAML hasn’t progressed like OAS has in recent years. RAML is still on version 1.0 (with the last major patch in July 2016), where OAS is now on version 3.0 with new releases in the pipeline.

Interestingly, the most recent developments surrounding RAML actually seek to enable conversion between the two formats:

“We recently deprecated our official Java and JavaScript parsers and launched a new parser called webapi-parser which supports both RAML and OpenAPI/OAS. This is great for the community because it means that any tool that is compatible with OpenAPI can now be leveraged using RAML, and vice versa.” -Jonathan Stoikovitch

It would appear RAML isn’t being used out in the wild nearly as much as those 3,700 GitHub stars would have you believe. Most StackOverflow threads with the RAML tag actually come from users of MuleSoft’s API creation and integration products, like Mule and Anypoint Studio, where RAML is the native API description format.

The takeaway? RAML has always been part of the MuleSoft ecosystem, which may explain its continued usage despite a lack of new development. However, what with MuleSoft now warming to the use of OAS 3.0 in its products, it’s hard to imagine RAML activity increasing much beyond that ecosystem from here on out.

Final Verdict

Within an industry of many standards, RAML and OAS stand out as powerful formats for modeling and/or describing APIs. Although their structure and syntax are similar, there are noticeable differences in feature sets and their communities’ activity. While RAML may be the logical spec to use for some MuleSoft developers or in particular circumstances, the OpenAPI Specification appears to be an industry standard, reflected by its continued development and support across the API community.