Helper DataFilter

---

1Presentación

Helper usado para filtrar o validar datos con el fin de comprobar que cumplen un contrato. Esto puede ser útil para garantizar que los datos entrantes de una API coincidan con lo esperado.

---

2Uso

El objeto \Temma\Utils\DataFilter ofrece un método estático process(). Este método recibe como parámetros los datos que se deben filtrar y el contrato que se debe aplicar, y devuelve los datos filtrados. Si la sintaxis del contrato es incorrecta, el método lanza una excepción \Temma\Exceptions\IO. Si los datos no cumplen el contrato, el método lanza una excepción \Temma\Exceptions\Application.

Un tercer parámetro opcional permite especificar si la validación debe realizarse en modo estricto o no. Por defecto, la validación no es estricta.

Un cuarto parámetro opcional, pasado por referencia, permite recuperar los datos procesados. Para la mayoría de los tipos de contrato, este parámetro contiene los datos filtrados (idéntico al valor devuelto por el método). Para ciertos tipos como binary, base64 o json, este parámetro contiene datos procesados específicos (consulta la documentación de cada tipo).

Ejemplo de uso:

use \Temma\Utils\DataFilter as TµDataFilter;
use \Temma\Exceptions\IO as TµIOException;
use \Temma\Exceptions\Application as TµApplicationException;
use \Temma\Base\Log as TµLog;

$contract = 'enum; values: admin, member, guest';
/* equivalente a la línea anterior:
$contract = [
    'type'   => 'enum',
    'values' => ['admin', 'member', 'guest'],
];
*/
try {
    $data = TµDataFilter::process($data, $contract);
} catch (TµIOException $ie) {
    TµLog::log('myapp', 'WARN', "Contrato inválido.");
    throw $ie;
} catch (TµApplicationException $ae) {
    TµLog::log('myapp', 'WARN', "Datos inválidos.");
    throw $ae;
}

// ejecución en modo estricto
try {
    $data = TµDataFilter::process($data, $contract, true);
} catch (\Exception $e) {
    TµLog::log('myapp', 'WARN', "Error de validación.");
    throw $e;
}

// recuperación de los datos procesados mediante el parámetro $output
try {
    $data = TµDataFilter::process($data, $contract, false, $output);
    // $output contiene los datos procesados
} catch (\Exception $e) {
    TµLog::log('myapp', 'WARN', "Error de validación.");
    throw $e;
}

---

3Definición de contrato

3.1Tipo y parámetro

Los contratos se usan para definir el tipo de dato que se debe filtrar o validar. Pueden escribirse como una cadena de texto o como un array asociativo.

Un contrato contiene al menos el tipo que los datos deben respetar.
Ejemplos: 'int', 'string'

Un contrato también puede recibir parámetros adicionales.
Los parámetros pueden escribirse de dos formas diferentes:

• Pueden añadirse a la cadena de configuración del contrato, después de la definición del tipo. Los parámetros se separan con punto y coma (;), y los nombres de los parámetros se separan de sus valores con dos puntos (:).

  Ejemplo: 'int; default: 3'

• Los contratos también pueden escribirse como un array asociativo. El tipo y los parámetros se representan como pares clave/valor en el array. Este formato es obligatorio al definir subcontratos.

  Ejemplo: ['type' => 'int', 'default' => 3]

Por último, cuando un contrato espera un array asociativo (tipo 'assoc') pero falta la clave 'type', el tipo 'assoc' se infiere automáticamente, y el array que contiene el contrato se considera como el valor del parámetro 'keys'.

Ejemplo: ['name' => 'string']
es equivalente a: ['type' => 'assoc', 'keys' => ['name' => 'string']]

---

3.2Tipos anulables

Todos los tipos pueden volverse anulables anteponiendo un signo de interrogación: '?bool', '?false', '?true'…

---

3.3Tipos múltiples

Es posible usar múltiples tipos. Por ejemplo: 'null|int|string', 'int|float'

---

3.4Validación automática (pass-through)

Si el contrato proporcionado es el valor null (y no la cadena "null"), los datos de entrada se devuelven tal cual.

---

3.5Modo estricto

Por defecto, el objeto DataFilter funciona en modo no estricto: si es necesario, realiza una conversión de tipo (por ejemplo, convirtiendo una cadena que contiene dígitos en un entero); para algunos parámetros, se comporta de forma permisiva (por ejemplo, si un número supera el máximo definido, se devuelve el máximo en lugar de lanzar un error; si una cadena supera la longitud máxima definida, se trunca); las claves no definidas en un array asociativo se eliminan.

