Aplicando JOLT a casos de uso práticos

Aprenda como transformar operações JOLT em soluções práticas.

O JOLT é amplamente usado em integrações para reestruturar dados JSON, aplicar regras de negócio e preparar payloads para sistemas downstream. Ele permite transformar informações de forma dinâmica, garantindo que cada pipeline receba os dados exatamente no formato necessário.

Neste guia, você encontrará uma coleção de exemplos práticos e reais que ilustram como o JOLT pode resolver desafios comuns de transformação.

Exemplos práticos

Cada exemplo inclui:

• O JSON de entrada, mostrando a estrutura original dos dados.

• O resultado esperado, apresentando o formato final desejado.

• A especificação JOLT, que você pode copiar e reutilizar nos seus pipelines.

• Uma explicação clara que detalha a lógica da transformação.

Conjuntamente, esses exemplos ajudarão você a ganhar confiança para escrever e adaptar especificações JOLT nos seus cenários de integração.

Separando um nome completo em primeiro nome e sobrenome

Essa transformação extrai os primeiros e últimos elementos de uma string de nome completo e os mapeia para novos campos.

JSON de entrada

{  
    "fullName": "Vitor Aquiles Sordi"
}

JSON de saída desejado

{  
    "name": "Vitor",  
    "lastName": "Sordi"
}

Spec de transformação

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "fullName": "=split(' ',@(1,fullName))",
      "name": "=firstElement(@(1,fullName))",
      "lastName": "=lastElement(@(1,fullName))"
    }
  },
  {
    "operation": "remove",
    "spec": {
      "fullName": ""
    }
  }
]

Explicação

O nome completo é dividido em uma lista usando espaços como separadores. Em seguida, os primeiros e últimos elementos dessa lista são extraídos. O campo original fullName é removido, já que não é mais necessário.

Separando o DDD de um número de telefone

Essa transformação isola os dois primeiros dígitos de um número de telefone (DDD) e extrai o restante como o número telefônico.

JSON de entrada

{  
    "telephone": "11999998888"
}

JSON de saída desejado

{  
    "ddd": "11",  
    "telephone": "999998888"
}

Spec de transformação

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "ddd": "=substring(@(1,telephone),0,2)",
      "sizeTelehone": "=size(@(1,telephone))",
      "telephone": "=substring(@(1,telephone),2,@(1,sizeTelephone))"
    }
  },
  {
    "operation": "remove",
    "spec": {
      "sizeTelephone": ""
    }
  }
]

Explicação

Para esse tipo de transformação, e por conta de como a função substring funciona, podemos definir as posições de início e fim do trecho que queremos extrair de uma string.

No entanto, números de telefone podem variar de tamanho. O campo telephone pode conter:

• Um número fixo

• Um número móvel

• Um valor formatado, como "1199999-8888"

Por causa dessas variações, optamos por usar a função de forma dinâmica.

Como tratamos isso:

1. Primeiro, calculamos o tamanho do valor em telephone.

2. Em seguida, passamos esse tamanho como parâmetro para a função substring.

Essa abordagem evita qualquer dependência do comprimento da string e garante que sempre extraímos o último caractere, independentemente do formato de entrada.

Removendo caracteres especiais de CPF e CNPJ

Essa transformação remove pontuações e caracteres de formatação dos campos CPF e CNPJ.

JSON de entrada

{  
    "cpf": "123.456.789-10",  
    "cnpj": "11.222.333/0001-10"
}

JSON de saída desejado

{  
    "cpf": "12345678910",  
    "cnpj": "11222333000110"
}

Spec de transformação

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "cpf": "=split('[.-]',@(1,cpf))",
      "cnpj": "=split('[./-]',@(1,cnpj))"
    }
  },
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "cpf": "=join('',@(1,cpf))",
      "cnpj": "=join('',@(1,cnpj))"
    }
  }
]

Explicação

Os caracteres [ ] na função split indicam que o parâmetro deve ser interpretado como uma expressão regular. O uso é opcional, mas extremamente útil quando você quer dividir uma string com base em múltiplos caracteres ou padrões.

No exemplo do CPF, usar "[.-]" garante que a divisão ocorra para toda ocorrência de "." ou "-" na string.

