JSON Schema: validar datos en línea (Draft 2020-12)

¿Por qué validar datos JSON contra un esquema?

Un JSON válido no es necesariamente válido para tu API. Un payload puede parsear a la perfección y aun así faltar un campo requerido, enviar un tipo incorrecto o violar una restricción format — y esos bugs a menudo aparecen solo en tests de integración o en producción. JSON Schema responde a una pregunta distinta de la comprobación sintáctica: ¿esta instancia respeta el contrato? El validador JSON Schema en línea de FastMinify ejecuta la validación Draft-07 y 2020-12 en dos editores Monaco (esquema + instancia), enteramente en tu navegador. Asócialo al validador JSON si la sintaxis es dudosa, y a validate-openapi cuando el contrato vive en OpenAPI. Explora el hub de herramientas API para la conversión de esquemas y el lint OpenAPI.

Esquema vs. sintaxis: detectar campos required faltantes y tipos incorrectos después del parse JSON

Draft-07 y 2020-12 vía Ajv — errores instancePath / keyword por violación

Doble editor con debounce en vivo (~300 ms) — sin instalación ni cuenta

Modo Strict opcional para la review de esquemas (Ajv strict: true en la compilación)

100 % local — esquema y payloads nunca salen del navegador

Límites honestos y esquemas mantenibles

Lo que el validador del navegador no hace

Un resultado verde significa que la instancia coincidió con el esquema pegado — no que toda la plataforma API sea conforme.

Sin fetch de red — $ref externas y https:// nunca se resuelven

Sin bundle multiarchivo — pega un esquema JSON autónomo por ejecución

Sin lint de operaciones OpenAPI — usa lint-openapi para operationId y tags

Sin sondeo de endpoints en vivo — la instancia debe pegarse de forma explícita

Esquemas Draft-04/06/2019-09 rechazados — migrar o convertir los drafts primero

Consejos de diseño de esquema

Los esquemas que pasan de forma limpia en el navegador sobreviven mejor a la CI y a la generación de SDK.

Define siempre $schema en los archivos compartidos — evita asunciones 2020-12 implícitas

Prefiere additionalProperties: false solo para objetos cerrados de forma deliberada

Usa examples OpenAPI y pégalos como instancias en review

Alinea los enums con el código — documenta los valores deprecados en description

Versiona los breaking changes — los consumers validan contra el tag de esquema objetivo

Cuándo escalar a la CI

Los checks del navegador ahorran minutos de pipeline; la política de la organización sigue en CI.

Ajv o jsonschema en GitHub Actions / GitLab CI en cada PR

Detectores de breaking change entre versiones de esquema

Pact o tests de contrato en entornos en vivo

Registries de esquema (Apicurio, Buf) para gobernanza multi-equipo

Combina con nuestra guía CI/CD

Sintaxis JSON vs. validación JSON Schema

Dos validadores, dos preguntas

No cambies de herramienta a mitad de un debug: cada una apunta a un modo de fallo distinto.

Validador JSON (json-validator): solo sintaxis — comas finales, comillas simples, pegado truncado

Validador JSON Schema (json-schema-validator): contrato semántico — types, required, enums, formats

Sintaxis verde + esquema rojo = violación de contrato, no error de parse

Repara el JSON con json-repair o los enlaces siblings del validador

La validación de documento OpenAPI es una tercera intención — usa validate-openapi para el envoltorio de la spec

Drafts soportados (y lo que se rechaza)

FastMinify detecta el draft vía $schema si está presente; sin $schema, el valor por defecto es 2020-12.

Draft 2020-12 — https://json-schema.org/draft/2020-12/schema

Draft-07 — http://json-schema.org/draft-07/schema#

Draft-04, Draft-06 y 2019-09 → error unsupported-draft explícito — sin conversión silenciosa

Declara el draft de forma explícita en los esquemas compartidos para evitar derivas de equipo

OpenAPI 3.1 se alinea con 2020-12; OpenAPI 3.0 usa a menudo Draft-07 en components.schemas

instancePath y errores keyword

En caso de fallo, Ajv indica dónde la instancia violó el esquema — indispensable en payloads API grandes.

instancePath apunta al valor en fallo (estilo JSON Pointer)

El keyword indica la regla en fallo (required, type, format, …)

Las violaciones múltiples se muestran por separado — corrige por prioridad de negocio

Instancia vacía con esquema required → ruta / o propiedades faltantes

Usa el visualizador JSON en payloads profundos

Validar JSON contra un esquema: paso a paso

Usar el validador JSON Schema

El validador JSON Schema ofrece dos editores: Esquema e Instancia. Pega JSON en cada campo — no YAML en el editor de esquema (solo JSON). Máx. 512 KiB por campo.

Validación en vivo tras debounce (~300 ms) cuando ambos lados parsean

Panel de resultados: válido / inválido, número de violaciones, draft detectado

