Versionado de esquemas y validación

JSON Schema tiene versiones de draft. Un draft define qué palabras clave existen y cómo los validadores deben interpretarlas. Los esquemas modernos a menudo usan Draft 2020-12, mientras que ecosistemas más antiguos pueden seguir esperando Draft 7.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

El campo $schema indica a las herramientas qué dialecto usar. Elige un draft que tus validadores, editores y herramientas de API soporten.

Los errores de validación forman parte del contrato

Un esquema útil falla con errores que señalan el problema:

• Propiedad requerida ausente
• Tipo incorrecto
• Valor por debajo del mínimo
• Cadena que no coincide con un formato
• Propiedad extra rechazada por política

Al revisar un esquema, prueba ejemplos válidos e inválidos. Los fixtures inválidos suelen ser más valiosos porque demuestran que el validador detecta los errores que te importan.

Reglas de compatibilidad

Cambiar un esquema puede romper clientes. Trata la evolución del esquema como la evolución de una API:

• Añadir una propiedad opcional suele ser seguro.
• Añadir una propiedad requerida puede romper productores existentes.
• Restringir un enum puede romper datos almacenados y clientes.
• Cambiar un tipo suele ser un cambio incompatible.
• Eliminar un campo puede romper consumidores.

Elección de draft en la práctica

Draft 2020-12 es un valor predeterminado sensato para nuevos flujos de trabajo locales. Draft 7 sigue siendo útil cuando herramientas antiguas lo requieren. El mejor draft es el más reciente que tu validador de producción realmente soporta.

Los esquemas son contratos vivos. Mantenlos cerca de ejemplos, pruebas y notas de versión para que el contrato de datos evolucione con el sistema en lugar de desviarse de él.