Para ejecutar el filtrado en modo estricto, debes definir el parámetro strict como true (consulta cómo usar el objeto DataFilter más arriba).

Un contrato también puede forzar una evaluación estricta o no estricta:

• Para forzar una evaluación estricta, antepón al tipo un signo igual (=).
  Ejemplos: '=int', '=string'
• Para forzar una evaluación no estricta, antepón al tipo una virgulilla (~).
  Ejemplos: '~int', '~string'

---

3.6Valor por defecto

Usando el parámetro default, es posible proporcionar un valor alternativo, que se usará si los datos de entrada no son válidos. El valor por defecto debe ser del mismo tipo que se está validando.

Ejemplos:

'bool; default: false'

[
    'type'    => 'list',
    'default' => [1, 2, 3],
]

---

3.7Otros parámetros

• min: Valor mínimo (para un número, fecha, hora o coordenada geográfica).
• max: Valor máximo (para un número, fecha, hora o coordenada geográfica).
• minLen: Longitud mínima (número de caracteres para una cadena o URL, número de elementos para una lista).
• maxLen: Longitud máxima (número de caracteres para una cadena o URL, número de elementos para una lista).
• mask: Expresión regular (para una cadena, dirección de correo electrónico o URL).
• format: Formato de entrada y salida para una fecha/hora.
• inFormat: Formato de entrada para una fecha/hora.
• outFormat: Formato de salida para una fecha/hora.
• values: Valores aceptados para una enumeración, o tipos aceptados en una lista.
• contract: Contrato de validación para el contenido de una lista.
• keys: Lista de claves esperadas en un array asociativo.
• mime: Lista de tipos MIME autorizados (en un contenido binario o codificado en base64).
• charset: Conjunto de caracteres. Puede ser una cadena simple ('utf-8') o una lista ('utf-8, iso-8859-1'). En el caso de una lista, el primer conjunto de caracteres es el destino de la conversión (en modo no estricto), los siguientes son conjuntos de caracteres alternativos aceptados.
• algo : Algoritmo de hash (consulta la función hash_algos(): md2, md4, md5, sha1, sha224, sha256, sha384, sha512/224, sha512/256, sha512, sha3-224, sha3-256, sha3-384, sha3-512, ripemd128, ripemd160, ripemd256, ripemd320, whirlpool, tiger128,3, tiger160,3, tiger192,3, tiger128,4, tiger160,4, tiger192,4, snefru, snefru256, gost, gost-crypto, adler32, crc32, crc32b, crc32c, fnv132, fnv1a32, fnv164, fnv1a64, joaat, murmur3a, murmur3c, murmur3f, xxh32, xxh64, xxh3, xxh128, haval128,3, haval160,3, haval192,3, haval224,3, haval256,3, haval128,4, haval160,4, haval192,4, haval224,4, haval256,4, haval128,5, haval160,5, haval192,5, haval224,5, haval256,5).
• source : Datos de origen que se usarán para el hash.
• scheme, host, domain, port, user, pass, path, query, fragment : Elementos aceptados en una URL (consulta la función PHP parse_url()). Se puede proporcionar una lista de valores para cada elemento.
  domain corresponde al dominio de nivel superior encontrado en host (por ejemplo, siteweb.com para www.test.siteweb.com).

---

4Tipos escalares

4.1null

• Los datos de entrada deben ser null.
• No se acepta ningún parámetro.

Ejemplos:

'null'
['type' => 'null']

---

4.2false, true, bool

false

• Modo estricto: los datos deben ser iguales a false.
• Modo no estricto: los datos deben ser iguales a false o a cualquier valor que PHP convierta automáticamente a false (null, 0, cadena vacía, array vacío).
• Parámetro aceptado: default

Ejemplos:

// valida un valor false
'false'
['type' => 'false']

// devuelve false aunque los datos tuvieran otro valor
'=false; default: false'

true

• Modo estricto: los datos deben ser iguales a true.
• Modo no estricto: los datos deben ser iguales a true o a cualquier valor que PHP convierta automáticamente a true (número distinto de cero, cadena no vacía, array no vacío, objeto).
• Parámetro aceptado: default

Ejemplos:

// valida un valor true
'true'
['type' => 'true']

// valida un valor true, siempre en modo no estricto
'~true'

