JSON Schema

JavaScript Object Notation (JSON)

JSON (JavaScript Object Notation) nos permite representar estructuras de datos de una manera que es fácil de leer y escribir tanto para las personas como para los sistema automáticos. Es independiente del lenguaje de programación y la gran mayoría de estos dispone de alguna forma de leer y manipular estructuras JSON. Por esta razón se utiliza mucho para el intercambio de datos. También se han desarrollado bases de datos para almacenar información en formato JSON o en las bases de datos relacionales, tipos de campo especiales.

 

JSON se basa en dos estructuras:

• Una colección de pares nombre/valor. En diferentes lenguajes de programación pueden tener diferentes nombres como objetos, registro, estructura, array asociativo, etc. En el par nombre/valor, el nombre siempre es un string. En cuanto a las posibilidades del valor lo veremos más abajo.
• Una lista ordenada de valores. En diferentes lenguajes de programación se les conoce como arrays, secuencias, vectores, etc.

 

El valor de los datos puede ser:

• String
• Número
• Objeto
• Array
• true
• false
• null

Podemos validar que un JSON está bien escrito usando algunas herramientas, algunas de ellas online, como por ejemplo el validador JSON Lint.

 

JSON Schema

En muchos casos podríamos necesitar un JSON se ciña a cierto formato. Digamos por ejemplo que el JSON representa a un usuario y deseamos que tenga un nombre, un email, y un teléfono de forma obligatoria. Esto lo podemos hacer usando JSON Schema.

 

Un JSON Schema es un JSON que describe la estructura que tendrá otro JSON, pudiendo definir que información puede contener, con que tipos de datos, que datos son obligatorios,  valores admitidos, etc.

 

JSON Schema:

• Dispone de una especificación, actualmente está en la versión 2021-02-01: Draft 2020-12. Para conocer en detalle puedes revisar los documentos oficiales de especificación.
• Permite describir  formatos.
• Proporciona una documentación entendible para las personas y las máquinas.
• Ayuda a validar si un Json (muchas veces llamado documento) se adecúa al formato, y de esta manera elaborar test automáticos, asegurar la calidad, mejorar la seguridad.

 

Paso a paso de como escribir un JSON Schema

Para ir aprendiendo como funciona JSON Schema, iremos escribiendo desde el formato más simple y poco a poco lo haremos más complejo. Al mismo tiempo  gracias a un validador en línea probaremos si nuestro schema está de acuerdo a la especificación y si el JSON que queremos probar se adapta al schema. El validador que vamos a utilizar es JSON Schema Lint, pero puedes usar el de tu preferencia. Hay varios disponibles.

 

Nuestro primer Schema nos indicará si el valor es un número entero.

{ "type": "integer" }

 

Hacemos la prueba en el validador.

 

Vemos que el validador nos dice que el schema es valida de acuerdo al draf-07. Y al probar cualquier número entero considera que el documento valida de acuerdo al schema presentado. Podemos ir un poco más lejos e indicar cual es el número mínimo (mínimum) y máximo (maximum). Hay una ligera variación e estos con "exclusiveMinimum" y "exclusiveMaximum" (deben escribirse respetando las mayúsculas y minúsculas).

 

{   "type": "integer",   "exclusiveMinimum": 5,   "exclusiveMaximum": 20 }

 

Podemos ahora probar reemplazado la palabra "integer", por "string", "array", "object". Haciendo las pruebas veremos que efectivamente valida que se trata de una cadena de texto, un array o un objeto. Incluso cuando el array está vacío, y el objeto no tiene propiedades.

 

 

Los types permitidos por JSON Schema son:

• string
• number
• integer
• object
• array
• boolean
• null

Equivalente a los tipos permitidos en un documento JSON con algunos matices: se permite indicar si un número es entero, y con boolean un valor puede ser true y false.

 

También podemos indicar una lista de opciones de tipo, usando un array.

 

{"type": ["array", "object"]}

 

Definiendo un array

Cuando indicamos que un tipo array, podemos agregar reglas adicionales, como el tipo de los items que va a contener, la cantidad mínima, cantidad máxima, y si estos deben ser únicos.

 

{

  "type": "array",   "items": {     "type": "string"   },   "minItems": 3,   "maxItems": 4,   "uniqueItems": true }

 

Propiedades de un objeto

En el caso de objetos, se puede definir que propiedades puede contener y si estas son requeridas o no.

{

  "type": "object",   "properties": {     "saludo": {       "description": "Sr., Sra. Dr. Lic.",       "type": "string"      },     "nombre": {       "description": "Nombre y apellido",       "type": "string"      }   },   "required": ["nombre"] }

Podemos ver que se puede indicar el tipo de las propiedades. También observamos que la opción de requerido tiene como valor un set, es decir, un array sin valores repetidos.

 

Combinando estructuras

Podemos combinar estructuras, por ejemplo colocar como el valor de propiedades de un objeto un array u otro objeto.

{   "type": "object",   "properties": {     "saludo": {       "description": "Sr., Sra. Dr. Lic.",       "type": "string"      },     "nombre": {       "description": "Nombre y apellido",       "type": "string"      },      "notas": {        "type": "array",        "items": {          "type": "integer"        },        "minItems": 1,        "maxItems": 5      }   },   "required": ["nombre", "notas"] }

 

Propiedade Generales

Los objetos que representan un JSON Schema tienen 4 propiedades. Veamos que las dos primeras comienzan con el signo dólar.

• $schema, nos indica a que versión del schema se ciñe nuestro documento.
• $id, es una URI del schema, y a la vez un idenficador. Nos será útil al momento de tener referencias a otros schemas.
• title y description, son solo descriptivas, y nos dicen para que es útil el schema.
• type, esta palabra que ya la hemos visto nos da la primera restricción del schema, indicándonos el tipo permitido.

 

Nuestro schema podría comenzar como lo mostramos más abajo. Los tres puntos en un paréntesis "(..)" lo estamos usando para omitir el resto del schema en este artículo, indicando que ahí debe ir. Así evitamos se extienda demasiado.

{   "$schema": "https://json-schema.org/draft/2020-12/schema",   "$id": "https://example.com/product.schema.json",   "title": "Persona",   "description": "Persona y sus notas",   "type": "object"

  (..) }

 

Estructuras embebidas

JSON Schema nos permite combinar diferentes schemas. Sobre este tema trataremos en otro artículo.