Se removêssemos os colchetes — por exemplo: "=split('.-',(@1,cpf))" — o JOLT procuraria a sequência exata ".-", que não aparece no valor do CPF. Como resultado, a divisão não funcionaria. O mesmo princípio se aplica ao exemplo do CNPJ.

Após dividir os valores, usamos a função join para remontar os segmentos em uma única string sem formatação.

Eliminando valores duplicados

Este exemplo mostra como deduplicar itens dentro de uma lista com base em um campo que se repete (id).

JSON de entrada

{
  "products": [
    {
      "id": 1
    },
    {
      "id": 2
    },
    {
      "id": 1
    }
  ]
}

JSON de saída desejado

{
  "products": [
    {
      "id": "1"
    },
    {
      "id": "2"
    }
  ]
}

Spec de transformação

[
  {
    "operation": "shift",
    "spec": {
      "products": {
        "*": {
          "id": {
            "*": "ids.&[]"
          }
        }
      }
    }
  },
  {
    "operation": "shift",
    "spec": {
      "ids": {
        "*": {
          "$": "products[].id"
        }
      }
    }
  }
]

Explicação

Na primeira operação shift, a expressão "*": "ids.&[]" faz duas coisas:

• Primeiro, seleciona todos os valores dos campos id.

• Em seguida, usa cada valor como nome de campo na saída (&), garantindo que cada ID repetido se torne um campo único.

• Por fim, coloca todos esses campos criados dinamicamente em uma nova lista ids.

Na segunda operação shift, a expressão "$": "products[].id" pega o nome de cada campo gerado dentro da lista ids e o utiliza como valor para os novos campos id dentro da lista products.

Somando valores numéricos

Esta transformação calcula a soma total dos valores contidos em uma lista de objetos.

JSON de entrada

{
  "products": [
    {
      "id": 1,
      "name": "Product A",
      "value": 10
    },
    {
      "id": 2,
      "name": "Product B",
      "value": 20
    }
  ]
}

JSON de saída desejado

{
  "products": [
    {
      "id": 1,
      "name": "Product A",
      "value": 10
    },
    {
      "id": 2,
      "name": "Product B",
      "value": 20
    }
  ],
  "totalValue": 30
}

Spec de transformação

[
  {
    "operation": "shift",
    "spec": {
      "products": {
        "*": {
          "*": "products[#2].&",
          "value": ["products[#2].&", "values[]"]
        }
      }
    }
  },
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "totalValue": "=doubleSum(@(1,valores))"
    }
  }
]

Explicação

Usando a operação shift, primeiro criamos uma lista values contendo todos os valores dos arrays products, preservando toda a estrutura de products ao final da transformação.

Em seguida, aplicamos a função doubleSum diretamente à lista values, permitindo que o JOLT some todos os valores de forma dinâmica.

Essa abordagem é especialmente útil ao trabalhar com arrays, já que as funções aritméticas do JOLT permitem processar todos os itens de uma lista de uma só vez.

Para transformações mais simples, você também pode aplicar funções explicitamente, por exemplo:

"=doubleSum(@(1,firstValue),@(1,secondValue))"

Multiplicando dois valores numéricos

Como o JOLT não possui uma função de multiplicação, este exemplo realiza a lógica equivalente usando divisão.

JSON de entrada

{  
    "value1": 10,  
    "value2": 2
}

JSON de saída desejado

{  
    "value1": 10,  
    "value2": 2,  
    "inverseValue": 0.5,  
    "finalValue": 20
}

Spec de transformação

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "inverseValue": "=divide(1, @(1,value2))",
      "finalValue": "=divideAndRound(2, @(1,value1), @(1,inverseValue))"
    }
  }
]

Explicação

Ao usar esta transformação, o objetivo é simular uma multiplicação de forma invertida. Para isso, fazemos o seguinte:

• Primeiro, dividimos um dos valores por 1.

• Em seguida, dividimos o outro valor pelo resultado dessa primeira divisão.

Essa abordagem é necessária porque as funções =divide e =divideAndRound aceitam apenas dois parâmetros, o que significa que não podem processar mais de dois valores diretamente de uma vez.

Aplicando um filtro com base no conteúdo de um campo