bool

• Modo estricto: los datos deben ser iguales a true o false.
• Modo no estricto: los datos se convierten a un booleano.
• Parámetro aceptado: default

Ejemplos:

// valida un booleano
'bool'
['type' => 'bool']

// booleano con un valor por defecto false
'bool; default: false'
[
    'type'    => 'bool',
    'default' => true,
]

---

4.3int, float

int

• Modo estricto: los datos deben ser un entero.
• Modo no estricto: los datos pueden ser un booleano (convertido a 0 o 1), un entero, un float (convertido a entero), o una cadena que contenga dígitos (convertida a entero).
• Parámetros aceptados: default, min, max

Ejemplos:

// valida un entero
'int'

// valida un entero en modo no estricto, con un valor por defecto
'~int; default: 3'

// valida un entero en modo estricto, mayor o igual que 5
'=int; min: 5'

// entero entre 5 y 8, con un valor por defecto
'int; min: 5; max: 8; default: 6'

// valida un entero
['type' => 'int']

// con un valor mínimo
[
    'type' => 'int',
    'min'  => 5,
]

float

• Modo estricto: los datos deben ser un float.
• Modo no estricto: los datos pueden ser un booleano (convertido a 0.0 o 1.0), un float, un entero (convertido a float), o una cadena que contenga dígitos (convertida a float).
• Parámetros aceptados: default, min, max

Ejemplos:

// valida un float
'float'

// valida un float en modo no estricto, con un valor mínimo
'~float; min: 2.7'

// valida un float en modo estricto, con un valor máximo
[
    'type' => '=float',
    'max'  => 18.5,
]

---

4.4string

• Modo estricto: los datos deben ser una cadena.
• Modo no estricto: los datos pueden ser una cadena, un booleano (convertido a "true" o "false"), o cualquier valor escalar (convertido a cadena).
• Parámetros aceptados: default, minLen, maxLen, mask, charset

Ejemplos:

// valida una cadena, con un valor por defecto
'string; default: abc'

// valida una cadena de entre 3 y 12 caracteres
'string; minLen: 3; maxLen: 12'

// valida una cadena que coincide con una expresión regular
'string; mask: ^[Bb][Oo0]..[Oo0].r$'
// equivalente
[
    'type' => 'string',
    'mask' => '^[Bb][Oo0]..[Oo0].r$',
]

// valida una cadena codificada en UTF-8
'string; charset: utf-8'

// valida una cadena, y la convierte a UTF-8 si es necesario (en modo no estricto)
'string; charset: utf-8, iso-8859-1'

---

5Tipos avanzados

5.1email, url, uuid, hash

email

• Los datos deben ser una dirección de correo electrónico válida.
• Parámetros aceptados: default, minLen, maxLen, mask

Ejemplos:

// valida una dirección de correo electrónico, con un valor por defecto
'email; default: contact@domain.com'

// con una expresión regular
'email; mask: @domain.com$'

// con una expresión regular y un valor por defecto
[
    'type'    => 'email',
    'default' => 'contact@domain.com',
    'mask'    => '@domain.com$',
]

url

• Los datos deben ser una URL válida.
• Parámetros aceptados: default, minLen, maxLen, mask, scheme, host, domain, port, user, pass, path, query, fragment

Ejemplos:

// valida una URL
'url'

// URL de menos de 200 caracteres
'url; maxLen: 200'

// URL en el host "www.foo.com" o "test.foo.com"
'url; host: www.foo.com, test.foo.com'

// con una expresión regular
[
    'type' => 'url',
    'mask' => 'https?:..www.domain.com/.$',
]

// URL https en el host "foo.com" o "*.foo.com", en el puerto 8080,
// con el usuario "bob", y el fragmento "api" o "json"
'url; scheme: https; domain: foo.com; port: 8080; user: bob; fragment: api, json'

uuid

• Los datos deben ser un UUID válido.
• Parámetro aceptado: default

Ejemplo:

// valida un UUID con un valor por defecto
'uuid; default: 123e4567-e89b-12d3-a456-426614174003'

hash

• El valor debe ser una cadena hexadecimal con la longitud requerida según el algoritmo de hash usado (por ejemplo, 32 caracteres para MD5, 40 para SHA-1, 64 para SHA2-256, etc.).
• Si se proporciona el parámetro source, se calcula su hash y se compara.
• Parámetros aceptados : default, algo (obligatorio), source

