¿Cuáles son las diferencias clave entre OpenAPI 3.0 y OpenAPI 3.1? #

La OpenAPI Specification ha evolucionado de forma significativa a lo largo de los años, y una de sus actualizaciones más importantes fue la transición de la versión 3.0 a la versión 3.1. Lanzada en febrero de 2021 por la OpenAPI Initiative, OpenAPI 3.1 introdujo una serie de mejoras que estrecharon la relación entre OpenAPI y JSON Schema, resolvieron inconsistencias de larga data y añadieron nuevas capacidades para describir API modernas. Para los equipos que han invertido en documentos de OpenAPI 3.0, comprender estas diferencias es esencial antes de planificar una migración.

Alineación total con JSON Schema #

El cambio más significativo de OpenAPI 3.1 es su alineación total con la especificación de JSON Schema, en concreto con JSON Schema Draft 2020-12. En OpenAPI 3.0, el objeto de esquema (Schema Object) se describía como un subconjunto extendido de JSON Schema Draft 4 con algunas modificaciones que, en la práctica, lo hacían incompatible con los validadores estándar de JSON Schema. Esto generaba fricciones para los desarrolladores que intentaban reutilizar esquemas entre distintos ecosistemas de herramientas.

OpenAPI 3.1 resuelve este problema al adoptar el vocabulario de JSON Schema por completo y sin modificaciones. Esto significa que:

• Las palabras clave estándar de JSON Schema como $schema, $id, $dynamicRef, $dynamicAnchor, unevaluatedProperties y unevaluatedItems ahora son válidas en los objetos de esquema de OpenAPI.
• Los esquemas escritos para OpenAPI 3.1 pueden validarse con cualquier validador conforme a JSON Schema Draft 2020-12, como AJV o jsonschema.
• Las herramientas y bibliotecas que ya son compatibles con JSON Schema ahora pueden trabajar con los esquemas de OpenAPI sin capas de traducción.

Para los equipos que construyen grandes plataformas de API, esta alineación simplifica drásticamente la reutilización de esquemas y la integración de herramientas.

Eliminación de las modificaciones de esquema específicas de OpenAPI #

OpenAPI 3.0 introdujo varias modificaciones en palabras clave de JSON Schema que se apartaban del estándar. Dos ejemplos destacados:

nullable reemplazado por arreglos (arrays) type de JSON Schema #

En OpenAPI 3.0, para que un campo admitiera valores nulos se requería la palabra clave propietaria nullable: true junto con el tipo. Por ejemplo:

schema:
  type: string
  nullable: true

En OpenAPI 3.1 se utiliza el enfoque estándar de JSON Schema: type puede ser un arreglo de tipos:

schema:
  type: [string, "null"]

Este es un cambio incompatible que obliga a actualizar los esquemas durante la migración, pero se ajusta correctamente a la forma en que JSON Schema maneja los valores nulos opcionales.

Cambios en exclusiveMinimum y exclusiveMaximum #

En OpenAPI 3.0, exclusiveMinimum y exclusiveMaximum eran valores booleanos que modificaban el comportamiento de minimum y maximum. En JSON Schema Draft 2020-12 (y, por tanto, en OpenAPI 3.1), son números que expresan directamente el límite exclusivo:

# OpenAPI 3.0
minimum: 0
exclusiveMinimum: true

# OpenAPI 3.1
exclusiveMinimum: 0

Compatibilidad con webhooks #

OpenAPI 3.0 carecía de una forma estándar de describir webhooks: callbacks HTTP asíncronos que un servidor envía a una URL registrada por el cliente. Aunque existían los callbacks, estos modelaban un patrón distinto (llamadas salientes desencadenadas por una solicitud).

OpenAPI 3.1 introduce un objeto webhooks dedicado en el nivel superior, que permite a los proveedores de API describir formalmente la forma de los eventos que su servicio enviará mediante POST a los endpoints de los suscriptores:

webhooks:
  newOrder:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        "200":
          description: Return a 200 to signal receipt

Esto es especialmente relevante para las integraciones orientadas a eventos que se encuentran en plataformas como Stripe, GitHub y Shopify.

Comportamiento mejorado de $ref #

