¿Qué es la iniciativa OpenAPI Moonwalk y qué cambios introduce OpenAPI 4.0?

¿Qué es la iniciativa OpenAPI Moonwalk y qué cambios introduce OpenAPI 4.0? #

OpenAPI Moonwalk es el nombre en clave de la próxima versión principal de la especificación OpenAPI: OpenAPI 4.0. Lo desarrolla un grupo de interés especial (SIG, por sus siglas en inglés) de la OpenAPI Initiative (OAI), de forma abierta en GitHub, y supone un replanteamiento fundamental de cómo se describen las API HTTP. En lugar de ser una actualización incremental como el paso de la versión 3.0 a la 3.1, Moonwalk es un rediseño desde cero que pretende resolver las limitaciones acumuladas de la especificación actual y, al mismo tiempo, conservar lo que hace valioso a OpenAPI: un contrato legible por personas y por máquinas para las API RESTful.

¿Por qué una nueva versión principal? #

OpenAPI 3.x ha tenido un éxito enorme, pero años de uso en el mundo real han puesto de manifiesto limitaciones estructurales:

  • El modelo de elemento de ruta (Path Item) es rígido. Las rutas son la unidad organizativa principal, pero las API modernas no siempre se ajustan bien a las rutas de URL, sobre todo las que tienen jerarquías de recursos complejas, patrones de parámetros superpuestos o aspectos comunes a nivel de ruta.
  • La reutilización es engorrosa. El mecanismo $ref y el objeto components admiten la reutilización, pero componer operaciones a partir de fragmentos compartidos resulta incómodo. Los equipos acaban duplicando definiciones o creando soluciones alternativas complejas con herramientas.
  • No hay una descripción nativa de flujos de trabajo ni secuencias. OpenAPI describe las operaciones individuales de forma aislada. La especificación Arazzo se añadió como complemento para cubrir esta carencia, pero sigue siendo externa a la especificación principal.
  • El tratamiento de los esquemas ha mejorado, pero el modelo estructural no. OpenAPI 3.1 logró una alineación total con JSON Schema para los esquemas, pero el modelo de operaciones en sí (rutas, parámetros, cuerpos de solicitud, respuestas) no se ha revisado con el mismo rigor.
  • Proliferación de extensiones. Las carencias de la especificación se han ido parcheando con extensiones x-, lo que ha dado lugar a un ecosistema fragmentado en el que cada herramienta entiende dialectos de extensión distintos.

Moonwalk está diseñado para resolver estos problemas desde los primeros principios, en lugar de mediante más extensiones incrementales.

Principios de diseño fundamentales de Moonwalk #

El grupo de trabajo de Moonwalk ha formulado varios principios rectores para OpenAPI 4.0:

Simplicidad y facilidad de aprendizaje #

Una de las críticas más habituales a OpenAPI 3.x es su pronunciada curva de aprendizaje. El objeto Path Item, el objeto Operation, el objeto Parameter, el objeto Request Body y el objeto Response forman una jerarquía profundamente anidada que sorprende a quienes se inician. Moonwalk pretende aplanar y simplificar este modelo siempre que sea posible.

Componibilidad #

Moonwalk introduce un modelo más componible en el que las operaciones, los parámetros y los patrones de respuesta pueden definirse una sola vez y ensamblarse en descripciones de API sin duplicación. Esta componibilidad está pensada para funcionar de forma nativa con la especificación, en lugar de depender de convenciones de las herramientas.

Desacoplar la estructura de HTTP #

Históricamente, OpenAPI ha estado estrechamente ligado a la estructura de rutas de HTTP. Moonwalk explora un modelo en el que la estructura lógica de la API se describe con independencia de cómo se asigna a HTTP, lo que permite usar una misma descripción de API con distintos enlaces de transporte o convenciones de URL.

Mejor soporte para patrones de API modernos #

Moonwalk se está diseñando teniendo en cuenta de forma explícita patrones que son habituales en las API modernas, pero difíciles de describir en 3.x:

  • Webhooks (abordados en 3.1, pero con más mejoras previstas)
  • Operaciones por lotes
  • Operaciones de larga duración (patrones de tareas asíncronas)
  • Eventos enviados por el servidor (SSE)
  • API multiprotocolo (la misma API lógica sobre REST y WebSockets)

Cambios estructurales clave en estudio #

El modelo request #

Moonwalk está experimentando con sustituir el mapa de nivel superior paths por un modelo de descripción de solicitudes más flexible. En lugar de organizar las operaciones bajo plantillas de ruta de URL, las operaciones podrían definirse de forma más abstracta y vincularse a rutas HTTP por separado. Esto permitiría exponer la misma operación lógica en varias rutas o con distintas convenciones de URL sin duplicación.

