Helper DataFilter

---

1Apresentação

Helper usado para filtrar ou validar dados, a fim de verificar se eles atendem a um contrato. Isso pode ser útil para garantir que os dados recebidos em uma API correspondam ao que é esperado.

---

2Uso

O objeto \Temma\Utils\DataFilter oferece um método estático process(). Esse método recebe como parâmetros os dados a serem filtrados e o contrato a ser aplicado, e retorna os dados filtrados. Se a sintaxe do contrato estiver incorreta, o método lança uma exceção \Temma\Exceptions\IO. Se os dados não atenderem ao contrato, o método lança uma exceção \Temma\Exceptions\Application.

Um terceiro parâmetro opcional permite especificar se a validação deve ser realizada em modo estrito ou não. Por padrão, a validação é não estrita.

Um quarto parâmetro opcional, passado por referência, permite recuperar os dados processados. Para a maioria dos tipos de contrato, esse parâmetro contém os dados filtrados (idêntico ao valor de retorno do método). Para certos tipos, como binary, base64 ou json, esse parâmetro contém dados processados específicos (veja a documentação de cada tipo).

Exemplo 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 à linha 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', "Dados inválidos.");
    throw $ae;
}

// execução em modo estrito
try {
    $data = TµDataFilter::process($data, $contract, true);
} catch (\Exception $e) {
    TµLog::log('myapp', 'WARN', "Erro de validação.");
    throw $e;
}

// recuperando os dados processados por meio do parâmetro $output
try {
    $data = TµDataFilter::process($data, $contract, false, $output);
    // $output contém os dados processados
} catch (\Exception $e) {
    TµLog::log('myapp', 'WARN', "Erro de validação.");
    throw $e;
}

---

3Definição de contratos

3.1Tipo e parâmetro

Os contratos são usados para definir o tipo de dado a ser filtrado ou validado. Eles podem ser escritos como uma string ou como um array associativo.

Um contrato contém, no mínimo, o tipo que os dados devem respeitar.
Exemplos: 'int', 'string'

Um contrato também pode receber parâmetros adicionais.
Os parâmetros podem ser escritos de duas formas diferentes:

• Eles podem ser adicionados à string de configuração do contrato, após a definição do tipo. Os parâmetros são separados por ponto e vírgula (;), e os nomes dos parâmetros são separados de seus valores por dois-pontos (:).

  Exemplo: 'int; default: 3'

• Os contratos também podem ser escritos como um array associativo. O tipo e os parâmetros são representados como pares chave/valor no array. Esse formato é obrigatório ao definir subcontratos.

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

Por fim, quando um contrato espera um array associativo (tipo 'assoc') mas a chave 'type' está ausente, o tipo 'assoc' é inferido automaticamente, e o array que contém o contrato é considerado como o valor do parâmetro 'keys'.

Exemplo: ['name' => 'string']
é equivalente a: ['type' => 'assoc', 'keys' => ['name' => 'string']]

---

3.2Tipos anuláveis

Todos os tipos podem se tornar anuláveis prefixando-os com um ponto de interrogação: '?bool', '?false', '?true'…

---

3.3Tipos múltiplos

É possível usar múltiplos tipos. Por exemplo: 'null|int|string', 'int|float'

---

3.4Validação automática (pass-through)

Se o contrato fornecido for o valor null (e não a string "null"), os dados de entrada são retornados como estão.

---

3.5Modo estrito

Por padrão, o objeto DataFilter opera em modo não estrito: quando necessário, ele realiza conversão de tipo (por exemplo, convertendo uma string contendo dígitos em um inteiro); para alguns parâmetros, ele se comporta de forma permissiva (por exemplo, se um número excede o máximo definido, o máximo é retornado em vez de lançar um erro; se uma string excede o comprimento máximo definido, ela é truncada); chaves não definidas em um array associativo são removidas.

Para executar a filtragem em modo estrito, você deve definir o parâmetro strict como true (veja como usar o objeto DataFilter acima).

Um contrato também pode forçar uma avaliação estrita ou não estrita:

• Para forçar uma avaliação estrita, prefixe o tipo com um sinal de igual (=).
  Exemplos: '=int', '=string'
• Para forçar uma avaliação não estrita, prefixe o tipo com um til (~).
  Exemplos: '~int', '~string'

