Como aplicar JOLT para transformações JSON

Saiba como o JOLT funciona como uma ferramenta para transformar dados JSON e como utilizá-lo na Digibee Integration Platform.

JOLT (JSON Language for Transform) é uma ferramenta baseada em especificações usada para transformar estruturas de dados JSON. Na Digibee Integration Platform, você pode usar o JOLT em pipelines ou cápsulas por meio do conector Transformer (JOLT) para extrair e manipular dados específicos de payloads JSON.

Como o JOLT funciona

Uma especificação JOLT geralmente consiste em dois elementos principais:

• operation: Define o tipo de transformação a ser aplicada (shift, remove, default e outros).

• spec: Especifica as regras de transformação aplicadas de acordo com a operação selecionada.

As transformações são escritas dentro de um array, permitindo encadear várias operações e aplicá-las em sequência:

[ 
 { 
   "operation": "", 
   "spec": { 
      "client.name": "customer.fullName" 
   } 
 } 
]

Elementos de sintaxe:

• [ ] (colchetes): Usados para definir arrays, como ao encadear múltiplas transformações.

• { } (chaves): Usadas para definir objetos JSON e mapear pares chave-valor dentro da spec.

• . (notação por ponto): Usada para definir caminhos aninhados no JSON de saída. Por exemplo, "client.name": "customer.fullName" mapeia um valor para um campo dentro de customer.

Dica: É possível combinar diferentes operações em uma única transformação, como neste exemplo:

[ 
  {
    "operation": "shift",
    "spec": {
      "client.name": "customer.fullName"
    }
  },
  {
    "operation": "remove",
    "spec": ["client.ssn"]
  }
]

Operações JOLT: Básicas e Avançadas

O JOLT define o tipo de transformação por meio de operações. Aqui estão algumas das mais utilizadas:

• shift: Reestrutura o JSON ou renomeia campos.

• default: Insere valores padrão quando campos estão ausentes.

• remove: Remove campos específicos.

• sort: Organiza os campos em ordem alfabética.

O JOLT também inclui operações avançadas, como:

• modify-default-beta: Define valores padrão sem criar novos campos — preenche apenas os que já existem quando estão vazios ou nulos.

• modify-overwrite-beta: Atualiza valores usando expressões ou cálculos.

• cardinality: Converte entre objetos e arrays.

Guia rápido: Crie sua primeira transformação

Use a operação shift para reestruturar um objeto JSON sem modificar seus valores. Essa operação funciona mapeando campos do JSON de entrada para novos locais no JSON de saída. Você define onde encontrar os valores na estrutura original e onde posicioná-los na nova estrutura.

Caso de uso

Essa transformação reestrutura um registro de cliente para um novo formato esperado por outro sistema. O JSON de entrada contém campos planos dentro de "client", enquanto o JSON de destino organiza os dados em "customer", renomeia alguns campos, aninha as informações de endereço e duplica o número de telefone em dois campos ("phoneNumber" e "mobileNumber").

Passo a passo

1

Adicione o conector

Abra o pipeline e adicione o Transformer (JOLT) V2 logo após o trigger.

2

Configure a transformação

Cole a seguinte spec no formulário de configuração do conector:

[
 {
   "operation": "shift",
   "spec": {
     "client": {
       "name": "customer.fullName",
       "birthDate": "customer.birthDate",
       "address": "customer.address.street",
       "country": "customer.address.country",
       "number": ["customer.phoneNumber", "customer.mobileNumber"]
     }
   }
 }
]

O que cada mapeamento faz:

• "name": "customer.fullName": Move o valor de client.name para customer.fullName.

• "birthDate": "customer.birthDate": Copia a data de nascimento sem alterar o formato.

• "address": "customer.address.street": Transforma o campo plano address em um campo aninhado em customer.address.street.

• "country": "customer.address.country": Aninha o campo country dentro de customer.address.

• "number": ["customer.phoneNumber", "customer.mobileNumber"]: Duplica o valor de number, criando os campos phoneNumber e mobileNumber.

Apenas os campos explicitamente mapeados na spec aparecerão no resultado. Todos os demais dados da entrada serão excluídos.

3

Use este JSON de entrada

Copie e cole no campo Payload no Painel de Execução:

{ 
 "client": { 
   "name": "Sample Client", 
   "email": "[email protected]", 
   "ssn": "123.456.789.10", 
   "birthDate": "02/15/1985", 
   "address": "Sample Client street, 123",
   "country": "United States",
   "number": "8888-8888"
 } 
}

4

Execute o teste

Clique em Executar para executar o teste. O resultado esperado é:

{
 "customer" : {
   "fullName" : "Sample Client",
   "birthDate" : "02/15/1985",
   "address" : {
     "street" : "Sample Client street, 123",
     "country" : "United States"
   },
   "phoneNumber" : "8888-8888",
   "mobileNumber" : "8888-8888"
 }
}

Aprofunde seu conhecimento

Agora que você já conhece os conceitos básicos do JOLT, pode explorar outras operações. Confira nossos artigos sobre como criar transformações básicas em JOLT, usar operadores do JOLT e construir transformações avançadas. Você também pode consultar exemplos reais em Aplicando JOLT em casos de uso práticos para se inspirar.