Propriedades

Visão Geral

As propriedades definem as colunas na sua tabela de banco de dados e como elas são renderizadas na UI de administração. Cada propriedade tem um type que determina:

• O tipo de coluna do banco de dados (via geração de esquema Drizzle)
• O componente de campo de formulário
• O renderizador de célula de tabela
• As regras de validação

Tipos de Propriedade

Tipo	Descrição	Coluna PostgreSQL
string	Texto, seleção, markdown, upload de arquivo, URL, e-mail	varchar, text, jsonb
number	Inteiro, decimal, moeda	integer, numeric, bigint, serial
boolean	Alternador verdadeiro/falso	boolean
date	Data, data/hora, timestamp	timestamp, date
array	Lista ordenada de valores	jsonb
map	Objeto chave-valor	jsonb
geopoint	Par latitude/longitude	jsonb
reference	Referência incorporada a outra entidade	varchar (armazena ID)
relation	Relação de chave estrangeira SQL	Usa o array relations

Propriedades Comuns

Todos os tipos de propriedades compartilham estas opções:

Propriedade	Tipo	Descrição
type	string	Obrigatório. Tipo de dado (veja acima)
name	string	Obrigatório. Rótulo de exibição
description	string	Texto de ajuda exibido abaixo do campo
defaultValue	any	Valor padrão para novas entidades
validation	object	Regras de validação
propertyConfig	string	Chave de configuração de propriedade registrada
columnName	string	Nome explícito da coluna do banco de dados (ignora conversão para snake_case)
callbacks	PropertyCallbacks	Hooks para transformações afterRead e beforeSave
dynamicProps	function	Construtor de propriedades dinâmicas (ver Campos Condicionais)
conditions	PropertyConditions	Condições declarativas com JSON Logic

Configuração de UI (admin)

As opções relacionadas à UI são aninhadas sob o sub-objeto admin:

price: {
    type: "number",
    name: "Price",
    admin: {
        readOnly: true,
        columnWidth: 120,
        hideFromCollection: false
    }
}

Propriedade	Tipo	Descrição
admin.readOnly	boolean	Impedir edição
admin.disabled	boolean | PropertyDisabledConfig	Desabilitar com tooltip opcional
admin.hideFromCollection	boolean	Ocultar da visualização de tabela
admin.columnWidth	number	Largura da coluna em pixels (visualização de tabela)
admin.span	1 | 2 | 3 | 4	Largura do campo na grelha de formulário de quatro colunas
admin.Field	React.ComponentType	Componente de campo personalizado
admin.Preview	React.ComponentType	Componente de célula de tabela personalizado

Propriedades de String

O tipo string é o mais versátil — dependendo das opções que você configurar, ele é renderizado como diferentes widgets.

Campo de texto

Um campo de texto básico de uma única linha.

name: {
    type: "string",
    name: "Name",
    validation: { required: true, min: 2, max: 200 }
}

Texto multilinha

Configure multiline: true para renderizar como um textarea.

description: {
    type: "string",
    name: "Description",
    multiline: true
}

Editor Markdown

Configure markdown: true para renderizar um editor de markdown completo com barra de ferramentas.

body: {
    type: "string",
    name: "Blog text",
    markdown: true
}

Campo de e-mail

Configure email: true para adicionar validação de formato de e-mail e renderizar com um ícone de e-mail.

email: {
    type: "string",
    name: "User email",
    email: true,
    validation: { required: true }
}

Campo de URL

Configure url: true para adicionar validação de formato de URL e renderizar com um ícone de link.

website: {
    type: "string",
    name: "Amazon link",
    url: true
}

Upload de arquivo

Configure storage para renderizar uma zona de upload de arquivo.

avatar: {
    type: "string",
    name: "Main image",
    storage: {
        storagePath: "avatars",
        acceptedFiles: ["image/*"],
        maxSize: 2 * 1024 * 1024
    }
}

Seleção (enum)

Configure enum para renderizar um menu suspenso. Consulte a seção Valores de Enum para detalhes.

category: {
    type: "string",
    name: "Category",
    enum: [
        { id: "electronics", label: "Electronics", color: "blueDark" },
        { id: "clothing", label: "Clothing", color: "pink" },
    ]
}

Seleção múltipla

Configure enum + multiSelect: true para permitir a seleção de múltiplos valores.

locales: {
    type: "string",
    name: "Available locales",
    multiSelect: true,
    enum: [
        { id: "es", label: "Spanish", color: "pink" },
        { id: "en", label: "English", color: "blueLight" },
        { id: "fr", label: "French", color: "purpleLight" },
    ]
}

