¿Qué es RAML y en qué se diferencia de OpenAPI? #

Antes de que OpenAPI se convirtiera en el estándar dominante para describir las API REST, varias especificaciones competían por ser adoptadas. RAML (RESTful API Modeling Language) fue una de las alternativas más extendidas, sobre todo en entornos empresariales. Creado por MuleSoft en 2013 y respaldado por un consorcio que incluía a Salesforce, Cisco y PayPal, RAML ofrecía una sintaxis clara y legible para describir API e introdujo conceptos que influyeron en el ecosistema más amplio de especificaciones de API. Comprender RAML y en qué se diferencia de OpenAPI ayuda a los equipos a evaluar decisiones históricas y a planificar iniciativas de modernización.

¿Qué es RAML? #

RAML es una especificación basada en YAML para describir API RESTful. Se diseñó haciendo hincapié en:

• Legibilidad para las personas: los documentos RAML estaban pensados para que los pudieran leer personas que no son desarrolladoras, en particular analistas de negocio y responsables de producto.
• Reutilización: RAML introdujo resourceTypes y traits como mecanismos de primera clase para reutilizar patrones de API.
• Modelado antes de la implementación: RAML seguía de forma explícita el enfoque design-first y fomentaba el diseño de la API como una actividad de modelado separada de la implementación.

Un documento RAML sencillo tiene este aspecto:

#%RAML 1.0
title: Users API
version: v1
baseUri: https://api.example.com/{version}

/users:
  get:
    description: List all users
    responses:
      200:
        body:
          application/json:
            type: User[]

  post:
    description: Create a new user
    body:
      application/json:
        type: UserInput
    responses:
      201:
        body:
          application/json:
            type: User

types:
  User:
    type: object
    properties:
      id: string
      email: string
      name?: string

  UserInput:
    type: object
    required: [email]
    properties:
      email: string
      name?: string

La cabecera #%RAML 1.0 y la sección types son características propias de RAML sin equivalente directo en la estructura de documento de OpenAPI.

Características principales de RAML #

Tipos de recurso y rasgos #

La característica más distintiva de RAML son sus mecanismos resourceTypes y traits. Un resourceType define una plantilla reutilizable para un recurso HTTP; por ejemplo, un recurso de colección estándar con operaciones GET (listar) y POST (crear). Un trait define un conjunto reutilizable de propiedades que se puede aplicar a operaciones individuales; por ejemplo, un trait pageable que añade los parámetros de consulta page y per_page.

resourceTypes:
  collection:
    get:
      description: List all <<resourcePathName>>
      responses:
        200:
          body:
            application/json:
              type: <<resourcePathName | !singularize>>[]
    post:
      body:
        application/json:
          type: <<resourcePathName | !singularize>>Input
      responses:
        201:
          body:
            application/json:
              type: <<resourcePathName | !singularize>>

traits:
  pageable:
    queryParameters:
      page:
        type: integer
        default: 1
      per_page:
        type: integer
        default: 25

Se pueden aplicar a los recursos con una repetición mínima:

/users:
  type: collection
  get:
    is: [pageable]

OpenAPI no tiene un equivalente directo de resourceTypes y traits. En OpenAPI se logra una reutilización similar mediante $ref en components, los parámetros a nivel de ruta y convenciones de las herramientas, pero la abstracción es menos elegante.

Sistema de tipos de RAML #

RAML 1.0 introdujo su propio sistema de tipos, anterior a la alineación completa de OpenAPI con JSON Schema. Los tipos de RAML admiten herencia (type: User), tipos de unión (type: string | integer) y discriminadores para el polimorfismo, todo ello expresado con sintaxis nativa de RAML en lugar de palabras clave de JSON Schema.

RAML también admitía de forma nativa formatos de datos distintos de JSON: los esquemas XML, CSV y los datos de formulario eran ciudadanos de primera clase en el sistema de tipos, lo que reflejaba su herencia empresarial, en la que las API basadas en XML eran habituales.