Por error: instancePath, keyword, mensaje

Acciones copiar y expand (⌘⇧E) en cada panel

Toggle Strict — desactivado por defecto; actívalo para lint de esquema estilo CI

Modo Strict: cuándo activarlo

El modo Strict activa Ajv strict: true en la compilación del esquema — keywords desconocidos y esquemas no estrictos fallan antes de la validación de instancia.

Desactivado (por defecto): debug pragmático de esquemas reales con claves extra

Activado: review de esquema antes de publicar en un registry o en <code>components.schemas</code> OpenAPI

Errores de compilación Strict en el panel de resultados — corrige el esquema y vuelve a probar

Combina Strict con <a href="/es/format-openapi" class="text-primary hover:underline">format-openapi</a> para esquemas embebidos

No sustituye la gobernanza Spectral ni vocabularios custom de la organización

Escenario — respuesta API que falla en staging

El cliente móvil se cae con una nueva forma de campo: la respuesta es JSON válido pero rompe el esquema publicado.

Paso 1: confirmar la sintaxis JSON

Pega la respuesta en json-validator. Si la sintaxis falla, repara antes de la validación de esquema.

Paso 2: pegar esquema e instancia

Abre json-schema-validator. Pega el esquema canónico (export OpenAPI o registry) y la respuesta de staging.

Paso 3: leer los errores instancePath

Corrige la API o actualiza el esquema con un plan de deprecación. Vuelve a validar después del despliegue. Opción: diff staging vs. producción.

Escenario — archivo de config antes de kubectl apply

El equipo comparte una config JSON validada en CI — quieres un check local rápido sin clonar el pipeline.

Paso 1: cargar el esquema del repo

Copia el JSON del esquema (autónomo — las $ref externas no se resuelven en el navegador).

Paso 2: validar tu edición

Pega la config modificada como instancia. Activa Strict si el esquema está escrito para una review estricta.

Paso 3: encadenar con YAML si hace falta

Las configs suelen estar en YAML — convierte vía yaml-to-json, valida la sintaxis y luego el esquema sobre la instancia JSON.

OpenAPI, components.schemas y conversión

Dónde viven los esquemas en los contratos API

Los equipos REST suelen publicar en OpenAPI components.schemas mientras que los registries guardan archivos standalone — el validador acepta ambos una vez extraídos a JSON. Workflow: validate-openapi (envoltorio de spec) → extraer esquema → json-schema-validator (payload vs. esquema). Consulta nuestra guía de validación OpenAPI y la guía de lint y format para la cara spec del contrato.

Convertir entre OpenAPI y JSON Schema

Cuando la fuente es el archivo OpenAPI, pivota los formatos en el hub sin CLI local: openapi-to-json-schema extrae un esquema de los components OpenAPI; json-schema-to-openapi envuelve un esquema standalone para importarlo en un portal.

Mentalidad de contract testing

La validación en el navegador acelera el feedback; la CI conserva las suites de regresión. Pega instancias representativas — happy path, nulls, límites de enum. Documenta el draft en $schema junto a cada archivo de esquema compartido en git.

Fallos de validación frecuentes

Errores de instancia habituales

Estos casos vuelven una y otra vez en soporte y jobs CI inestables.

Propiedad required faltante — instancePath en el padre o /

Tipo type incorrecto — string en lugar de integer (frecuente tras serialización de formulario)

additionalProperties: false — campos de más tras un error de versionado de API

Violaciones format — date-time, email, uuid (vía ajv-formats)

Mismatch enum — códigos de estado o regiones no documentados en el payload

Errores de compilación de esquema

El modo Strict y los drafts no soportados aparecen aquí antes de la validación de instancia.

URL $schema no soportada — migrar a Draft-07 o 2020-12

$ref externa — error duro; inlinea o empaqueta las refs en local

YAML pegado en el editor de esquema — convertir a JSON o pegar solo JSON

Esquema > 512 KiB — dividir o usar bundlers de CI

Keywords desconocidos bajo Strict — retirar o mover según la política de la organización

Conclusión

La validación JSON Schema cubre el hueco entre JSON parseable y datos API fiables. Empieza por la sintaxis si hace falta, luego valida las instancias contra esquemas Draft-07 o 2020-12 con errores instancePath claros — en local, antes de la CI. Extrae los esquemas desde OpenAPI cuando el contrato vive en la spec, y mantén límites honestos sobre refs, drafts y tamaño.

Validar tu instancia JSON contra un esquema ahora

Sintaxis primero con json-validator — validación de esquema después

Declara $schema de forma explícita en cada archivo de esquema compartido

Activa Strict para review de esquema antes del merge, no para debug de payload suelto

Empaqueta las $ref externas en local — la herramienta del navegador nunca hace fetch de URLs

Encadena con openapi-to-json-schema cuando la fuente es un archivo OpenAPI