JSON Schema para contratos de API fiables
Un proceso de creación de esquemas que convierte datos válidos y erróneos en documentación ejecutable, en lugar de depender de un único ejemplo ideal.
La sintaxis JSON solo demuestra que el documento se puede analizar. Un contrato de API útil debe definir las estructuras y los valores que sus consumidores pueden esperar con seguridad.
Modela explícitamente la ausencia y los valores nulos
Un campo obligatorio, uno opcional y uno que admite null representan estados diferentes. Define tipos, elementos de matrices, enumeraciones, formatos, límites y additionalProperties según las reglas reales de compatibilidad.
Prueba los errores además de los casos correctos
Conserva ejemplos con campos ausentes, tipos erróneos, valores nulos, enumeraciones desconocidas, propiedades adicionales, matrices vacías y todas las ramas oneOf o anyOf.
Gestiona la evolución del contrato
Compara los esquemas y los datos reales durante cada publicación, distingue las ampliaciones compatibles de los cambios incompatibles y trata los tipos de cliente generados solo como un punto de partida que debe revisarse.
Lista de revisión del esquema de API
- Define campos obligatorios opcionales y anulables
- Limita deliberadamente matrices enumeraciones y formatos
- Añade ejemplos erróneos representativos
- Revisa los solapamientos de oneOf y anyOf
- Prueba los cambios del esquema con datos reales
Guías relacionadas
Aprenda el workflow detrás de esta herramienta y qué revisar después.
Cómo depurar paso a paso una respuesta JSON de API
Un proceso repetible para separar errores de transporte, problemas de sintaxis JSON y fallos del contrato de datos en las respuestas de una API.
Cómo depurar payloads JSON de API
Un workflow práctico para formatear JSON, encontrar errores de sintaxis, validar la forma del payload y revisar el status cuando los datos de API no cuadran.