¿Qué es la especificación Arazzo y cómo se relaciona con OpenAPI?

¿Qué es la especificación Arazzo y cómo se relaciona con OpenAPI? #

Las API modernas rara vez se usan de forma aislada. Las integraciones del mundo real requieren encadenar varias llamadas a la API, pasar datos de una a otra y tomar decisiones en función de resultados intermedios. La especificación Arazzo, publicada por la OpenAPI Initiative en 2024, se creó precisamente para cubrir esta necesidad. Define un formato estándar y legible por máquinas para describir flujos de trabajo (workflow) de API de varios pasos: secuencias de llamadas a la API que, en conjunto, permiten lograr un resultado de negocio significativo.

El problema que resuelve Arazzo #

OpenAPI destaca al describir operaciones individuales de una API: a qué endpoint llamar, qué parámetros proporcionar y qué respuesta esperar. Sin embargo, no incluye de forma nativa el concepto de flujo de trabajo: el conjunto ordenado de operaciones necesarias para completar un proceso de negocio.

Piensa en un flujo habitual de comercio electrónico:

  1. Autenticarse: POST a /auth/token para obtener un token de acceso.
  2. Buscar un producto: GET /products?q=shoes utilizando el token.
  3. Añadir al carrito: POST /cart/items con el ID del producto seleccionado en el paso 2.
  4. Realizar el pedido: POST /orders con el ID del carrito obtenido en el paso 3.

Cada paso depende del resultado del anterior. Documentar este flujo exige documentación en prosa, diagramas o scripts personalizados, y ninguno de ellos es legible por máquinas ni interoperable. Arazzo cambia esto.

Qué aporta Arazzo al ecosistema OpenAPI #

Arazzo no sustituye a OpenAPI. Es una especificación complementaria que se sitúa sobre uno o varios documentos OpenAPI y describe cómo deben secuenciarse y combinarse sus operaciones. Un documento Arazzo hace referencia a documentos OpenAPI de origen y define flujos de trabajo que orquestan las llamadas a esas operaciones.

En conjunto, OpenAPI y Arazzo cubren distintas capas de la descripción de una API:

CapaEstándarDescribe
Operación individualOpenAPIEndpoint, parámetros, esquema de solicitud y respuesta
Flujo de trabajo de negocioArazzoSecuencia de operaciones, paso de datos, condiciones

Conceptos principales #

Campo de versión arazzo #

Al igual que OpenAPI, cada documento Arazzo declara su versión:

arazzo: 1.0.0

Objeto info #

Proporciona metadatos sobre el documento de flujos de trabajo:

info:
  title: E-Commerce Purchase Workflow
  version: 1.0.0
  description: Describes the sequence of steps to complete a product purchase.

sourceDescriptions #

Declara los documentos OpenAPI (u otros documentos Arazzo) que proporcionan las operaciones utilizadas en este flujo de trabajo:

sourceDescriptions:
  - name: ecommerce-api
    url: ./openapi.yaml
    type: openapi

workflows #

El núcleo de un documento Arazzo. Cada flujo de trabajo tiene un id, un summary, inputs opcionales (definidos como un esquema JSON Schema) y una lista de steps:

workflows:
  - workflowId: purchase-product
    summary: Complete a product purchase from search to order confirmation
    inputs:
      type: object
      properties:
        searchQuery:
          type: string
        userId:
          type: string
    steps:
      - stepId: search-products
        operationId: ecommerce-api.searchProducts
        parameters:
          - name: q
            in: query
            value: $inputs.searchQuery
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          firstProductId: $response.body#/products/0/id

      - stepId: add-to-cart
        operationId: ecommerce-api.addCartItem
        requestBody:
          payload:
            productId: $steps.search-products.outputs.firstProductId
            quantity: 1
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          cartId: $response.body#/cartId

Pasos y referencias a operationId #

Cada paso hace referencia a una operación de un documento OpenAPI de origen mediante el formato {sourceDescription.name}.{operationId}. Este acoplamiento estrecho con el campo operationId de OpenAPI subraya por qué asignar ID de operación únicos y descriptivos en los documentos OpenAPI es una buena práctica.

successCriteria #

Cada paso puede definir criterios de éxito: condiciones que deben cumplirse para que el paso se considere correcto antes de continuar. Estos criterios utilizan un lenguaje de expresiones sencillo que puede hacer referencia al código de estado HTTP, a los encabezados de la respuesta y al cuerpo de la respuesta:

successCriteria:
  - condition: $statusCode == 200
  - condition: $response.body#/status == 'active'

outputs #