Ejemplos :

// valida un hash MD5
'hash; algo: md5'

// valida un hash SHA256 o SHA512
'hash; algo: sha256, sha512'

// valida un hash MD5 verificando el valor calculado
[
    'type'   => 'hash',
    'algo'   => 'md5',
    'source' => $data,
]

Ten en cuenta que hay varios alias disponibles para simplificar el uso : md5, sha1, sha256, sha512

Ejemplos 

// valida un hash MD5
'md5'

// valida un hash SHA256 verificando el valor calculado
'sha256; source: input_data'

---

5.2binary, base64

binary

• Comprueba si los datos proporcionados son una cadena binaria válida.
• El parámetro mime es opcional, y acepta uno o varios tipos MIME (separados por comas). Los tipos pueden ser específicos (por ejemplo, image/jpeg) o genéricos (image). Si los datos no corresponden a ninguno de los tipos indicados, se lanza una excepción.
• Parámetros aceptados: default, minLen, maxLen, mime, charset

Ejemplos:

// valida una imagen GIF o PNG
'binary; mime: image/gif, image/png'

// valida una imagen o un PDF
'binary; mime: image, application/pdf'

base64

• Los datos deben estar codificados en Base64.
• Modo:
  • no estricto: los datos se decodifican.
  • estricto: los datos se decodifican, luego se codifican de nuevo, y el resultado se compara con los datos originales.
• Con el parámetro mime, es posible especificar uno o varios tipos MIME (separados por comas). Si el contenido codificado en base64 no corresponde a ninguno de los tipos indicados, se lanza una excepción.
• Parámetros aceptados: default, minLen, maxLen, mime, charset

Ejemplos:

// valida cualquier contenido codificado en base64
'base64'

// valida una imagen GIF o PNG
'base64; mime: image/gif, image/png'

// valida una imagen o un PDF
'base64; mime: image, application/pdf'

---

5.3date, time, datetime

date

• Si los datos son un entero, un float, o una cadena que contiene dígitos, se interpretan como una marca de tiempo Unix.
• Si los datos son una cadena, deben coincidir con el formato de entrada (Y-m-d por defecto).
• Modo:
  • estricto: la fecha debe ser válida (la fecha 2026-12-33 se rechaza).
  • no estricto: la fecha se convierte (2026-12-33 se convierte en 2027-01-02).
• Los datos se devuelven usando el formato de salida especificado (Y-m-d por defecto).
• Parámetros aceptados: default, format, inFormat, outFormat, min, max

Ejemplos:

// valida una fecha con un formato de salida especificado
'date; outFormat: d/m/Y'

// especificando el formato de entrada, con una fecha mínima posterior al 1 de enero de 2000
'date; inFormat: d/m/Y; min: 01/01/2000'

time

• Si los datos son un entero, un float, o una cadena que contiene dígitos, se interpretan como una marca de tiempo Unix.
• Si los datos son una cadena, deben coincidir con el formato de entrada (H:i:s por defecto).
• Modo:
  • estricto: la hora debe ser válida (la hora 13:65:34 se rechaza).
  • no estricto: la hora se convierte (13:65:34 se convierte en 14:05:34).
• Los datos se devuelven usando el formato de salida especificado (H:i:s por defecto).
• Parámetros aceptados: default, format, inFormat, outFormat, min, max

Ejemplos:

// valida una hora con el mismo formato de entrada y salida
'time; format: H:i;'

// valida una hora entre las 15:00 y las 17:00
'time; min: 15:00:00; max: 17:00:00'

datetime

• Si los datos son un entero, un float, o una cadena que contiene dígitos, se interpretan como una marca de tiempo Unix.
• Si los datos son una cadena, deben coincidir con el formato de entrada (Y-m-d H:i:s por defecto).
• Modo:
  • estricto: la fecha/hora debe ser válida (la fecha/hora 2026-12-33 13:65:34 se rechaza).
  • no estricto: la fecha/hora se convierte (2026-12-33 13:65:34 se convierte en 2027-01-02 14:05:34).
• Los datos se devuelven usando el formato de salida especificado (Y-m-d H:i:s por defecto).
• Parámetros aceptados: default, format, inFormat, outFormat, min, max

Ejemplos:

// valida una fecha/hora usando un formato de entrada específico
'datetime; inFormat: d/m/Y H:i'

