Referência do modelo de dados

Configurações de atributo

Todos os campos que uma definição de atributo aceita. Alterável responde à pergunta mais cara de errar — se você ainda pode mudar isto depois que já existem registros.

Campo	Aceita	Padrão	Alterável	O que faz
entityTypeId	O identificador do tipo de entidade	—	Não	O tipo ao qual este atributo pertence. Mover um atributo entre tipos não é uma edição; é um atributo novo.
name	1–100 caracteres: letras, dígitos e sublinhado; deve começar por letra	—	Não	O identificador usado por regras de correspondência, regras de validação e pela API. Imutável porque toda regra que o nomeia quebraria silenciosamente.
slug	1–100 caracteres: minúsculas, dígitos e hífen	Derivado do nome	Não	Identificador seguro para URLs.
displayName	1–255 caracteres	—	Sim	O rótulo legível exibido no console. Pode mudar a qualquer momento.
description	Até 2.000 caracteres	—	Sim	Orientação para quem for preencher o campo.
dataType	Um dos 12 tipos abaixo	—	Sim	O formato do valor. Veja a nota sobre promoção adiante.
subFields	De 1 a 40 sub-campos	—	Não	As partes nomeadas de um composto. Obrigatório quando o tipo é composto, e fixo depois de criado.
rdmLookupTypeId	Um tipo de lookup	—	Sim	Restringe os valores aos códigos daquela lista. Obrigatório quando o tipo é lookup.
rdmHierarchyId	Uma hierarquia	—	Sim	Vincula os valores a um nível de uma hierarquia nivelada. Anda junto com o nível abaixo.
rdmHierarchyLevelOrder	Inteiro, 1 ou maior	—	Sim	Em qual nível daquela hierarquia o valor se situa.
valueTypeLookupId	Um tipo de lookup	—	Sim	Fornece os tipos de uso por valor (residencial, comercial, celular). Diferente de rdmLookupTypeId: aquele restringe o valor, este restringe o tipo de uso associado a cada valor.
isRequired	verdadeiro ou falso	false	Sim	Um atributo obrigatório bloqueia a criação do registro quando ausente.
isUnique	verdadeiro ou falso	false	Sim	Dois registros do mesmo tipo não podem compartilhar um valor.
isSearchable	verdadeiro ou falso	true	Sim	Apenas intenção registrada — veja a nota adiante.
isPii	verdadeiro ou falso	false	Sim	Apenas intenção registrada — veja a nota adiante.
defaultValue	Qualquer valor do tipo declarado	—	Sim	Aplicado quando um registro chega sem valor.
displayOrder	Inteiro, 0 ou maior	0	Sim	Ordenação dentro do seu grupo em telas e formulários de entidade.
attributeGroup	1–100 caracteres, texto livre	—	Sim	A seção nomeada em que o atributo aparece. Texto livre em vez de lista fixa, para que os grupos surjam conforme cada tenant.
maxCardinality	Inteiro, 0 ou maior	1	Sim	Quantos valores um registro pode guardar. Veja o aviso adiante.
metadata	Objeto arbitrário	{}	Sim	Suas próprias anotações. A plataforma armazena e devolve sem interpretar.

Tipos de dado

string · number · integer · decimal · boolean · date · datetime · email · phone · json · lookup · composite

Um tipo pode ser promovido no lugar

dataType é editável, o que não é o que a maioria dos sistemas de esquema permite. O uso pretendido é a promoção: um atributo que começou como string de texto livre pode virar um lookup vinculado a uma lista controlada assim que você tiver os dados de referência — um código de diagnóstico saindo de texto digitado para uma terminologia clínica vinculada, por exemplo.

As regras de vínculo são reavaliadas contra o estado resultante, então uma promoção que deixaria o atributo inconsistente é recusada naquele momento.

Reduzir maxCardinality não remove valores existentes

O limite é aplicado quando um valor é gravado, não retroativamente. Reduza de 3 para 1 e os registros que já guardam três valores mantêm os três; apenas as gravações seguintes são rejeitadas.