---

3.6Valor padrão

Usando o parâmetro default, é possível fornecer um valor alternativo, que será usado se os dados de entrada forem inválidos. O valor padrão deve ser do mesmo tipo que está sendo validado.

Exemplos:

'bool; default: false'

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

---

3.7Outros parâmetros

• min: Valor mínimo (para um número, data, hora ou coordenada geográfica).
• max: Valor máximo (para um número, data, hora ou coordenada geográfica).
• minLen: Comprimento mínimo (número de caracteres para uma string ou URL, número de elementos para uma lista).
• maxLen: Comprimento máximo (número de caracteres para uma string ou URL, número de elementos para uma lista).
• mask: Expressão regular (para uma string, endereço de e-mail ou URL).
• format: Formato de entrada e saída para uma data/hora.
• inFormat: Formato de entrada para uma data/hora.
• outFormat: Formato de saída para uma data/hora.
• values: Valores aceitos para uma enumeração, ou tipos aceitos em uma lista.
• contract: Contrato de validação para o conteúdo de uma lista.
• keys: Lista de chaves esperadas em um array associativo.
• mime: Lista de tipos MIME autorizados (em um conteúdo binário ou codificado em base64).
• charset: Conjunto de caracteres. Pode ser uma string simples ('utf-8') ou uma lista ('utf-8, iso-8859-1'). No caso de uma lista, o primeiro conjunto de caracteres é o destino da conversão (em modo não estrito), os seguintes são conjuntos de caracteres alternativos aceitos.
• algo : Algoritmo de hash (veja a função 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 : Dado de origem a ser usado no hash.
• scheme, host, domain, port, user, pass, path, query, fragment : Elementos aceitos em uma URL (veja a função PHP parse_url()). Uma lista de valores pode ser fornecida para cada elemento.
  domain corresponde ao domínio de nível superior encontrado em host (por exemplo, siteweb.com para www.test.siteweb.com).

---

4Tipos escalares

4.1null

• Os dados de entrada devem ser null.
• Nenhum parâmetro aceito.

Exemplos:

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

---

4.2false, true, bool

false

• Modo estrito: os dados devem ser iguais a false.
• Modo não estrito: os dados devem ser iguais a false ou qualquer valor que o PHP converta automaticamente para false (null, 0, string vazia, array vazio).
• Parâmetro aceito: default

Exemplos:

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

// retorna false mesmo que os dados tivessem outro valor
'=false; default: false'

true

• Modo estrito: os dados devem ser iguais a true.
• Modo não estrito: os dados devem ser iguais a true ou qualquer valor que o PHP converta automaticamente para true (número diferente de zero, string não vazia, array não vazio, objeto).
• Parâmetro aceito: default

Exemplos:

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

// valida um valor true, sempre em modo não estrito
'~true'

bool

• Modo estrito: os dados devem ser iguais a true ou false.
• Modo não estrito: os dados são convertidos para booleano.
• Parâmetro aceito: default

Exemplos:

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

// booleano com um valor padrão false
'bool; default: false'
[
    'type'    => 'bool',
    'default' => true,
]

---

4.3int, float

int

• Modo estrito: os dados devem ser um inteiro.
• Modo não estrito: os dados podem ser um booleano (convertido para 0 ou 1), um inteiro, um float (convertido para inteiro), ou uma string contendo dígitos (convertida para inteiro).
• Parâmetros aceitos: default, min, max

Exemplos:

// valida um inteiro
'int'

// valida um inteiro em modo não estrito, com um valor padrão
'~int; default: 3'

// valida um inteiro em modo estrito, maior ou igual a 5
'=int; min: 5'

// inteiro entre 5 e 8, com um valor padrão
'int; min: 5; max: 8; default: 6'

// valida um inteiro
['type' => 'int']

// com um valor mínimo
[
    'type' => 'int',
    'min'  => 5,
]

float

• Modo estrito: os dados devem ser um float.
• Modo não estrito: os dados podem ser um booleano (convertido para 0.0 ou 1.0), um float, um inteiro (convertido para float), ou uma string contendo dígitos (convertida para float).
• Parâmetros aceitos: default, min, max

Exemplos:

// valida um float
'float'

// valida um float em modo não estrito, com um valor mínimo
'~int; min: 2.7'

// valida um float em modo estrito, com um valor máximo
[
    'type' => '=float',
    'max'  => 18.5,
]

---

4.4string

• Modo estrito: os dados devem ser uma string.
• Modo não estrito: os dados podem ser uma string, um booleano (convertido para "true" ou "false"), ou qualquer valor escalar (convertido para string).
• Parâmetros aceitos: default, minLen, maxLen, mask, charset

Exemplos:

// valida uma string, com um valor padrão
'string; default: abc'

// valida uma string com comprimento entre 3 e 12 caracteres
'string; minLen: 3; maxLen: 12'

// valida uma string que corresponde a uma expressão regular
'string; mask: ^[Bb][Oo0]..[Oo0].r$'
// equivalente
[
    'type' => 'string',
    'mask' => '^[Bb][Oo0]..[Oo0].r$',
]

// valida uma string codificada em UTF-8
'string; charset: utf-8'

// valida uma string, e a converte para UTF-8 se necessário (em modo não estrito)
'string; charset: utf-8, iso-8859-1'

---

5Tipos avançados

5.1email, url, uuid, hash

email

• Os dados devem ser um endereço de e-mail válido.
• Parâmetros aceitos: default, minLen, maxLen, mask

Exemplos:

// valida um endereço de e-mail, com um valor padrão
'email; default: contact@domain.com'

// com uma expressão regular
'email; mask: @domain.com$'

// com uma expressão regular e um valor padrão
[
    'type'    => 'email',
    'default' => 'contact@domain.com',
    'mask'    => '@domain.com$',
]

url

• Os dados devem ser uma URL válida.
• Parâmetros aceitos: default, minLen, maxLen, mask, scheme, host, domain, port, user, pass, path, query, fragment

Exemplos:

// valida uma URL
'url'

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

// URL no host "www.foo.com" ou "test.foo.com"
'url; host: www.foo.com, test.foo.com'

// com uma expressão regular
[
    'type' => 'url',
    'mask' => 'https?:..www.domain.com/.$',
]

// URL https no host "foo.com" ou "*.foo.com", na porta 8080,
// com o usuário "bob", e o fragmento "api" ou "json"
'url; scheme: https; domain: foo.com; port: 8080; user: bob; fragment: api, json'

uuid

• Os dados devem ser um UUID válido.
• Parâmetro aceito: default

Exemplo:

// valida um UUID com um valor padrão
'uuid; default: 123e4567-e89b-12d3-a456-426614174003'

hash

• O valor deve ser uma string hexadecimal com o comprimento exigido de acordo com o algoritmo de hash usado (por exemplo, 32 caracteres para MD5, 40 para SHA-1, 64 para SHA2-256, etc.).
• Se o parâmetro source for fornecido, seu hash é calculado e comparado.
• Parâmetros aceitos : default, algo (obrigatório), source

Exemplos :

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

// valida um hash SHA256 ou SHA512
'hash; algo: sha256, sha512'

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

Observe que vários aliases estão disponíveis para simplificar o uso : md5, sha1, sha256, sha512

Exemplos 

// valida um hash MD5
'md5'

// valida um hash SHA256 verificando o valor calculado
'sha256; source: input_data'

---

5.2binary, base64

binary

• Verifica se os dados fornecidos são uma string binária válida.
• O parâmetro mime é opcional, e aceita um ou mais tipos MIME (separados por vírgula). Os tipos podem ser específicos (por exemplo, image/jpeg) ou genéricos (image). Se os dados não corresponderem a nenhum dos tipos listados, uma exceção é lançada.
• Parâmetros aceitos: default, minLen, maxLen, mime, charset

Exemplos:

// valida uma imagem GIF ou PNG
'binary; mime: image/gif, image/png'

// valida imagem ou PDF
'binary; mime: image, application/pdf'

base64

• Os dados devem estar codificados em Base64.
• Modo:
  • não estrito: os dados são decodificados.
  • estrito: os dados são decodificados, depois recodificados, e o resultado é comparado com os dados originais.
• Com o parâmetro mime, é possível especificar um ou vários tipos MIME (separados por vírgula). Se o conteúdo codificado em base64 não corresponder a nenhum dos tipos listados, uma exceção é lançada.
• Parâmetros aceitos: default, minLen, maxLen, mime, charset

Exemplos:

// valida qualquer conteúdo codificado em base64
'base64'

// valida uma imagem GIF ou PNG
'base64; mime: image/gif, image/png'

// valida imagem ou PDF
'base64; mime: image, application/pdf'

---

5.3date, time, datetime

date

• Se os dados forem um inteiro, float, ou string contendo dígitos, eles são interpretados como um timestamp Unix.
• Se os dados forem uma string, eles devem corresponder ao formato de entrada (Y-m-d por padrão).
• Modo:
  • estrito: a data deve ser válida (a data 2026-12-33 é rejeitada).
  • não estrito: a data é convertida (2026-12-33 se torna 2027-01-02).
• Os dados são retornados usando o formato de saída especificado (Y-m-d por padrão).
• Parâmetros aceitos: default, format, inFormat, outFormat, min, max

Exemplos:

// valida uma data com um formato de saída especificado
'date; outFormat: d/m/Y'

// especificando o formato de entrada, com uma data mínima após 1º de janeiro de 2000
'date; inFormat: d/m/Y; min: 01/01/2000'

time

• Se os dados forem um inteiro, float, ou string contendo dígitos, eles são interpretados como um timestamp Unix.
• Se os dados forem uma string, eles devem corresponder ao formato de entrada (H:i:s por padrão).
• Modo:
  • estrito: a hora deve ser válida (a hora 13:65:34 é rejeitada).
  • não estrito: a hora é convertida (13:65:34 se torna 14:05:34).
• Os dados são retornados usando o formato de saída especificado (H:i:s por padrão).
• Parâmetros aceitos: default, format, inFormat, outFormat, min, max

Exemplos:

// valida uma hora com formato de entrada e saída idênticos
'time; format: H:i;'

// valida uma hora entre 15:00 e 17:00
'time; min: 15:00:00; max: 17:00:00'

datetime

• Se os dados forem um inteiro, float, ou string contendo dígitos, eles são interpretados como um timestamp Unix.
• Se os dados forem uma string, eles devem corresponder ao formato de entrada (Y-m-d H:i:s por padrão).
• Modo:
  • estrito: a data/hora deve ser válida (a data/hora 2026-12-33 13:65:34 é rejeitada).
  • não estrito: a data/hora é convertida (2026-12-33 13:65:34 se torna 2027-01-02 14:05:34).
• Os dados são retornados usando o formato de saída especificado (Y-m-d H:i:s por padrão).
• Parâmetros aceitos: default, format, inFormat, outFormat, min, max

Exemplos:

// valida uma data/hora usando um formato de entrada específico
'datetime; inFormat: d/m/Y H:i'

// valida uma data/hora retornada como timestamp, especificando o formato de entrada e o intervalo 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

• Os dados devem ser um ISBN válido.
• Parâmetro aceito: default

Exemplos:

// valida um ISBN com um ISBN-10 padrão
'isbn; default: 0-306-40615-2'
// o mesmo sem hifens
'isbn; default: 0306406152'

// valida um ISBN com um ISBN-13 padrão
'isbn; default: 978-3-16-148410-0'
// o mesmo sem hifens
'isbn; default: 9783161484100'

ean

• Os dados devem ser um código EAN válido.
• Parâmetro aceito: default

Exemplo:

// valida um EAN com um valor padrão
'ean; default: 4006381333931'

---

5.5ip, ipv4, ipv6

ip

• Os dados devem ser um endereço IP válido (IPv4 ou IPv6).
• Parâmetro aceito: default

Exemplos:

// valida um endereço IP com um IPv4 padrão
'ip; default: 127.0.0.1'

// valida um endereço IP com um IPv6 padrão
[
    'type'    => 'ip',
    'default' => '::1',
]

ipv4

• Os dados devem ser um endereço IPv4 válido.
• Parâmetro aceito: default

Exemplo:

// valida um IPv4 com um valor padrão
'ipv4; default: 127.0.0.1'

ipv6

• Os dados devem ser um endereço IPv6 válido.
• Parâmetro aceito: default

Exemplo:

// valida um IPv6 com um valor padrão
'ipv6; default: ::1'

---

5.6mac, port

mac

• Os dados devem ser um endereço MAC válido.
• Parâmetro aceito: default

Exemplo:

// valida um endereço MAC com um valor padrão
'mac; default: 00:1A:2B:3C:4D:5E'

port

• Modo estrito: os dados devem ser um inteiro entre 1 e 65.535.
• Modo não estrito: os dados devem ser convertíveis em um inteiro entre 1 e 65.535.
• Parâmetros aceitos: default, min, max

Exemplo:

// valida uma porta privilegiada (abaixo de 1024)
'port; max: 1024'

---

5.7slug, color

slug

• Modo estrito: os dados devem ser uma string contendo apenas caracteres minúsculos sem acento (a a z), dígitos e hifens (-).
• Modo não estrito: os dados são convertidos usando \Temma\Utils\Text::urlize().
• Parâmetros aceitos: default, minLen, maxLen, mask

color

• Os dados devem ser uma string contendo uma cor hexadecimal válida, opcionalmente iniciando com uma cerquilha (#).
• O valor retornado sempre começa com uma cerquilha e está em minúsculas.
• Parâmetro aceito: default

---

5.8geo, phone

geo

• Os dados devem ser uma coordenada geográfica.
• Parâmetro aceito: default

Exemplo:

// coordenadas padrão de Paris
'geo; default: 48.8566, 2.3522'

phone

Valida números de telefone que atendam a uma das seguintes condições:

• Começar com 00 seguido de 1 a 15 dígitos.
• Começar com + seguido de 1 a 15 dígitos.
• Conter de 1 a 15 dígitos.

Observações:

• Modo estrito: o número retornado tem espaços, hifens, pontos e parênteses removidos.
• Modo não estrito: espaços, hifens, pontos e parênteses são preservados.
• Parâmetro aceito: default

---

6Tipos complexos

6.1enum

• Enumeração cujo valor deve ser uma das opções listadas.
• Parâmetros aceitos: default, values

Exemplos:

// enumeração com três valores possíveis e um valor padrão
'enum; values: red, green, blue; default: red'

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

---

6.2list, assoc

list

• Os dados devem ser um array.
• Se um subcontrato for fornecido, todos os elementos da lista devem validá-lo.
• Parâmetros aceitos: default, contract, minLen, maxLen

// lista em que todos os elementos são inteiros
'list; contract: int'

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

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

assoc

• Os dados devem ser um array associativo, cujas chaves podem ser definidas.
• Se as chaves forem definidas:
  • Modo estrito: uma exceção é lançada se uma chave não definida for encontrada.
  • Modo não estrito: chaves não definidas são silenciosamente descartadas dos dados retornados.
  • Em qualquer caso, se a lista de chaves definidas contiver uma entrada "...", as chaves não definidas são aceitas como estão.
  • Se a lista de chaves definidas contiver uma entrada "..." associada a um contrato, as chaves não definidas são validadas com esse contrato.
• Parâmetros aceitos: default, keys

Exemplo: array associativo com as chaves 'id' e 'name'

'assoc; keys: id, name'

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

Exemplo: array associativo com as chaves obrigatórias 'id' e 'name', sendo as demais chaves aceitas

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

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

Exemplo: array associativo com as chaves obrigatórias 'id' e 'name', sendo as demais chaves aceitas somente se forem inteiros

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

Exemplo: lista cujos elementos são arrays associativos com chaves definidas:

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

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

Exemplo: array associativo com a chave 'id' (obrigatória) e a chave 'name' (opcional)

'assoc; keys: id, name?'

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

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

Exemplo: definindo o tipo esperado de algumas chaves

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

Exemplo: array associativo com chaves tipadas, uma delas opcional

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

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

Exemplo : array associativo com chaves tipadas, aceitando outras chaves não definidas

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

Exemplo complexo:

[
    '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

• Os dados devem ser uma string contendo JSON válido.
• Se um subcontrato for fornecido, o conteúdo JSON deve validá-lo.
• Parâmetros aceitos: default, contract, minLen, maxLen

Exemplos:

// valida um fluxo JSON (independentemente do seu conteúdo)
'json'

// valida um JSON que contém uma lista de inteiros
[
    'type'     => 'json',
    'contract' => 'list; contract: int',
]

// valida um JSON que contém um array associativo com chaves definidas
[
    'type'     => 'json',
    'contract' => 'assoc; keys: id, name, role',
]

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