JSON Schema: valida un contrato de suscripción pequeño

Un esquema útil describe un contrato real e incluye entradas que debe aceptar y rechazar. No sustituye autenticación, autorización ni límites de recursos anteriores al parseo.

Prueba el ejemplo completo

Abre el validador JSON Schema y pega este esquema en su panel. También puedes descargar subscription.schema.json.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "plan",
    "seats"
  ],
  "properties": {
    "plan": {
      "enum": [
        "basic",
        "pro"
      ]
    },
    "seats": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    },
    "company": {
      "type": "string",
      "minLength": 1
    }
  },
  "if": {
    "properties": {
      "plan": {
        "const": "pro"
      }
    },
    "required": [
      "plan"
    ]
  },
  "then": {
    "required": [
      "company"
    ]
  }
}

La suscripción ficticia tiene dos planes. seats debe ser un entero entre 1 y 25. El plan pro exige además una empresa no vacía. Esos límites pertenecen al ejemplo, no son una recomendación comercial.

Prueba cada entrada por separado:

Desplázate horizontalmente para ver todas las columnas.

Comprueba que el error identifica la ruta de entrada o de esquema relevante. No conviertas tipos silenciosamente para superar la validación salvo que el contrato de la aplicación defina esa conversión.

Campos obligatorios, adicionales y condicionales

properties describe valores presentes; required exige que existan. Una empresa vacía falla minLength: incluir la clave no basta. La condición añade el requisito para pro sin duplicar el esquema completo.

Rechazar propiedades extra encaja con este contrato cerrado. Otros objetos de extensiones o metadatos permiten claves arbitrarias de forma intencionada. Decide esa política en cada nivel. Al componer esquemas, additionalProperties sólo reconoce las propiedades declaradas a su lado; los drafts recientes ofrecen también unevaluatedProperties para composición.

Escoge un dialecto compatible

La URI $schema identifica el dialecto previsto. JSONCraft utiliza @cfworker/json-schema con 2020-12 por defecto; tu backend puede usar otra biblioteca o versión. Comprueba soporte antes de copiar palabras clave nuevas a Draft 7. Por ejemplo, 2020-12 usa prefixItems para posiciones de tuplas: no lo mezcles con ejemplos antiguos de items como array.

Las referencias locales permiten reutilizar definiciones en $defs. Resuelve esquemas aprobados bajo control de la aplicación; aceptar referencias de red arbitrarias añade otro problema de disponibilidad y seguridad.

Formatos y límites

Que format compruebe validez depende del dialecto, vocabulario y configuración. Prueba la implementación concreta. Un string con forma de email no demuestra que exista el buzón; una URL sintácticamente válida no garantiza que sea seguro solicitarla. Conserva aparte esas comprobaciones de dominio.

Limita el tamaño y el trabajo antes de validar. Un esquema aplicado después de parsear no evita todas las reservas de memoria del parser. Consulta seguridad de entradas y utiliza el formateador para distinguir errores de sintaxis y de contrato.

Referencias: objetos JSON Schema, condiciones, formatos y validador usado por JSONCraft.