Esquema JSON a JSON: de la carga útil de muestra al contrato

¿Qué inferencia puedo y no puedo ver?

A partir de un único documento, un buen conversor deriva tipos, anidamientos, formas de elementos de matriz y nombres de propiedades con precisión. Lo que no puede derivar es la intención. No sabe que un campo es opcional porque este registro en particular lo incluye, que una cadena es una dirección de correo electrónico, que un número es un entero positivo o que un valor proviene de un conjunto fijo. Por lo tanto, todo lo derivado se marca con `required`, que es el valor predeterminado correcto para un borrador de contrato y lo incorrecto para enviar sin examinar.

Endurecer el esquema generado

1. Compare dos o tres muestras reales: las claves que faltan en cualquier muestra deberían salir de `required`.
2. Agregue `format` donde se conozca el significado: `date-time`, `email`, `uri`, `uuid`, `ipv4`.
3. Convierta conjuntos abiertos en valores `enum` cuando el campo realmente tenga un vocabulario fijo, como un estado o una región.
4. Apriete los números con `minimum`, `maximum` y `multipleOf` para que una cantidad negativa no pueda validarse.
5. Agregue `additionalProperties: false` solo cuando se deban rechazar claves desconocidas; de lo contrario, deje el esquema abierto para compatibilidad futura.

Se requiere una promesa, no una observación. Marcar un campo como obligatorio porque su única muestra lo contenía es la forma más común en que un esquema inferido rompe una integración real.

Donde el esquema se gana la vida

El valor práctico se muestra en los límites: validar la carga útil de un webhook antes de confiar en él, verificar los archivos de dispositivos en CI para que las pruebas fallen en datos con formato incorrecto en lugar de errores nulos confusos, documentar una respuesta API para personas que nunca leerán el código del servidor y generar clientes escritos. Un esquema JSON también es la forma más económica de evitar que un cambio de configuración altere silenciosamente una respuesta pública, porque el validador lo detecta en el momento de la compilación en lugar de en producción.

                {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "plan": { "type": "string", "enum": ["free", "pro", "team"] }
  }
}
              

Mantenlo en control de versiones.

Los esquemas generados cambian en el momento en que nadie los posee. Confirme el archivo reforzado junto al código que produce los datos, haga referencia a él desde el validador en CI y regenere solo cuando el contrato realmente cambie, tratando el esquema como la fuente de verdad para la forma y la muestra como evidencia, y no al revés.

Inferencia en el navegador

Las cargas útiles reales están llenas de identificadores, correos electrónicos y tokens, por lo que una conversión de esquema de JSON a JSON que carga la muestra entrega datos de producción para una operación puramente mecánica. La inferencia local mantiene la carga útil en la pestaña, le permite pegar un registro de cliente sin pensarlo dos veces y funciona con la red cortada.