Streaming JSON en OpenAPI 3.2

Los datos en streaming permiten que los servidores de APIs envíen y reciban información en tiempo real o por fragmentos, sin esperar a que toda la respuesta esté lista. Igual que los navegadores procesan HTML, imágenes y multimedia a medida que llegan, ahora también puede hacerse con APIs que trabajan con JSON. Esto acelera respuestas con grandes volúmenes de datos y habilita el envío de eventos del servidor al cliente sin recurrir a polling ni añadir la complejidad de Webhooks o WebSockets, porque el cliente consume pequeños fragmentos de información de forma continua.

El streaming de JSON cobra cada vez más valor a medida que crecen las expectativas en big data, data science e inteligencia artificial. JSON por sí mismo no es fácilmente streamable, pero han surgido estándares y convenciones que lo convierten en un formato apto para transmisión continua, y OpenAPI 3.2 introduce palabras clave para describir estos flujos de datos.

Hacer streaming de JSON puede ser complicado porque el formato no fue pensado para eso. Una aproximación ingenua acumula objetos sin cerrar estructuras, lo que rompe la mayoría de herramientas. En su lugar, formatos como JSON Lines o NDJSON envían un objeto JSON por línea, de modo que cada línea es un JSON válido y se puede procesar con herramientas estándar iterando línea a línea. Otros formatos como JSON Text Sequences o GeoJSON Text Sequence siguen ideas muy similares.

Con OpenAPI 3.0 y 3.1 ya era posible transmitir datos binarios, pero resultaba difícil modelar formatos de streaming JSON porque no había una manera estándar de definir el esquema de cada evento individual del flujo. Muchas personas intentaban describir el stream como si fuera un array, pero un flujo no es un array único sino una secuencia de múltiples objetos, y ese enfoque confunde a las herramientas.

OpenAPI 3.2 resuelve el problema con dos nuevas palabras clave orientadas al streaming: itemSchema para definir la estructura de cada elemento del flujo y itemEncoding para describir cómo se codifica cada elemento, ya sea texto, JSON o binario.

ItemSchema aplica una definición de esquema por elemento, no sobre la respuesta completa. Imagina un endpoint que transmite billetes de tren en tiempo real, cada elemento contendría campos como tren, origen, destino y precio. Declarar itemSchema deja claro para el tooling que la respuesta es un stream y, junto con el tipo de contenido adecuado, indica cómo debe parsearse y mostrarse. Para flujos puramente JSON, itemSchema suele ser suficiente; en formatos más complejos puede ser necesario añadir información de codificación.

ItemEncoding permite especificar la codificación de cada elemento usando el mismo objeto que encoding, pero solo es aplicable a respuestas multipart. Es útil cuando en un mismo flujo se mezclan JSON y binarios como imágenes, aunque para streaming JSON convencional rara vez hace falta. En la mayoría de APIs orientadas a datos y eventos, centrarse en itemSchema será suficiente.

Entre los formatos populares se encuentran JSON Lines, NDJSON, JSON Text Sequences y Server Sent Events. Aunque difieren en ciertos detalles, todos persiguen permitir el envío de datos de forma continua en lugar de una respuesta única y completa.

Con JSON Lines y NDJSON, la práctica es casi idéntica y se siente como trabajar con JSON tradicional, pero con un encabezado distinto y el uso de itemSchema. JSON Lines suele anunciarse con el tipo de contenido application/jsonl y NDJSON con application/x-ndjson. En ambos casos, cada elemento es un objeto JSON seguido por un salto de línea. En documentación es habitual mostrar ejemplos como cadenas multilínea, ya que esa concatenación de objetos separados por líneas no se representa bien como un único JSON o YAML convencional.

Para implementar el envío, basta con serializar cada objeto con JSON y escribir un salto de línea al final de cada uno, manteniendo la conexión abierta mientras el servidor tenga elementos que transmitir. El cliente puede ir leyendo línea a línea y procesando en cuanto llegan, sin esperar a que termine el stream.

JSON Text Sequences añade una particularidad: cada elemento comienza con el carácter de control Record Separator 0x1E, que no es visible en la mayoría de editores pero marca el inicio de cada objeto en el flujo. En estos casos, apoyarse en librerías específicas para generar y consumir la secuencia simplifica la gestión de estos caracteres de control.

Además de transmitir datos, también es común enviar eventos. Server Sent Events es un estándar para actualizaciones en tiempo real desde el servidor al cliente sobre HTTP con el tipo de contenido text/event-stream. Con OpenAPI 3.2 se puede describir un stream SSE usando itemSchema para definir la estructura de campos como event, data y retry. Incluso se puede aplicar polimorfismo con oneOf para tipar cada evento y detallar el formato de sus datos, por ejemplo datos numéricos, cadenas multilínea o JSON con un esquema concreto.

Muchos flujos incluyen eventos centinela, que anuncian el cierre del stream o estados especiales. En OpenAPI esto se resuelve con composición de esquemas estándar como oneOf, anyOf o allOf, combinando el esquema de datos habitual con una variante que represente el marcador de fin o los casos especiales, por ejemplo un evento con data igual a DONE.

Para sacar partido a todo esto en entornos de producción es clave alinear la definición OpenAPI 3.2 con la implementación real de servidor y cliente, validar cada elemento según itemSchema, elegir el tipo de contenido correcto para el formato de streaming y cubrir los casos límite como reconexiones, reintentos, control de backpressure y eventos centinela.

En Q2BSTUDIO impulsamos el diseño e implementación de APIs modernas con OpenAPI 3.2, integrando patrones de streaming para casos de big data, analítica avanzada, agentes IA y productos basados en ia para empresas. Nuestro equipo desarrolla aplicaciones a medida y software a medida con foco en rendimiento, observabilidad y seguridad de extremo a extremo.

Si buscas un partner para diseñar y construir una plataforma preparada para datos en tiempo real, descubre cómo abordamos proyectos de aplicaciones a medida en nuestra página de servicio de desarrollo de software multiplataforma, o conoce cómo aplicamos inteligencia artificial práctica en nuestra unidad de inteligencia artificial con casos de uso de copilotos, automatización con agentes IA y MLOps.

Complementamos estas soluciones con ciberseguridad avanzada y pentesting, servicios cloud aws y azure, y servicios inteligencia de negocio con power bi para orquestar pipelines, gobernanza y visualización de datos. También abordamos automatización de procesos extremo a extremo, desde la captura y validación de datos hasta la publicación de eventos y dashboards operativos, siempre con una arquitectura sostenible y escalable.

En resumen, OpenAPI 3.2 aporta la pieza que faltaba para describir de forma nativa streams de JSON mediante itemSchema e itemEncoding, habilitando especificaciones más precisas, documentación clara y mejores herramientas de validación y pruebas. Es el momento ideal para evolucionar tus APIs hacia modelos orientados a eventos y streaming continuo, reduciendo latencia, mejorando experiencia de usuario y habilitando nuevos escenarios de inteligencia artificial y analítica en tiempo real.