Modelo de parámetros unificado #

En OpenAPI 3.x, los parámetros pueden definirse a nivel del elemento de ruta o a nivel de la operación, y a veces interactúan de formas confusas. Moonwalk pretende unificar el modelo de parámetros para que la herencia, la sobrescritura y el uso compartido de parámetros funcionen de forma predecible.

Reutilización nativa sin la complejidad de $ref #

Aunque $ref seguirá siendo compatible (forma parte de JSON Schema), Moonwalk está explorando construcciones de reutilización de más alto nivel que no exijan un conocimiento profundo de la semántica de JSON Reference y JSON Pointer para usarlas con eficacia.

Modelo de extensibilidad mejorado #

En lugar de extensiones x- sin estructura, Moonwalk podría introducir un sistema de extensiones tipadas en el que cada extensión declare su esquema, de modo que los validadores y las herramientas puedan comprobar su corrección en lugar de ignorarlas en silencio.

Relación con las especificaciones existentes #

Moonwalk está diseñado para coexistir con OpenAPI 3.x y, con el tiempo, sustituirlo. Consideraciones clave de compatibilidad:

  • Los documentos de OpenAPI 3.x seguirán siendo válidos: las herramientas y los documentos existentes no dejarán de funcionar. Moonwalk se dirige a las nuevas descripciones de API a partir de ahora.
  • Se mantiene la alineación con JSON Schema: el vocabulario completo de JSON Schema 2020-12 adoptado en OpenAPI 3.1 pasa a Moonwalk.
  • Integración con Arazzo: la especificación Arazzo para describir flujos de trabajo podría integrarse más estrechamente con el modelo de operaciones de Moonwalk o armonizarse con él.
  • Especificación Overlay: se espera que la especificación OpenAPI Overlay siga siendo relevante como mecanismo de personalización para los documentos de Moonwalk.

Estado actual y cronograma #

En 2026, Moonwalk se encuentra en desarrollo activo como un SIG que trabaja mediante debates y registros de decisiones de arquitectura (ADR), y no mediante un borrador formal de especificación: el grupo ha indicado que comenzará a redactar un documento formal cuando existan suficientes ADR que formen un conjunto coherente. No hay una fecha de finalización prevista para la versión 4.0.

Es importante señalar que Moonwalk no mira únicamente al futuro: varias ideas surgidas de los debates del SIG ya se han incorporado a la línea de versiones 3.x, que es compatible con versiones anteriores. El ejemplo más visible es OpenAPI 3.2.0, publicada en septiembre de 2025, que incluyó funcionalidades influidas por Moonwalk, como el objeto Tag mejorado y anidable y el campo $self de identidad del documento, mucho antes de cualquier versión 4.0. Esto significa que el impacto de Moonwalk ya se está notando en la especificación que usan los equipos hoy, y no solo en una futura versión principal.

Se anima a la comunidad a participar en la definición de la especificación de las siguientes formas:

¿Qué deberían hacer ahora los equipos de API? #

Para los equipos que diseñan API hoy, la guía práctica es la siguiente:

  1. Usa OpenAPI 3.2 para los nuevos diseños de API: es la última versión actual, totalmente compatible con las versiones 3.0.x/3.1.x, e incluye ya varias ideas que se originaron en los debates de Moonwalk.
  2. Sigue el repositorio sig-moonwalk para entender la dirección que se está tomando y empezar a alinear las prácticas internas con los principios de diseño de Moonwalk.
  3. Invierte en un buen diseño de esquemas con JSON Schema 2020-12, que pasa sin cambios de la versión 3.1/3.2 a Moonwalk.
  4. Evita depender en exceso de extensiones x- específicas de una herramienta siempre que sea posible, ya que Moonwalk podría introducir sustitutos estándar.
  5. Participa en la comunidad: el diseño de Moonwalk se moldea con los comentarios de profesionales de API en entornos reales.

Conclusión #

OpenAPI Moonwalk representa la evolución más ambiciosa de la especificación OpenAPI desde sus inicios. Al replantear el modelo de operaciones principal, mejorar la componibilidad y la reutilización, y abordar los patrones de API modernos que la especificación actual maneja con dificultad, Moonwalk aspira a mantener a OpenAPI como el estándar definitivo para describir API HTTP durante la próxima década. Además, ya está influyendo en la especificación de forma incremental, como se aprecia en las incorporaciones de etiquetas y de $self en OpenAPI 3.2. Los equipos que han invertido en OpenAPI deberían seguir de cerca el repositorio sig-moonwalk a medida que la especificación madure hacia una versión estable.

Última actualización: 12 de agosto de 2026.

Este sitio web no está afiliado a la OpenAPI Initiative.