RAML vs OAS

Two specification languages, one platform

Anypoint Platform supports both RAML and OpenAPI Specification (OAS, formerly Swagger). API Designer edits both, Exchange stores both, and API Manager can apply policies to either. The choice is about team fit, not capability.

RAML strengths

RAML was built for reuse. Its fragments, resource types, and traits make factoring out common patterns natural.

#%RAML 1.0
title: Orders API
version: v1
baseUri: https://api.example.com/{version}
/orders:
  get:
    responses:
      200:
        body:
          application/json:
            type: Order[]

OAS strengths

OAS has the broader ecosystem — more third-party tooling, wider industry familiarity, and it is the direction much of the market has moved.

openapi: 3.0.0
info:
  title: Orders API
  version: v1
paths:
  /orders:
    get:
      responses:
        "200":
          description: A list of orders

How to guide the choice

• If the customer already standardizes on OpenAPI elsewhere, meet them there.
• If deep reuse via fragments is the priority, RAML has a slight edge.
• Either way, pick one per API program for consistency and govern it.