Saltar a contenido

JSON Schema

JSON Schema es un vocabulario que le permite validar, anotar y manipular documentos JSON, de forma segura y fiable.

se utiliza principalmente cuando tienes un JSON, que:

  • se necesita armar y es complejo en campos y estructura.
  • la respuesta de un servicio con muchos campos.
  • tiene demasiados campos para realizar una validacion mediante código.

JSON Schema permite definir un JSON, para validar la estructura de otro JSON 😄 así tal cual!.

Nota

Callisto utiliza la versión/borrador 2020-12.

Borradores

A la versión actual del estandar se le denomina comunmente borrador, la versión que se utiliza, por ejemplo en Callisto para la validación de la estructura del cuerpo de la petición de algunos servicios es 2020-12.

Implementaciones

Las implementaciones son librerias en diferentes lenguajes de programación para validar esquemas.

Ejemplos

Tenemos el siguiente JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "fruits": [
        "apple",
        "orange",
        "pear"
    ],
    "vegetables": [
        {
            "veggieName": "potato",
            "veggieLike": true
        },
        {
            "veggieName": "broccoli",
            "veggieLike": false
        }
    ],
    "count": 21,
    "status": "Active",
    "address": "Great Russell St, London WC1B 3DG",
    "online": true,
    "expireAccount": "2021-12-31",
    "latitude": 51.520071
    "longitude": -0.123908
}

Este ejemplo en particular, tiene varios tipos de datos y carácteristicas que lo hacen expecialmente complicado de validar, sí lo que se quiere, es que no solo la estructura del JSON sea válida (campos requeridos, tipos de datos correctos por campo etc..). si no que los datos sean consistentes.

Normalmente con muchas validaciónes en tu código (muchas líneas de código), revisarías cada campo y su tipo de datos.

Sin embargo al definir un "esquema" con JSON Schema, la validación del JSON de entrada resulta muy sencilla.

Importante

En este punto, como se comentaba más arriba...

JSON Schema permite definir un JSON para validar un esquema de otro JSON.

Ahora se define cada aspecto de la validación:

1
2
3
4
5
6
7
8
9
    - tipos de datos
    - limites de los datos
    - limites de carácteres
    - limites para campos numericos
    - establecer que tipos de entrada que serán aceptados (Ej. lista de vegetales)
    - cantidad de elementos (para los arreglos)
    - como validar correctamente fechas
    - como validar correctamente coordenadas
    - cualquier otra cosa que se pueda validar

Y finalmente tenemos nuestro esquema:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "fruits": {
            "type": "array",
            "minItems": 1,
            "maxItems": 12,
            "items": {
                "type": "string",
                "minLength": 3,
                "maxLength": 32
            }
        },
        "vegetables": {
            "type": "array",
            "items": {
                "type": "object",
                "minProperties": 1,
                "maxProperties": 12,
                "properties": {
                    "veggieName": {
                        "type": "string",
                        "minLength": 3,
                        "maxLength": 32
                    },
                    "veggieLike": {
                        "type": "boolean"
                    }
                }
            }
        },
        "count": {
            "type": "integer"
        },
        "status": {
            "type": "string"
        },
        "address": {
            "type": "string"
        },
        "online": {
            "type": "boolean"
        },
        "expireAccount": {
            "type": "string",
            "format": "date"
        },
        "latitude": {
            "type": "number"
        },
        "longitude": {
            "type": "number"
        }
    }
}

Para tener en cuenta

Definir un esquema para validar grandes estructuras JSON, reduce significativamente la cantidad de código para realizar validaciones y consigo mismo, los errores que esto pueda conllevar, además los datos serán revisados de forma estricta y los errores por información errónea se reduce casi a cero.

Lectura recomendada