# Como aplicar JOLT para transformações JSON

**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)**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/jolt-v2) 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:

```json
[ 
 { 
   "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`.

{% hint style="success" %}
**Dica:** É possível combinar diferentes operações em uma única transformação, como neste exemplo:

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

{% endhint %}

## **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**

{% stepper %}
{% step %}

#### **Adicione o conector**

Abra o pipeline e adicione o [**Transformer (JOLT) V2**](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/connectors/tools/jolt-v2) logo após o trigger.
{% endstep %}

{% step %}

#### **Configure a transformação**

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

```json
[
 {
   "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`.

{% hint style="info" %}
Apenas os campos explicitamente mapeados na spec aparecerão no resultado. Todos os demais dados da entrada serão excluídos.
{% endhint %}
{% endstep %}

{% step %}

#### **Use este JSON de entrada**

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

```json
{ 
 "client": { 
   "name": "Sample Client", 
   "email": "sample-client@email.com", 
   "ssn": "123.456.789.10", 
   "birthDate": "02/15/1985", 
   "address": "Sample Client street, 123",
   "country": "United States",
   "number": "8888-8888"
 } 
}
```

{% endstep %}

{% step %}

#### **Execute o teste**

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

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

{% endstep %}
{% endstepper %}

## **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**](https://docs.digibee.com/documentation/resources/pt-br/use-cases/how-to-jolt/basic-operations), usar [**operadores do JOLT**](https://docs.digibee.com/documentation/resources/pt-br/use-cases/how-to-jolt/operators) e construir [**transformações avançadas**](https://docs.digibee.com/documentation/resources/pt-br/use-cases/how-to-jolt/advanced-operations). Você também pode consultar exemplos reais em [**Aplicando JOLT em casos de uso práticos**](https://docs.digibee.com/documentation/resources/pt-br/use-cases/how-to-jolt/use-cases) para se inspirar.