En qué se diferencian RAML y OpenAPI #

Organismo rector y comunidad #

OpenAPI está gobernado por la OpenAPI Initiative, un consorcio de la Linux Foundation que incluye a Google, Microsoft, IBM, Salesforce y muchas otras empresas. Este amplio respaldo de la industria aporta a OpenAPI una inversión considerable en herramientas y estabilidad a largo plazo. RAML lo mantiene el RAML Workgroup, impulsado principalmente por MuleSoft (ahora propiedad de Salesforce). El ecosistema de RAML ha recibido bastante menos inversión en los últimos años.

Herramientas y ecosistema #

El ecosistema de herramientas de OpenAPI es mucho mayor que el de RAML. OpenAPI se beneficia de herramientas para todos los lenguajes y frameworks principales: desde generadores de código y de SDK hasta linters, portales de documentación, gateways de API y plataformas de integración con IA. Las herramientas de RAML se concentran sobre todo en la MuleSoft Anypoint Platform y han tenido poco desarrollo fuera de ese ecosistema.

Alineación con JSON Schema #

OpenAPI 3.1 logra una compatibilidad total con JSON Schema 2020-12, por lo que sus esquemas se pueden usar con cualquier validador de JSON Schema que cumpla el estándar. El sistema de tipos de RAML es distinto de JSON Schema, lo que obliga a usar herramientas específicas de RAML para validar esquemas y limita la portabilidad.

Dónde sigue presente RAML #

RAML sigue utilizándose en organizaciones que construyeron sus programas de API sobre la MuleSoft Anypoint Platform. Anypoint Design Center, de MuleSoft, admite RAML de forma nativa, y muchas empresas que usan MuleSoft para la integración tienen grandes bibliotecas de documentos RAML.

Para estas organizaciones, la migración a OpenAPI es posible, pero requiere inversión. Herramientas como oas-raml-converter pueden automatizar buena parte de la conversión, y las propias herramientas de MuleSoft han añadido cada vez más soporte para OpenAPI junto con RAML.

¿Deben los nuevos proyectos de API usar RAML u OpenAPI? #

Para los proyectos de API nuevos, la recomendación clara es OpenAPI:

• Estándar de la industria: OpenAPI lo usan Google, Microsoft, AWS, Stripe, Twilio y prácticamente todas las grandes plataformas de API.
• Amplitud de herramientas: los generadores de código, los linters, las herramientas de documentación, los servidores simulados (mock), los gateways de API y las plataformas de IA admiten OpenAPI de forma nativa.
• Preparado para el futuro: OpenAPI 4.0 (Moonwalk) está en desarrollo activo; la hoja de ruta de RAML no está clara.
• Familiaridad de los desarrolladores: muchos más desarrolladores tienen experiencia con OpenAPI que con RAML.

El único motivo para elegir RAML hoy es que el equipo ya esté muy comprometido con la MuleSoft Anypoint Platform y que el coste de migrar a OpenAPI no se pueda justificar por ahora.

Conclusión #

RAML fue un lenguaje de especificación de API innovador e influyente que fue pionero en conceptos como los tipos de recurso, los rasgos (traits) y el modelado de API como disciplina de diseño. En su mejor momento compitió seriamente con Swagger/OpenAPI. Hoy, sin embargo, OpenAPI se ha impuesto en el mercado: cuenta con un respaldo más amplio de la industria, un ecosistema de herramientas mucho mayor, una alineación total con JSON Schema y un desarrollo activo hacia OpenAPI 4.0. Para los equipos que se encuentran con RAML en sistemas heredados, el camino a seguir es una migración planificada a OpenAPI, idealmente con herramientas de conversión automática y un enfoque por fases que conserve los contratos de API existentes y, al mismo tiempo, dé acceso al ecosistema moderno de OpenAPI.

Última actualización: 30 de abril de 2026.