JSON Validator

1. Visão Geral

O componente JSON Validator (json-validator) valida se o corpo de uma mensagem segue as regras de um JSON Schema definido. Serve para garantir que os dados recebidos em um fluxo tenham o formato esperado antes de seguir para os próximos passos.

Use quando precisar validar a estrutura de um JSON recebido (campos obrigatórios, tipos, formatos) antes de processá-lo. Não use para validações de regra de negócio complexas (isso é papel de um Choice ou de lógica customizada) — o JSON Validator só verifica estrutura/formato.

2. Pré-requisitos

Não há credenciais ou acessos externos — a validação roda localmente na engine de fluxo.

3. Autenticação e Conexão

Não aplicável.

4. Configuração / Operações Suportadas

O componente tem uma única operação: validar o corpo da mensagem contra um schema.

Campo	Obrigatório	Tipo	Descrição	Exemplo
schema	Sim	Texto (JSON Schema)	O schema usado para validar o corpo da mensagem.	Um JSON Schema definindo campos obrigatórios
schemaVersion	Não	Texto: 4, 6, 7, 2019-09 ou 2020-12	Versão do JSON Schema usada para interpretar o schema. Valor padrão: 7. Valores não reconhecidos caem no padrão.	"2020-12"
failOnError	Não	Texto ("true"/"false")	Se true (padrão), uma validação que falha interrompe o fluxo com erro. Se false, o fluxo continua, mas com success: false e os detalhes do erro no corpo.	"false"

O corpo da mensagem de entrada precisa ser um JSON válido — se não for, a validação falha antes mesmo de comparar com o schema.

5. Exemplos Práticos

Exemplo simples: um fluxo recebe um cadastro de cliente e valida se os campos obrigatórios estão presentes, interrompendo o fluxo se algo estiver errado (comportamento padrão, failOnError ligado).

Entrada:

{
  "nome": "Maria Silva",
  "email": "maria@exemplo.com"
}

Configuração do componente:

{
  "componentName": "json-validator",
  "configurations": {
    "schema": "{\"type\":\"object\",\"required\":[\"nome\",\"email\",\"idade\"],\"properties\":{\"idade\":{\"type\":\"number\"}}}"
  }
}

Como o campo idade (obrigatório no schema) não veio na entrada, a validação falha e, como failOnError está no padrão (true), o fluxo é interrompido com um erro contendo os detalhes.

Exemplo avançado: o mesmo cenário, mas sem interromper o fluxo — o resultado da validação é usado para decidir o próximo passo (por exemplo, com um Choice logo em seguida).

Configuração do componente:

{
  "componentName": "json-validator",
  "configurations": {
    "schema": "{\"type\":\"object\",\"required\":[\"nome\",\"email\",\"idade\"],\"properties\":{\"idade\":{\"type\":\"number\"}}}",
    "failOnError": "false"
  }
}

Resposta (quando a validação falha, mas o fluxo continua):

{
  "errors": [
    { "message": "$.idade: is missing but it is required" }
  ]
}

Resposta (quando a validação passa):

{
  "nome": "Maria Silva",
  "email": "maria@exemplo.com",
  "idade": 34
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"Configuration 'schema' is required for json-validator component"	O campo schema não foi preenchido.	Preencher schema com um JSON Schema válido.
"Failed to initialize JSON Schema: ..."	O texto informado em schema não é um JSON Schema válido.	Revisar a sintaxe do schema.
"Error validating JSON: ..."	O corpo da mensagem recebida não é um JSON válido.	Garantir que a mensagem de entrada seja um JSON bem formado.
Mensagens como "$.campo: is missing but it is required"	O corpo não atende a uma regra específica do schema (campo faltando, tipo incorreto, etc).	Ajustar os dados de entrada ou revisar as regras do schema.