Referência de dados de referência

Tipo de lookup

Campo	Aceita	Padrão	Alterável	O que faz
name	1–255 caracteres	—	Não	Identifica a lista onde quer que a configuração se refira a ela.
displayName	1–255 caracteres	—	Sim	O que as pessoas leem no console.
description	Até 2.000 caracteres	—	Sim	Texto livre.
isHierarchical	verdadeiro ou falso	false	Sim	Se os valores podem referenciar um valor pai, formando uma árvore.
lifecycleState	draft, active, retired	active	Sim	Em que ponto da vida a lista está. Uma lista em rascunho pode ser montada antes que algo se vincule a ela; uma aposentada deixa de ser oferecida.
versionLabel	1–32 caracteres	v1	Não	Qual versão publicada da lista é esta.
metadata	Um objeto	{}	Sim	Suas próprias anotações, armazenadas e devolvidas sem interpretação.

Uma lista nova nasce ativa salvo indicação contrária. Se você está montando um vocabulário e não quer que ele seja vinculado a atributos no meio da construção, crie-a como draft e promova-a quando os valores estiverem no lugar.

Valor de lookup

Campo	Aceita	Padrão	Alterável	O que faz
lookupTypeId	Um tipo de lookup	—	Não	A qual lista o valor pertence. Um valor não pode mudar de lista.
code	1–100 caracteres	—	Não	O que fica armazenado nos registros. Veja o aviso adiante.
label	1–500 caracteres	—	Sim	Texto de exibição. Livremente alterável — o código é o que os registros guardam, então renomear um rótulo não reescreve nada.
parentValueId	Outro valor, ou vazio	—	Sim	O pai numa lista hierárquica. Vazio significa raiz, e limpá-lo devolve o valor à raiz.
sortOrder	Inteiro, 0 ou maior	0	Sim	Ordem de apresentação dentro do seu nível.
isActive	verdadeiro ou falso	true	Sim	Se o valor é oferecido para dados novos. Valores aposentados continuam resolvendo em registros existentes.
effectiveFrom	Um instante	—	Sim	Quando o valor passa a ser válido.
effectiveTo	Um instante	—	Sim	Quando deixa de ser válido.
metadata	Um objeto	{}	Sim	Suas próprias anotações, armazenadas e devolvidas sem interpretação.

Rótulos em outros idiomas não são um campo do valor — são um recurso filho separado, de modo que um valor carrega um rótulo por idioma sem que o próprio valor mude.

O código é permanente

code é o que todo registro armazena. Ele não pode ser editado, e a restrição é estrutural, não cautelosa: os rótulos são resolvidos procurando o código armazenado na sua lista, então um código alterado deixaria todo registro existente apontando para um valor que não existe mais — exibindo um código cru onde deveria haver um nome, em dados que estavam corretos quando foram gravados.

Se um código está genuinamente errado, adicione o valor correto e migre os registros para ele. Acerte os códigos no início; trate-os como permanentes a partir do momento em que o primeiro registro usa um.

Um código aposentado ainda renderiza

A resolução de rótulo deliberadamente ignora o sinalizador de ativo e a janela de vigência. Um código aposentado num registro histórico ainda precisa exibir seu rótulo — a alternativa é um registro que silenciosamente perde significado porque um vocabulário seguiu em frente.

Transcodificação

Configuração	Notas
Tipo de lookup	Qual lista o mapeamento mira
Sistema de origem	De quem são os códigos sendo mapeados
Valor de origem	O código que chega
Valor canônico	O valor no qual ele se torna

Mapeamentos são por sistema de origem, então dois sistemas podem mapear códigos diferentes para o mesmo valor canônico sem ambiguidade.

Um mapeamento como o pacote bancário distribuído o declara:

{ "lookupType":     "account_types",
  "sourceSystem":   "core_banking",
  "sourceValue":    "CHK",
  "canonicalCode":  "checking" }

O sistema central chama de CHK. A lista canônica chama de checking. Nenhum sistema precisa mudar, e nada a jusante — comparação, busca, relatórios — jamais vê CHK.

O escopo por sistema de origem é o que torna isso seguro. CHK do sistema central e CHECKING de uma processadora de cartões resolvem ambos para checking, enquanto a mesma string vinda de dois sistemas pode legitimamente significar coisas diferentes e ainda ser mapeada corretamente.

A transcodificação vale em gravações de registro único, não em massa

O mapeamento é consultado quando um registro é criado ou alterado individualmente e quem chama identificou seu sistema de origem. Uma carga em massa resolve códigos de forma estrita e direta, então traduza os valores antes de submetê-los em volume — um código não mapeado ali faz a carga falhar em vez de ser convertido silenciosamente.

Hierarquias

Conceito	Notas
Hierarquia	Uma estrutura nivelada nomeada
Nível	Um patamar ordenado dentro dela
Nó	Uma posição, referenciando um valor de lookup
Agregação	Consolidação de um nível para cima

Dois conceitos distintos compartilham a palavra "hierarquia" e vale mantê-los separados:

	O que é	Usado para
Árvore de valores	Um valor referenciando um valor pai	Restringir valores permitidos
Hierarquia nivelada	Uma estrutura nomeada com níveis ordenados	Classificação e agregação

Proteção contra exclusão

Um valor de lookup em uso não pode ser excluído. A plataforma reporta quais registros o referenciam em vez de cascatear, porque cascatear aqui reescreveria silenciosamente dados governados.

A seguir

• Gerencie tipos e valores de lookup

---

Última verificação no commit d3c2586b (2026-08-03)