Este exemplo filtra os elementos de uma lista ao procurar uma substring dentro do campo email.

JSON de entrada

{
  "clients": [
    {
      "name": "Aquiles",
      "email": "[email protected]"
    },
    {
      "name": "Marcos",
      "email": "[email protected]"
    },
    {
      "name": "Yuri",
      "email": "[email protected]"
    }
  ]
}

JSON de saída desejado

{
  "clients": [
    {
      "name": "Aquiles",
      "email": "[email protected]"
    },
    {
      "name": "Yuri",
      "email": "[email protected]"
    }
  ]
}

Spec de transformação

[
  {
    "operation": "shift",
    "spec": {
      "clients": {
        "*": {
          "email": {
            "*\\@gmail.com": {
              "@2": "gmail[]"
            }
          }
        }
      }
    }
  }
]

Explicação

Em "*\\@gmail.com", filtramos o valor do campo email para retornar apenas os endereços que terminam com "gmail.com".

• O wildcard * captura qualquer conteúdo antes de "@gmail.com".

• A sequência "\@" é necessária porque o símbolo "@" deve ser tratado como um caractere literal, e não como o curinga @ do JOLT.

• No final da expressão, o "\\" é usado para escapar a própria barra invertida, garantindo que seja interpretada corretamente.

Incluindo valores padrão em uma lista

Esta transformação insere um campo padrão em cada elemento de uma lista.

JSON de entrada

{
  "list": [
    { "a": "a", "b": "b" },
    { "c": "c", "d": "d" }
  ]
}

JSON de saída desejado

{
  "list": [
    { "a": "a", "b": "b", "e": "e" },
    { "c": "c", "d": "d", "e": "e" }
  ]
}

Spec de transformação

Opção 1 — default

[
  {
    "operation": "default",
    "spec": {
      "list[]": {
        "*": {
          "e": "e"
        }
      }
    }
  }
]

Opção 2 — modify-default-beta

[
  {
    "operation": "modify-default-beta",
    "spec": {
      "list": {
        "*": {
          "e": "e"
        }
      }
    }
  }
]

Explicação

• default aplica valores quando o campo não existe. Usar list[] garante que a regra seja aplicada a cada entrada do array.

• modify-default-beta se comporta de forma semelhante ao default, mas não requer a notação de array ([]). Quando você especifica "list": { "*": { ... } }, a operação itera automaticamente sobre cada elemento do array.

Adicionando valores aos elementos de uma lista

Adicionando um valor fixo

Esta transformação adiciona o mesmo valor fixo a cada elemento de uma lista.

Você pode escolher como o valor deve se comportar:

• modify-overwrite-beta: Sempre define o valor, mesmo que o campo já exista.

• modify-default-beta: Define o valor apenas se o campo ainda não existir.

JSON de entrada

{
  "happy": "true",
  "statistics": [
    {
      "id": "A",
      "min": "2.0",
      "max": "10.0",
      "avg": "7.9"
    },
    {
      "min": "6",
      "max": "6",
      "avg": "6"
    },
    {
      "id": "C"
    }
  ]
}

JSON de saída desejado

{
  "happy": "true",
  "statistics": [
    {
      "id": "A",
      "min": "2.0",
      "max": "10.0",
      "avg": "7.9",
      "newValue": "test123"
    },
    {
      "min": "6",
      "max": "6",
      "avg": "6",
      "newValue": "test123"
    },
    {
      "id": "C",
      "newValue": "test123"
    }
  ]
}

Spec de transformação

[
  {
    "operation": "modify-overwrite-beta",
    // To add the value only if it does not exist, change the operation to "modify-default-beta"
    "spec": {
      "statistics": {
        "*": {
          "newValue": "test123"
        }
      }
    }
  }
]

Adicionando valores dinâmicos

Neste cenário, cada elemento da lista recebe um valor obtido dinamicamente de outra posição no JSON.

A sintaxe "@(n,path)" significa: suba n níveis a partir da localização atual e, em seguida, siga o caminho para encontrar o valor.

JSON de entrada

{
  "levelA": {
    "levelB": {
      "happy": "true"
    }
  },
  "levelX": {
    "statistics": [
      {
        "id": "A",
        "min": "2.0",
        "max": "10.0",
        "avg": "7.9"
      },
      {
        "min": "6",
        "max": "6",
        "avg": "6"
      },
      {
        "id": "C"
      }
    ]
  }
}