Ou seja, reduzir não é uma limpeza. Se você precisa que os valores extras desapareçam, remova-os deliberadamente — caso contrário o modelo afirma ser de valor único enquanto os dados não são.

isSearchable e isPii ainda não mudam comportamento

Os dois sinalizadores são armazenados na definição e devolvidos pela API, e nenhum dos dois é levado em conta.

• Desligar isSearchable não remove o atributo da busca por atributo. A busca resolve atributos pelo nome; ela nunca consulta esse sinalizador.
• Marcar isPii não mascara, oculta nem restringe nada. O mascaramento é regido inteiramente por regras de mascaramento, configuradas à parte, que não leem esse sinalizador.

Use-os para registrar intenção e trate-os como documentação para sua própria equipe. Não dependa de nenhum dos dois como controle. Se precisa ocultar um atributo, escreva uma regra de mascaramento; se precisa tirá-lo da busca, hoje não é possível excluí-lo.

Atributos compostos

Um composto guarda sub-campos nomeados em vez de um escalar. A comparação pode mirar um sub-campo com notação pontuada.

Cada sub-campo aceita:

Campo	Aceita	Padrão	O que faz
name	1–100 caracteres, camelCase, começando por letra	—	O identificador usado em caminhos pontuados, como address.postalCode.
displayName	1–255 caracteres	—	O rótulo exibido para esta parte.
dataType	Um dos dez tipos escalares	—	O formato da parte.
isRequired	verdadeiro ou falso	false	Se esta parte precisa estar presente.
maxLength	1 a 10.000	—	Limite de comprimento para partes textuais.
format	Até 100 caracteres	—	Uma dica de formato para esta parte.
rdmLookupTypeId	Um tipo de lookup	—	Restringe esta parte a uma lista controlada — uma parte de país vinculada à ISO 3166, por exemplo.

Um composto pode ter de 1 a 40 sub-campos.

Compostos não se aninham

O tipo de um sub-campo vem apenas dos dez tipos escalares — json e composite ficam de fora. Um endereço pode conter um CEP, mas não pode conter outro composto. Um único nível, deliberadamente: compostos aninhados não têm caminho pontuado sensato nem comparador que consiga pontuá-los.

Regra	Comportamento
Um sub-campo que não existe	Rejeitado ao salvar o perfil
Um comparador escalar num composto inteiro	Rejeitado — dois compostos diferentes se comparariam como iguais
Um comparador ciente de composto num composto inteiro	Permitido
Um valor não estruturado gravado num atributo composto	Rejeitado, tanto na API quanto no banco de dados

A rejeição de comparadores escalares em compostos inteiros não é uma verificação de conveniência. Sem ela, dois endereços completamente sem relação se comparam como iguais e o tipo de entidade consolida de forma catastrófica.

Atributos multivalorados

Comportamento	Detalhe
Armazenamento	Vários valores por atributo, cada um opcionalmente com um tipo de uso
Preferencial	No máximo um valor preferencial por tipo de uso no registro dourado
Comparação	Valores são enumerados; o melhor pareamento é assumido
Blocagem	Cada valor emite sua própria chave
Sobrevivência	Agrupada por tipo de uso; cada um resolve independentemente

Tipos de relacionamento

Configuração	Finalidade
Tipos de entidade de origem e destino	O que o relacionamento liga
Cardinalidade	Quantos vínculos são permitidos por ponta
Nome de exibição e nome inverso	Para que o vínculo se leia corretamente de qualquer ponta
Simétrico	Se a direção é significativa
Acíclico	Se ciclos são rejeitados

Acíclico importa para hierarquias: sem isso, uma cadeia de propriedade pode fechar num laço que nenhuma agregação resolve.

Validação do modelo

Configuração referenciada precisa existir e estar ativa ao salvar. Um perfil que nomeia um atributo inexistente, ou uma regra que nomeia um tipo de lookup aposentado, é rejeitado naquele momento em vez de falhar silenciosamente depois.

Este é o contrato geral: configuração que não poderia funcionar é recusada enquanto você ainda está olhando para ela.

A seguir

• Defina um tipo de entidade
• Gerencie dados de referência

---

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