Criando transformações básicas com JOLT

Aprenda como cada transformação básica do JOLT (shift, default, remove e sort) funciona.

O JOLT pode ser usado para diversos tipos de transformações, desde as mais simples até as mais avançadas. Neste documento, apresentamos as operações básicas, que permitem:

• Reestruturar o JSON ou renomear campos.

• Inserir valores padrão quando campos estiverem ausentes.

• Remover campos específicos.

• Organizar campos em ordem alfabética.

Dica: Teste os exemplos deste documento no playground do JOLT.

Entendendo as operações básicas do JOLT

Nesta seção, você aprenderá como cada operação básica do JOLT funciona (shift, default, remove e sort) e quando utilizá-las.

shift

A operação shift reestrutura um objeto JSON ao remapear seus campos, sem modificar seus valores. Ela funciona definindo de onde extrair os valores no JSON original e para onde colocá-los na nova estrutura.

Exemplo prático

• Caso de uso: Transformar um catálogo de produtos para atender a um novo formato.

• Objetivo: Agrupar detalhes do produto dentro de um objeto details e renomear campos.

JSON de entrada

{
  "product": {
    "id": "12345",
    "name": "Smartphone X1",
    "brand": "TechBrand",
    "price": 699.99,
    "currency": "USD",
    "stock": 25
  }
}

JSON de saída desejado

{
  "productId": "12345",
  "details": {
    "name": "Smartphone X1",
    "brand": "TechBrand",
    "pricing": {
      "amount": 699.99,
      "currency": "USD"
    },
    "availability": 25
  }
}

Spec de transformação

[
  {
    "operation": "shift",
    "spec": {
      "product": {
        "id": "productId",
        "name": "details.name",
        "brand": "details.brand",
        "price": "details.pricing.amount",
        "currency": "details.pricing.currency",
        "stock": "details.availability"
      }
    }
  }
]

Explicação

• "id": "productId" move product.id para o nível superior com um novo nome.

• "name" e "brand" são agrupados dentro de details.

• "price" e "currency" são aninhados em details.pricing para organizar informações de preço.

• "stock" é renomeado para availability e agrupado em details.

Usando a notação por ponto (.) e caminhos hierárquicos no spec, você pode organizar estruturas complexas com pouco esforço.

Somente os campos explicitamente mapeados na spec de transformação aparecerão na saída. Qualquer outro dado da entrada será ignorado.

default

A operação default adiciona campos a um objeto JSON quando eles não existem. É útil para preencher dados ausentes com valores pré-definidos.

Exemplo prático

• Caso de uso: Completar dados de cliente com uma data de nascimento padrão.

• Objetivo: Garantir que o JSON de saída inclua o campo birthDate, mesmo quando ele estiver ausente no input.

JSON de entrada

{
 "customer": {
   "name": "Customer Default",
   "ssn": "123-45-6789"
 }
}

JSON de saída desejado

{
 "customer": {
   "name": "Customer Default",
   "ssn": "123-45-6789",
   "birthDate": "01/01/1970"
 }
}

Spec de transformação

[    
 {
   "operation": "default",
   "spec": {
     "customer": {
       "birthDate": "01/01/1970"
     }
   }
 }
]

Explicação

• A operação verifica se customer.birthDate existe.

• Se não existir, "01/01/1970" é adicionado como valor padrão.

• Se já existir, o valor original é mantido.

Essa operação é útil para garantir que campos essenciais sempre estejam presentes no output, mesmo quando não são fornecidos no input..

A operação default não sobrescreve valores existentes, ela apenas preenche os ausentes.

remove

A operação remove exclui campos ou objetos específicos de uma estrutura JSON. Para isso, é necessário navegar até o campo desejado e atribuir a ele uma string vazia ("") no spec.

Exemplo prático

• Caso de uso: Limpar dados de cliente removendo campos desnecessários.

• Objetivo: Remover o campo birthDate do objeto customer.

JSON de entrada

{
 "customer": {
   "name": "Customer Default",
   "ssn": "123.456.789.10",
   "birthDate": "01/01/1970"
 }
}

JSON de saída desejado

{
 "customer": {
   "name": "Customer Default",
   "ssn": "123.456.789.10"
 }
}

Spec de transformação

[
 {
   "operation": "remove",
   "spec": {
     "customer": {
       "birthDate": ""
     }
   }
 }
]

Explicação

• A transformação navega até customer.birthDate e a remove ao atribuir "".

• Apenas os campos explicitamente definidos como string vazia serão removidos.

• Qualquer valor diferente de vazio fará a operação falhar.

Certifique-se de usar "" para indicar que o campo deve ser removido. Isso é necessário para que a operação funcione.

sort

A operação sort organiza todos os campos e objetos de um JSON em ordem alfabética, pelo nome da chave. Ela se aplica globalmente. A ordenação não pode ser personalizada e somente as chaves são ordenadas, não os valores.

Exemplo prático

• Caso de uso: Colocar campos de dados de funcionários em ordem alfabética para manter consistência.

• Objetivo: Garantir que todos os campos no JSON de saída apareçam em ordem alfabética.

JSON de entrada

{
 "employee": {
   "phone": "9 9999-9999",
   "name": "Employee Sort",
   "birthDate": "01/01/1980",
   "role": "JOLT Analyst"
 }
}

JSON de saída desejado

{
 "employee": {
   "birthDate": "01/01/1980",
   "name": "Employee Sort",
   "phone": "9 9999-9999",
   "role": "JOLT Analyst"
 }
}

Spec de transformação

[
 {
   "operation": "sort"
 }
]

Explicação

• A operação sort não precisa de spec. Basta declarar a operação.

• Todos os campos do JSON são ordenados alfabeticamente pelo nome da chave.

• A ordenação se aplica recursivamente, ou seja, também aos objetos internos.

Continue aprendendo

Agora que você já conhece os conceitos essenciais, pode avançar para os próximos tópicos:

• Operadores JOLT, elementos que deixam suas especificações mais dinâmicas e flexíveis.

• Operações avançadas, onde você explora técnicas de transformação mais sofisticadas.

• Exemplos de uso, que demonstram o funcionamento do JOLT em cenários reais de integração.