# Aplicando JOLT a casos de uso práticos 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** ```json { "fullName": "Vitor Aquiles Sordi" } ``` **JSON de saída desejado** ```json { "name": "Vitor", "lastName": "Sordi" } ``` **Spec de transformação** ```json [ { "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** ```json { "telephone": "11999998888" } ``` **JSON de saída desejado** ``` { "ddd": "11", "telephone": "999998888" } ``` **Spec de transformação** ```json [ { "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** ```json { "cpf": "123.456.789-10", "cnpj": "11.222.333/0001-10" } ``` **JSON de saída desejado** ```json { "cpf": "12345678910", "cnpj": "11222333000110" } ``` **Spec de transformação** ```json [ { "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** ```json { "products": [ { "id": 1 }, { "id": 2 }, { "id": 1 } ] } ``` **JSON de saída desejado** ```json { "products": [ { "id": "1" }, { "id": "2" } ] } ``` **Spec de transformação** ```json [ { "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** ```json { "products": [ { "id": 1, "name": "Product A", "value": 10 }, { "id": 2, "name": "Product B", "value": 20 } ] } ``` **JSON de saída desejado** ```json { "products": [ { "id": 1, "name": "Product A", "value": 10 }, { "id": 2, "name": "Product B", "value": 20 } ], "totalValue": 30 } ``` **Spec de transformação** ```json [ { "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** ```json { "value1": 10, "value2": 2 } ``` **JSON de saída desejado** ```json { "value1": 10, "value2": 2, "inverseValue": 0.5, "finalValue": 20 } ``` **Spec de transformação** ```json [ { "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** ```json { "clients": [ { "name": "Aquiles", "email": "aquiles@gmail.com" }, { "name": "Marcos", "email": "marcos@outlook.com" }, { "name": "Yuri", "email": "yuri@gmail.com" } ] } ``` **JSON de saída desejado** ```json { "clients": [ { "name": "Aquiles", "email": "aquiles@gmail.com" }, { "name": "Yuri", "email": "yuri@gmail.com" } ] } ``` **Spec de transformação** ```json [ { "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** ```json { "list": [ { "a": "a", "b": "b" }, { "c": "c", "d": "d" } ] } ``` **JSON de saída desejado** ```json { "list": [ { "a": "a", "b": "b", "e": "e" }, { "c": "c", "d": "d", "e": "e" } ] } ``` **Spec de transformação** **Opção 1 — default** ```json [ { "operation": "default", "spec": { "list[]": { "*": { "e": "e" } } } } ] ``` **Opção 2 — modify-default-beta** ```json [ { "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** ```json { "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** ```json { "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** ```json [ { "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** ```json { "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** ```json [ { "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** ```json { "data": { "DATE": "18/09/1974" } } ``` **JSON de saída desejado** ```json { "DATE": "19740918" } ``` **Spec de transformação** ```json [ { "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"`. {% hint style="info" %} 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](https://github.com/bazaarvoice/jolt/blob/7812399d1c955742d81eae363244a2d0ef86cf3b/jolt-core/src/test/resources/json/modifier/functions/stringsSplitTest.json). {% endhint %} * 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** ```json { "client": { "name": "Sample client", "age": "32", "maritalStatus": "Single", "country": "Brazil" } } ``` **JSON de saída desejado** ```json { "client": { "name": "Sample client", "citizenship": "Brazilian" } } ``` **Spec de transformação** ```json [ { "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**](https://digibee.academy/courses/transformer-jolt/): Um caminho de aprendizado estruturado onde você pode se aprofundar nas operações e operadores. * [**Assistente de IA para Conectores**](/documentation/developer-guide/pt-br/development-cycle/build-overview/canvas/connector-ai-assistant.md): 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digibee.com/documentation/resources/pt-br/use-cases/how-to-jolt/use-cases.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.