// valida una fecha/hora devuelta como timestamp, especificando el formato de entrada y el rango permitido
[
    'type'      => 'datetime',
    'inFormat'  => 'd/m/Y H:i:s',
    'outFormat' => 'U',
    'min'       => '2000-01-01 00:00',
    'max'       => '2050-12-31 23:59',
]

---

5.4isbn, ean

isbn

• Los datos deben ser un ISBN válido.
• Parámetro aceptado: default

Ejemplos:

// valida un ISBN con un ISBN-10 por defecto
'isbn; default: 0-306-40615-2'
// lo mismo sin guiones
'isbn; default: 0306406152'

// valida un ISBN con un ISBN-13 por defecto
'isbn; default: 978-3-16-148410-0'
// lo mismo sin guiones
'isbn; default: 9783161484100'

ean

• Los datos deben ser un código EAN válido.
• Parámetro aceptado: default

Ejemplo:

// valida un EAN con un valor por defecto
'ean; default: 4006381333931'

---

5.5ip, ipv4, ipv6

ip

• Los datos deben ser una dirección IP válida (IPv4 o IPv6).
• Parámetro aceptado: default

Ejemplos:

// valida una dirección IP con un IPv4 por defecto
'ip; default: 127.0.0.1'

// valida una dirección IP con un IPv6 por defecto
[
    'type'    => 'ip',
    'default' => '::1',
]

ipv4

• Los datos deben ser una dirección IPv4 válida.
• Parámetro aceptado: default

Ejemplo:

// valida un IPv4 con un valor por defecto
'ipv4; default: 127.0.0.1'

ipv6

• Los datos deben ser una dirección IPv6 válida.
• Parámetro aceptado: default

Ejemplo:

// valida un IPv6 con un valor por defecto
'ipv6; default: ::1'

---

5.6mac, port

mac

• Los datos deben ser una dirección MAC válida.
• Parámetro aceptado: default

Ejemplo:

// valida una dirección MAC con un valor por defecto
'mac; default: 00:1A:2B:3C:4D:5E'

port

• Modo estricto: los datos deben ser un entero entre 1 y 65.535.
• Modo no estricto: los datos deben poder convertirse en un entero entre 1 y 65.535.
• Parámetros aceptados: default, min, max

Ejemplo:

// valida un puerto privilegiado (por debajo de 1024)
'port; max: 1024'

---

5.7slug, color

slug

• Modo estricto: los datos deben ser una cadena que contenga solo caracteres minúsculos sin acentos (a a z), dígitos y guiones (-).
• Modo no estricto: los datos se convierten usando \Temma\Utils\Text::urlize().
• Parámetro aceptado: default, minLen, maxLen, mask

color

