Las herramientas de API estuvieron cerca de un acuerdo doloroso: OpenAPI usaba objetos de esquema similares a JSON, pero no eran JSON Schema en sentido pleno. Los validadores, generadores de código y herramientas de documentación tenían que aprender diferencias sutiles, de modo que un mismo contrato de API podía significar cosas distintas en distintas pilas tecnológicas.
El movimiento elegante no fue crear otro lenguaje exclusivo para API. JSON Schema hizo que el propio esquema fuera un tipo de medio JSON, con vocabularios y metaesquemas que declaran qué palabras clave y comportamientos están en juego. OpenAPI 3.1 pudo entonces decir: use JSON Schema draft 2020-12, no un imitador.
El resultado fue un estándar que ganó al convertirse en la gramática subyacente de otros estándares. OpenAPI calificó su versión 3.1 como 100% compatible con el último borrador de JSON Schema, mientras que JSON Schema obtuvo un modelo de extensión estable para validación, generación de código, interfaz de usuario y documentación.
Convertir los esquemas en vocabularios extensibles
El esquema siguió siendo JSON corriente, de modo que los desarrolladores podían leerlo, compararlo y generarlo con herramientas existentes.
Los vocabularios dieron nombres y límites a las extensiones en lugar de hacer que cada plataforma inventara palabras clave privadas.
La adopción de OpenAPI llevó JSON Schema a los flujos de documentación de API, validación y generación de código a la vez.
El borrador 2020-12 dio a los implementadores un objetivo estable, incluidos dialectos y metaesquemas.
Un formato se difunde cuando las extensiones son de primera clase y comprobables, no cuando están ocultas en prosa o convenciones de proveedores.
OpenAPI 3.1 se publicó el 18 de febrero de 2021 con compatibilidad total con JSON Schema draft 2020-12. Eso convirtió a JSON Schema en la capa de contrato compartida para un gran ecosistema de herramientas de API, en lugar de ser solo un formato de validador independiente.
CONSULTA LAS PRUEBAS
Las fuentes
- JSON Schema: A Media Type for Describing JSON Documents JSON Schema · json-schema.org
- OpenAPI Specification 3.1.0 Released OpenAPI Initiative · openapis.org ·