En OpenAPI 3.0, el objeto $ref no admitía propiedades hermanas: cualquier palabra clave junto a $ref se ignoraba sin avisar. OpenAPI 3.1 elimina esta restricción, siguiendo la especificación de JSON Schema, lo que significa que ahora puedes hacer lo siguiente:

schema:
  $ref: '#/components/schemas/BaseModel'
  description: An override description for this specific usage

Esto permite una documentación más precisa sin duplicar definiciones de esquema completas.

El tipo de componente pathItems #

OpenAPI 3.1 añade pathItems como un nuevo tipo de componente reutilizable, que permite definir una sola vez en components los objetos de elemento de ruta (path item objects, que describen un conjunto de operaciones para una ruta determinada) y referenciarlos mediante $ref donde sea necesario. Esto reduce la repetición en API con patrones de endpoints similares en varias rutas.

La palabra clave const de los esquemas #

OpenAPI 3.1 ahora admite la palabra clave const de JSON Schema, que restringe un campo a un único valor exacto:

schema:
  type: string
  const: "active"

Antes, esto se aproximaba con un enum de un solo valor en OpenAPI 3.0, pero const es semánticamente más preciso y cuenta con mejor soporte en las herramientas que reconocen esquemas.

Campo summary en los elementos de ruta #

OpenAPI 3.1 añade un campo opcional summary a los objetos de elemento de ruta (Path Item Objects), que complementa el campo description existente. Es una mejora de documentación menor pero útil, ya que permite resúmenes concisos de una sola línea que aparecen de forma destacada en herramientas de documentación generada como Redoc y Stoplight Elements.

Mejoras en la licencia y en la información #

El objeto info incorpora dos nuevos campos opcionales en OpenAPI 3.1:

• summary — una descripción breve de la API, en una sola oración, útil en contextos donde una description completa resulta demasiado extensa.
• license.identifier — un identificador de licencia SPDX (por ejemplo, MIT, Apache-2.0) como alternativa a proporcionar una url completa.

Resumen de los cambios incompatibles #

Migrar de OpenAPI 3.0 a 3.1 requiere abordar un puñado de cambios incompatibles:

Adopción en el ecosistema de herramientas #

A 2025, la mayoría de las principales herramientas de OpenAPI han añadido compatibilidad con OpenAPI 3.1, aunque la cobertura varía. Entre las herramientas que ya lo han adoptado se encuentran:

• Redocly CLI — permite agrupar (bundling), analizar con linter y renderizar documentos 3.1.
• Stoplight Studio — editor visual con compatibilidad total con 3.1.
• Swagger UI — el soporte de renderizado para 3.1 se añadió en la versión 5.x.
• openapi-generator — el soporte de generación de código para 3.1 está en curso.
• Spectral — compatibilidad de conjuntos de reglas de linter para 3.1.

Los equipos deben evaluar su cadena de herramientas antes de actualizar para asegurar la plena compatibilidad.

¿Conviene actualizar? #

Para proyectos nuevos, OpenAPI 3.1 (o 3.2, la última versión actual) es el punto de partida recomendado frente a 3.0. La alineación de 3.1 con JSON Schema mejora drásticamente la interoperabilidad del ecosistema y hace que los esquemas sean portables entre las herramientas de validación, documentación y generación de código, y esa alineación se mantiene sin cambios en 3.2.

Para los proyectos existentes de OpenAPI 3.0, la actualización implica cambios en los esquemas (nullable, límites exclusivos), pero los beneficios —en especial la compatibilidad total con JSON Schema y el soporte de webhooks— justifican la inversión. Herramientas como openapi-format y Redocly CLI pueden ayudar con la migración automatizada.

La entrada oficial del blog sobre el lanzamiento de OpenAPI 3.1.0 y la especificación completa son las referencias autorizadas para los equipos que planifican una actualización.

Conclusión #

OpenAPI 3.1 es un avance significativo y, en su mayor parte, compatible con versiones anteriores respecto a 3.0. Al adoptar por completo JSON Schema, añadir compatibilidad con webhooks y resolver inconsistencias de larga data, posiciona a la OpenAPI Specification como un estándar más robusto e interoperable para la descripción de API. Comprender las diferencias clave es el primer paso para tomar una decisión de migración informada en cualquier equipo de API.

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