Opções de String

Propriedade	Tipo	Descrição
admin.multiline	boolean	Renderizar como textarea
admin.markdown	boolean	Renderizar como editor de markdown
email	boolean	Validação de formato de e-mail
url	boolean	Validação de formato de URL
storage	StorageConfig	Habilitar upload de arquivo
enum	EnumValues	Renderizar como seletor dropdown
multiSelect	boolean	Permitir múltiplas seleções de enum
columnType	string	Coluna de banco de dados: "varchar", "text"
isId	string	Geração de ID: "uuid", "cuid", "increment", "manual"
userSelect	boolean	Renderizar como um seletor de usuário
admin.previewAsTag	boolean	Renderizar esta string como uma tag nas pré-visualizações
admin.clearable	boolean	Adicionar um ícone para limpar o valor (definir como nulo)

Propriedades Numéricas

price: {
    type: "number",
    name: "Price",
    validation: { required: true, min: 0 }
}

quantity: {
    type: "number",
    name: "Quantity",
    columnType: "integer"  // Armazenar como inteiro
}

Campos numéricos são renderizados como um campo de texto padrão com validação numérica.

Opções Numéricas

Propriedade	Tipo	Descrição
enum	EnumValues	Renderizar como seletor com valores numéricos
columnType	string	"integer", "bigint", "numeric", "serial", "smallint"
isId	string	Estratégia de geração de ID
admin.clearable	boolean	Adicionar um ícone para limpar o valor (definir como nulo)

Propriedades Booleanas

active: {
    type: "boolean",
    name: "Selectable",
    defaultValue: true
}

Campos booleanos são renderizados como um interruptor de alternância.

Propriedades de Data

Apenas data

Configure mode: "date" para mostrar um seletor de data sem hora.

event_date: {
    type: "date",
    name: "Expiry date",
    mode: "date"
}

Data e hora

O modo padrão "date_time" inclui tanto data quanto hora.

arrival_time: {
    type: "date",
    name: "Arrival time",
    mode: "date_time"
}

Timestamps automáticos

Use autoValue para definir timestamps automaticamente ao criar ou atualizar.

createdAt: {
    type: "date",
    name: "Created At",
    autoValue: "on_create",
    admin: { readOnly: true }
}

updatedAt: {
    type: "date",
    name: "Updated At",
    autoValue: "on_update"
}

Opções de Data

Propriedade	Tipo	Descrição
mode	"date" | "date_time"	Apenas data ou data + hora (padrão: "date_time")
autoValue	"on_create" | "on_update"	Definir timestamps automaticamente
columnType	string	"timestamp", "date"
timezone	string	String de fuso horário para avaliar a data
admin.clearable	boolean	Adicionar um ícone para limpar o valor (definir como nulo)

Propriedades de Array

Repetição simples

Use of para definir uma lista repetível de itens.

tags: {
    type: "array",
    name: "Tags",
    of: { type: "string" }
}

Upload de múltiplos arquivos

Combine of com storage para um upload de múltiplos arquivos.

images: {
    type: "array",
    name: "Images",
    of: {
        type: "string",
        storage: { storagePath: "images", acceptedFiles: ["image/*"] }
    }
}

Editor de blocos

Use oneOf para criar um editor de blocos com múltiplos tipos de conteúdo. Cada chave cria um tipo de cartão que os usuários podem selecionar.

content: {
    type: "array",
    name: "Content",
    oneOf: {
        properties: {
            text: {
                type: "map",
                properties: {
                    body: { type: "string", name: "Text", markdown: true }
                }
            },
            image: {
                type: "map",
                properties: {
                    src: { type: "string", name: "Image", storage: { storagePath: "content" } },
                    caption: { type: "string", name: "Caption" }
                }
            }
        }
    }
}

Opções de Array

Propriedade	Tipo	Descrição
of	Property | Property[]	Esquema de propriedade para itens do array
oneOf	object	Array de objetos tipados com múltiplos tipos discriminadores
admin.expanded	boolean	O campo deve ser inicialmente expandido? (padrão: true)
admin.minimalistView	boolean	Exibir propriedades filhas diretamente sem painel extensível
admin.sortable	boolean	Os elementos podem ser reordenados? (padrão: true)
admin.canAddElements	boolean	Novos elementos podem ser adicionados? (padrão: true)

Propriedades de Mapa

Grupo (estruturado)

Use properties para definir um objeto estruturado com campos nomeados.

address: {
    type: "map",
    name: "Address",
    properties: {
        street: { type: "string", name: "Street" },
        zip: { type: "string", name: "Postal code" }
    }
}