Spec de transformação

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "nivelX": {
        "statistics": {
          // "*" = each list element (also counts as a level)
          "*": {
            "newValue": "@(5,levelA.levelB.happy)"
          }
        }
      }
    }
  }
]

Explicação

• "*" itera sobre cada elemento da lista statistics.

• "@(5,levelA.levelB.happy)" sobe cinco níveis (cada "*" também conta como um nível), alcançando a raiz.

• A partir daí, a transformação lê o valor de levelA.levelB.happy.

• Cada elemento da lista recebe esse valor dinâmico.

Formatando datas usando split e concat

Este exemplo demonstra como reformatar uma data dividindo-a em partes e, em seguida, concatenando os valores na ordem desejada.

A transformação usa split para separar a string em um array e concat para reconstruir a data no formato desejado (AAAAMMDD).

JSON de entrada

{  
  "data": {    
    "DATE": "18/09/1974"  
  }
}

JSON de saída desejado

{  
  "DATE": "19740918"
}

Spec de transformação

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "data": {
        "array_aux": "=split('/',@(1,DATE))",
        "DATE": "=concat(@(1,array_aux[2]),@(1,array_aux[1]),@(1,array_aux[0]))"
      }
    }
  },
  {
    "operation": "shift",
    "spec": {
      "data": {
        "DATE": "&"
      }
    }
  }
]

Explicação

Como a formatação funciona

• Usamos a operação modify-overwrite-beta para atualizar o conteúdo do JSON.

• A função split divide a data original (18/09/1974) em um array: ["18", "09", "1974"], usando o caractere "/" como delimitador.

• Após a divisão, a função concat reorganiza os itens do array para formar a data final: ano + mês + dia → "1974" + "09" + "18".

A função split também pode receber expressões regulares como parâmetros. Para mais exemplos, consulte: Testes de funções split no GitHub.

• No shift final, movemos o campo transformado DATE para a raiz do JSON de saída.

Aplicando lógica simples IF-ELSE

Ao transformar dados entre sistemas, é comum precisar de um campo que não tenha um equivalente direto no JSON de origem. Em muitos casos, é possível derivar esse valor usando uma condição simples IF-ELSE dentro de uma transformação JOLT.

Este exemplo mostra como determinar a cidadania de um cliente com base no seu país.

JSON de entrada

{ 
  "client": {   
    "name": "Sample client",   
    "age": "32",   
    "maritalStatus": "Single",   
    "country": "Brazil" 
  }
}

JSON de saída desejado

{
  "client": {
    "name": "Sample client",
    "citizenship": "Brazilian"
  }
}

Spec de transformação

[
  {
    "operation": "shift",
    "spec": {
      "client": {
        "name": "client.name",
        "country": {
          "Brazil": {
            "#Brazilian": "client.citizenship"
          },
          "*": {
            "#Foreigner": "client.citizenship"
          }
        }
      }
    }
  }
]

Explicação

• O campo "country" é avaliado usando a estrutura de correspondência de padrões do JOLT:

  • Se o valor for "Brazil", o literal Brazilian é atribuído a client.citizenship.

  • Para qualquer outro valor (coringa *), o literal Foreigner é usado.

• O operador # cria um valor constante durante a transformação.

• O resultado é um JSON limpo contendo apenas os campos necessários: name e a cidadania derivada.

Considerações finais

Com os conceitos e exemplos abordados neste guia, você agora tem uma base sólida para criar transformações JOLT poderosas, desde reestruturações simples até manipulações de dados mais avançadas para cenários de integração.

Se quiser continuar aprendendo, oferecemos dois ótimos recursos de suporte:

• Digibee Academy: Transformer JOLT – Fundamentals: Um caminho de aprendizado estruturado onde você pode se aprofundar nas operações e operadores.

• Assistente de IA para Conectores: Seu assistente integrado para criar e ajustar specs JOLT diretamente durante a construção de pipelines.

Essas ferramentas complementam seu conhecimento e tornam ainda mais fácil projetar transformações corretas, eficientes e prontas para produção.