• Los datos deben ser una cadena que contenga un color hexadecimal válido, que puede empezar opcionalmente con una almohadilla (#).
• El valor devuelto siempre empieza con una almohadilla y está en minúsculas.
• Parámetro aceptado: default

---

5.8geo, phone

geo

• Los datos deben ser una coordenada geográfica.
• Parámetro aceptado: default

Ejemplo:

// coordenadas por defecto de París
'geo; default: 48.8566, 2.3522'

phone

Valida números de teléfono que cumplan una de las siguientes condiciones:

• Empezar con 00 seguido de 1 a 15 dígitos.
• Empezar con + seguido de 1 a 15 dígitos.
• Contener de 1 a 15 dígitos.

Notas:

• Modo estricto: al número devuelto se le quitan los espacios, guiones, puntos y paréntesis.
• Modo no estricto: se conservan los espacios, guiones, puntos y paréntesis.
• Parámetro aceptado: default

---

6Tipos complejos

6.1enum

• Enumeración cuyo valor debe ser una de las opciones indicadas.
• Parámetros aceptados: default, values

Ejemplos:

// enumeración con tres valores posibles y un valor por defecto
'enum; values: red, green, blue; default: red'

// equivalente
[
    'type'    => 'enum',
    'values'  => ['red', 'green', 'blue'],
    'default' => 'red',
]

---

6.2list, assoc

list

• Los datos deben ser un array.
• Si se indica un subcontrato, todos los elementos de la lista deben validarlo.
• Parámetros aceptados: default, contract, minLen, maxLen

// lista en la que todos los elementos son enteros
'list; contract: int'

// equivalente
[
    'type'     => 'list',
    'contract' => 'int',
]

// lista de 3 a 5 enteros
'list; contract: int; minLen: 3; maxLen: 5'

assoc

• Los datos deben ser un array asociativo, cuyas claves pueden estar definidas.
• Si las claves están definidas:
  • Modo estricto: se lanza una excepción si se encuentra una clave no definida.
  • Modo no estricto: las claves no definidas se descartan silenciosamente de los datos devueltos.
  • En cualquier caso, si la lista de claves definidas contiene una entrada "...", las claves no definidas se aceptan tal cual.
  • Si la lista de claves definidas contiene una entrada "..." asociada a un contrato, las claves no definidas se validan con ese contrato.
• Parámetros aceptados: default, keys

Ejemplo: array asociativo con las claves 'id' y 'name'

'assoc; keys: id, name'

// equivalente
[
    'type' => 'assoc',
    'keys' => [
        'id',
        'name',
    ]
]

Ejemplo: array asociativo con las claves obligatorias 'id' y 'name', aceptando las demás claves

'assoc; keys: id, name, ...'

// equivalente
[
    'type' => 'assoc',
    'keys' => [
        'id',
        'name',
        '...'
    ]
]

Ejemplo: array asociativo con las claves obligatorias 'id' y 'name', aceptando las demás claves solo si son enteros

[
    'type' => 'assoc',
    'keys' => [
        'id',
        'name',
        '...' => 'int',
    ]
]

Ejemplo: lista cuyos elementos son arrays asociativos con claves definidas:

[
    'type'     => 'list',
    'contract' => 'assoc; keys: id, name',
]

// equivalente
[
    'type'     => 'list',
    'contract' => [
        'type' => 'assoc',
        'keys' => ['id', 'name'],
    ]
]

Ejemplo: array asociativo con la clave 'id' (obligatoria) y la clave 'name' (opcional)

'assoc; keys: id, name?'

// equivalente
[
    'type' => 'assoc',
    'keys' => [
        'id',
        'name?',
    ]
]

// equivalente
[
    'type' => 'assoc',
    'keys' => [
        'id',
        'name' => [
            'mandatory' => false,
        ],
    ]
]

Ejemplo: definiendo el tipo esperado de algunas claves

[
    'type' => 'assoc',
    'keys' => [
        'id'   => 'int',
        'name' => 'string',
        'date',
    ]
]

Ejemplo: array asociativo con claves tipadas, una de ellas opcional

[
    'type' => 'assoc',
    'keys' => [
        'id'   => 'int',
        'name' => [
            'type'      => 'string',
            'mandatory' => false,
        ]
    ]
]

// equivalente
[
    'type' => 'assoc',
    'keys' => [
        'id'    => 'int',
        'name?' => 'string',
    ]
]

Ejemplo : array asociativo con claves tipadas, aceptando otras claves no definidas

[
    'type' => 'assoc',
    'keys' => [
        'id'    => 'int',
        'name?' => 'string',
        '...',
    ]
]

Ejemplo complejo:

[
    'type' => 'assoc',
    'keys' => [
        'id'          => 'int',
        'isCreated'   => 'bool',
        'name'        => 'string; default: abc',
        'color'       => [
            'type'      => 'enum',
            'values'    => ['red', 'green', 'blue'],
            'default'   => 'red',
            'mandatory' => false,
        ],
        'creator'     => [
            'type' => 'assoc',
            'keys' => [
                'id'           => 'int',
                'name',
                'dateCreation',
            ],
        ],
        'children'    => [
            'type'      => 'list',
            'mandatory' => false,
            'contract'  => [
                'type' => 'assoc',
                'keys' => [
                    'id'   => 'int',
                    'name',
                ]
            ],
        ],
        'identifiers' => [
            'type'     => 'list',
            'contract' => 'int',
        ],
    ],
]

---

6.3json

• Los datos deben ser una cadena que contenga JSON válido.
• Si se indica un subcontrato, el contenido JSON debe validarlo.
• Parámetro aceptado: default, contract, minLen, maxLen

Ejemplos:

// valida un flujo JSON (independientemente de su contenido)
'json'

// valida un JSON que contiene una lista de enteros
[
    'type'     => 'json',
    'contract' => 'list; contract: int',
]

// valida un JSON que contiene un array asociativo con claves definidas
[
    'type'     => 'json',
    'contract' => 'assoc; keys: id, name, role',
]

// equivalente al anterior
[
    'type'     => 'json',
    'contract' => [
        'type'    => 'assoc',
        'keys'    => [
            'id',
            'name',
            'role',
        ]
    ]
]