Chave-valor (livre)

Configure keyValue: true para renderizar um editor de pares chave-valor arbitrários.

metadata: {
    type: "map",
    name: "Key value",
    keyValue: true
}

Opções de Mapa

Propriedade	Tipo	Descrição
properties	Properties	Registro de propriedades incluídas no mapa
propertiesOrder	string[]	Chaves ordenadas para renderização
admin.previewProperties	string[]	Quais propriedades mostrar na pré-visualização da tabela
admin.spreadChildren	boolean	Renderizar propriedades filhas como colunas separadas na visualização de tabela
admin.minimalistView	boolean	Exibir propriedades sem um painel de envoltório
admin.expanded	boolean	O campo deve ser inicialmente expandido? (padrão: true)
keyValue	boolean	Renderizar como editor de pares chave-valor arbitrários

Propriedades de Referência

As referências linkam a entidades em outra coleção. Elas são renderizadas como um cartão de pré-visualização mostrando os detalhes da entidade referenciada.

client: {
    type: "reference",
    name: "Related client",
    path: "clients",
    admin: {
        previewProperties: ["first_name", "last_name", "email"]
    }
}

Opções de Referência e Relação

Aplicam-se tanto às propriedades reference quanto às relation.

Propriedade	Tipo	Descrição
admin.fixedFilter	FilterValues	Filtra as entidades oferecidas no seletor
admin.widget	"select" | "dialog"	Qual widget seleciona a entidade relacionada (apenas relações)
admin.includeId	boolean	Mostrar o id da entidade relacionada nas pré-visualizações (padrão: true)
admin.includeEntityLink	boolean	Mostrar um link que abre a entidade relacionada (padrão: true)
admin.previewProperties	string[]	Quais propriedades do destino aparecem na pré-visualização (máx. 3)

Valores de Enum

Usado com propriedades de string ou numéricas para renderizar seleções:

// Array simples
enum: ["draft", "published", "archived"]

// Com rótulos
enum: [
    { id: "draft", label: "Draft" },
    { id: "published", label: "Published" },
    { id: "archived", label: "Archived" }
]

// Com cores (para colunas Kanban e chips)
enum: [
    { id: "draft", label: "Draft", color: "grayDark" },
    { id: "published", label: "Published", color: "greenDark" },
    { id: "archived", label: "Archived", color: "orangeDark" }
]

Validação

validation: {
    required: true,             // Campo obrigatório
    unique: true,               // Deve ser único na tabela
    requiredMessage: "Custom error message",

    // Específico para strings
    min: 2,                     // Comprimento mínimo
    max: 200,                   // Comprimento máximo
    matches: /^[a-z]+$/,       // Padrão regex
    email: true,                // Formato de e-mail
    url: true,                  // Formato de URL

    // Específico para números
    min: 0,                     // Valor mínimo
    max: 1000,                  // Valor máximo
    integer: true,              // Deve ser inteiro

    // Específico para arrays
    min: 1,                     // Número mínimo de itens
    max: 10,                    // Número máximo de itens
}

Campos Condicionais

Você pode tornar os campos dinâmicos para que reajam aos valores da entidade. Existem duas maneiras de fazer isso:

1. Condições JSON Logic (Declarativas)

Você pode usar a propriedade conditions para definir regras JSON Logic declarativas que podem ser serializadas e modificadas visualmente no editor de coleção.

price: {
    type: "number",
    name: "Price",
    conditions: {
        disabled: { "==": [{ "var": "values.is_free" }, true] },
        required: { "!=": [{ "var": "values.is_free" }, true] },
        min: 0,
        clearOnDisabled: true // Definir como null se o campo for desabilitado
    }
}

O objeto conditions dá acesso a:

• disabled, hidden, readOnly
• required, min, max
• defaultValue
• enumConditions, allowedEnumValues, excludedEnumValues
• referencePath, referenceFilter
• canAddElements, sortable (para arrays)

2. Construtores de Propriedades (Programáticos)

Para comportamentos complexos que não podem ser expressos via JSON Logic, você pode usar dynamicProps, que avalia uma função Javascript.

price: {
    type: "number",
    name: "Price",
    dynamicProps: ({ values, user }) => ({
        disabled: values.is_free === true || !user.roles.includes("admin"),
        validation: values.is_free ? {} : { required: true, min: 0 }
    })
}

Próximos Passos

• Relações — Chaves estrangeiras e junções
• Regras de Segurança — Segurança em Nível de Linha
• Campos Personalizados — Construir componentes de campo personalizados