En esta página
La sintaxis indica si un texto puede leerse como JSON; JSON Schema comprueba requisitos explícitos sobre sus valores. Por eso una API puede rechazar un documento que un validador de sintaxis acepta. Comprueba primero la sintaxis y después valida el documento contra su esquema: un resultado conforme solo acredita las reglas que ese esquema contiene y que el validador admite.
| Comprobación | Pregunta que resuelve | Qué revisar si falla |
|---|---|---|
| Sintaxis | ¿Se pueden analizar ambos textos como JSON? | La entrada señalada: documento o esquema. |
| Esquema admitido | ¿El validador entiende el esquema y sus reglas? | El draft, las keywords y cómo están declaradas. |
| Conformidad | ¿Los valores cumplen ese esquema? | El campo y la regla del diagnóstico. |
| Reglas de negocio externas | ¿El pedido existe y está autorizado? | La fuente de datos y las comprobaciones de la aplicación. El esquema de este ejemplo no responde esas preguntas. |
Un pedido que se puede leer, pero no cumple el contrato
Este pedido ficticio tiene sintaxis JSON correcta:
{
"id": "00123",
"quantity": "2",
"active": true
}Supongamos que el contrato exige una cantidad entera de al menos una unidad. Este es el esquema completo para comprobarlo:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1 },
"quantity": { "type": "integer", "minimum": 1 },
"active": { "type": "boolean" }
},
"required": ["id", "quantity"],
"additionalProperties": false
}La raíz debe ser un objeto. properties describe los campos: id es una cadena no vacía, quantity es un entero mayor o igual que 1 y active, si aparece, es un booleano. required obliga a incluir id y quantity; declarar active en properties no lo hace obligatorio. additionalProperties: false prohíbe campos fuera de esa lista.
La distinción entre tipos y el mínimo inclusivo están definidos en JSON Schema draft-07, apartados 6.1.1 y 6.2.4. Aquí "2" es texto: que contenga un dígito no lo convierte en un entero.
Localizar el error y corregir lo que corresponda
- Abre el validador de JSON Schema. Pega el esquema completo en Esquema JSON y el pedido original en Documento JSON.
- Elige Validar. Si alguna entrada no se puede analizar, resuelve primero sus errores de sintaxis JSON.
- Con estas entradas, el resultado esperado es una incompatibilidad de
typeen/quantity, con la regla en/properties/quantity/type. - Confirma con el contrato y la fuente que el valor representa una cantidad. Si es así, cambia
"2"por2y vuelve a elegir Validar.
Las ubicaciones del diagnóstico son JSON Pointer, no consultas JSONPath. /quantity señala el dato; /properties/quantity/type, la regla del esquema. La traducción del mensaje puede variar: esas ubicaciones y la keyword permiten entender qué ha fallado.
El documento corregido queda así:
{
"id": "00123",
"quantity": 2,
"active": true
}El resultado esperado es conforme con este esquema. id sigue siendo una cadena y conserva sus ceros iniciales. No quites las comillas de todos los valores que parezcan números: un identificador no tiene por qué ser una cantidad. El validador no convierte "2" en 2; tú decides si el cambio está justificado.
Casos independientes: tipo, mínimo y campo adicional
Parte del documento corregido para cada fila y conserva el mismo esquema. Deshaz el cambio anterior antes de pasar al siguiente caso.
| Cambio único | Resultado esperado | Qué hacer con ese resultado |
|---|---|---|
Sustituir "quantity": 2 por "quantity": "2" |
type en /quantity. |
El texto no cumple el tipo entero. Confirma qué exige el contrato antes de cambiarlo. |
Sustituir "quantity": 2 por "quantity": 0 |
minimum en /quantity. |
El tipo es correcto, pero el mínimo es 1. Revisa la cantidad en la fuente; no inventes otra para superar la validación. |
Añadir "currency": "MXN" |
additionalProperties, propiedad currency, instancia raíz. |
El contrato no admite ese campo. Comprueba si sobra o si hay que revisar el esquema; no lo borres a ciegas. |
| No cambiar nada | Conforme. | Cumple las reglas declaradas, sin acreditar la existencia ni la autorización del pedido. |
La raíz se representa con el JSON Pointer vacío (""). Esta tabla reúne casos separados, no una salida con varios errores: la herramienta muestra solo la primera incompatibilidad. Tras corregirla y repetir, puede aparecer otra.
Cuando el problema está en el esquema
Un esquema puede tener JSON correcto y usar una keyword que esta herramienta no admite. Para ver la diferencia, conserva el pedido corregido y sustituye el esquema por este ejemplo deliberadamente no admitido:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"format": "email"
}El resultado esperado es esquema no admitido, por format, antes de evaluar los datos. No significa que el pedido sea no conforme ni que su identificador deba ser un correo. Restaura el esquema del pedido para continuar.
Esta herramienta implementa un subconjunto de draft-07. Exige un objeto en la raíz del esquema y el URI exacto de $schema mostrado arriba. Rechaza keywords desconocidas o no admitidas, entre ellas $ref, format, combinadores y condicionales. No ofrece compatibilidad completa con draft-07 ni con 2019-09 o 2020-12.
Qué demuestra un resultado conforme
El pedido corregido satisface este contrato. Eso no demuestra que "00123" exista, que haya existencias suficientes o que quien envía el pedido tenga permiso. Tampoco confirma que la cantidad copiada coincida con la fuente. Esas comprobaciones siguen correspondiendo a la aplicación y a la revisión del dato de origen.
La validación no repara sintaxis, elimina propiedades ni modifica la entrada. Además, una cancelación o un límite alcanzado deja la comprobación incompleta: no es un resultado conforme ni una prueba de incumplimiento. La página del validador de JSON Schema detalla los límites de tamaño, profundidad y operación, así como el rechazo de números que no puede representar con seguridad.