Los pasos pueden declarar outputs: valores con nombre extraídos de la respuesta que pueden ser referenciados por pasos posteriores. Así es como fluyen los datos entre pasos, lo que elimina la necesidad de scripts externos:

outputs:
  userId: $response.body#/id
  authToken: $response.header.Authorization

onFailure y onSuccess #

Arazzo admite ramificaciones condicionales en función del resultado de los pasos. Los campos onFailure y onSuccess definen qué hacer a continuación: pasar a un paso concreto, finalizar el flujo de trabajo o reintentar el paso actual:

onFailure:
  - name: handle-auth-failure
    type: goto
    stepId: refresh-token

Expresiones en tiempo de ejecución #

Arazzo utiliza un lenguaje conciso de expresiones en tiempo de ejecución para hacer referencia a valores durante la ejecución:

  • $inputs.fieldName: entrada a nivel de flujo de trabajo
  • $steps.stepId.outputs.outputName: salida de un paso anterior
  • $response.body#/jsonPointer: valor extraído del cuerpo de la respuesta del paso actual mediante JSON Pointer (RFC 6901)
  • $response.header.HeaderName: valor de un encabezado de la respuesta
  • $statusCode: código de estado HTTP de la respuesta del paso actual

En qué se diferencia Arazzo de AsyncAPI y BPMN #

Conviene distinguir Arazzo de otros estándares relacionados:

  • AsyncAPI: describe API asíncronas y basadas en eventos (colas de mensajes, WebSockets, Kafka). Arazzo se centra en los flujos de trabajo de API HTTP síncronas.
  • BPMN (Business Process Model and Notation): un estándar pesado para modelar procesos de negocio, utilizado a menudo con motores de flujos de trabajo empresariales. Arazzo es ligero, está centrado en las API y es cómodo para los desarrolladores.
  • Postman Collections: un formato específico de una herramienta para agrupar solicitudes de API. Arazzo es independiente de cualquier herramienta y tiene rango de especificación.

Herramientas y adopción #

Al tratarse de una publicación de 2024, el ecosistema de herramientas de Arazzo aún está en desarrollo, pero ya se observan las primeras adopciones:

  • Redocly: una de las primeras plataformas comerciales de API en anunciar compatibilidad con Arazzo, que la integra en sus herramientas de flujos de trabajo y documentación.
  • Speakeasy: admite Arazzo para generar ejemplos de uso de SDK y pruebas de integración de extremo a extremo.
  • Vacuum: un linter de OpenAPI que ha empezado a incorporar la validación de documentos Arazzo.
  • Implementaciones de la comunidad: el repositorio de GitHub de la OAI recopila implementaciones de referencia y herramientas compatibles.

Por qué Arazzo es importante para los equipos que siguen un enfoque API-first #

Para los equipos que practican el desarrollo API-first, Arazzo completa la capa de descripción:

  • Documentación: los flujos de trabajo pueden mostrarse como guías paso a paso en los portales de documentación, lo que hace comprensibles los escenarios de integración complejos.
  • Pruebas: los flujos de trabajo legibles por máquinas pueden impulsar pruebas de contrato que validen automáticamente escenarios de integración de varios pasos.
  • Generación de SDK: herramientas como Speakeasy pueden generar métodos de SDK de más alto nivel que encapsulan flujos de trabajo habituales, lo que mejora la experiencia del desarrollador.
  • Agentes de IA: los flujos de trabajo de Arazzo pueden guiar a los agentes de IA a través de interacciones de varios pasos con las API sin necesidad de código de orquestación a medida.

Conclusión #

La especificación Arazzo cubre un vacío crítico en el ecosistema OpenAPI al ofrecer un formato estándar y legible por máquinas para describir flujos de trabajo de API de varios pasos. Mientras que OpenAPI documenta qué hace cada operación de la API, Arazzo documenta cómo se secuencian esas operaciones para lograr objetivos de negocio reales. Para los equipos que crean integraciones de API complejas, exponen las API a agentes de IA, generan SDK o automatizan pruebas de extremo a extremo, Arazzo representa la siguiente evolución del panorama de la descripción de API.

Versiones #

Arazzo alcanzó su primera versión estable, la 1.0.0, en mayo de 2024, seguida de un parche, la 1.0.1, en enero de 2025. La versión actual es la 1.1.0, publicada el 17 de mayo de 2026, que añadió un campo $self de autoidentificación para los documentos (reflejo de la misma incorporación en OpenAPI 3.2), una ubicación de parámetro querystring equivalente a la añadida en OpenAPI 3.2, y reglas aclaradas para la coordinación de pasos asíncronos y la resolución de referencias.

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

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