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


---

# 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.md?ask=<question>
```

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.