Telas administrativas se repetem: listagem com filtros, formulário de criação, edição, exclusão. Escrever cada uma à mão significa dezenas de componentes quase idênticos, cada um com seus pequenos desvios e bugs. A alternativa é uma UI guiada por schema (schema-driven UI): o schema descreve a entidade e a interface é derivada dele.
Neste artigo vou mostrar como projetar uma biblioteca interna com essa ideia usando JSON Schema, mantendo a tipagem com TypeScript e gerando consultas complexas a partir de query params.
Por que schema-driven?
- Menos código repetido: uma nova entidade vira um schema, não um conjunto de telas.
- Consistência: todas as telas se comportam da mesma forma.
- Uma fonte da verdade: validação, formulário, tabela e tipos nascem do mesmo lugar.
- Evolução centralizada: melhorar o componente de data melhora todas as telas.
O custo é uma biblioteca para manter e uma camada de abstração. Vale a pena quando você tem muitas entidades parecidas, que é o caso típico de um backoffice.
JSON Schema como fonte da verdade
O JSON Schema é um padrão maduro, com validadores e ferramentas em várias linguagens, o que permite compartilhá-lo entre backend e frontend. Os metadados podem vir do banco (colunas, tipos, nulabilidade, constraints) e ser convertidos em schema, ou ser mantidos como arquivos versionados.
{
"$id": "veiculo",
"type": "object",
"required": ["placa", "tipo"],
"properties": {
"placa": { "type": "string", "pattern": "^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$", "title": "Placa" },
"tipo": { "type": "string", "enum": ["TRUCK", "CARRETA", "VUC"], "title": "Tipo" },
"capacidadeKg": { "type": "number", "minimum": 0, "title": "Capacidade (kg)" },
"ativo": { "type": "boolean", "title": "Ativo", "default": true }
}
}
Dele derivamos quase tudo:
- Formulário:
stringvira input,enumvira select,booleanvira switch,format: "date"vira datepicker. - Validação: o mesmo schema valida no cliente (Ajv) e no servidor.
- Colunas da tabela: as
propertiesviram colunas, comtitlecomo cabeçalho. - Filtros: o tipo do campo define quais operadores fazem sentido (texto: contém; número: maior/menor; enum: está em).
- Tipos TypeScript: a tipagem é gerada ou inferida do schema, sem duplicação.
Mantendo a tipagem com TypeScript
Existem duas abordagens principais:
1. Inferência em tempo de compilação com json-schema-to-ts. O schema precisa ser declarado as const:
import type { FromSchema } from 'json-schema-to-ts';
export const veiculoSchema = {
$id: 'veiculo',
type: 'object',
required: ['placa', 'tipo'],
properties: {
placa: { type: 'string', title: 'Placa' },
tipo: { type: 'string', enum: ['TRUCK', 'CARRETA', 'VUC'], title: 'Tipo' },
capacidadeKg: { type: 'number', title: 'Capacidade (kg)' },
ativo: { type: 'boolean', title: 'Ativo' },
},
} as const;
export type Veiculo = FromSchema<typeof veiculoSchema>;
// { placa: string; tipo: 'TRUCK' | 'CARRETA' | 'VUC'; capacidadeKg?: number; ativo?: boolean }
2. Geração de código com json-schema-to-typescript, útil quando os schemas vêm do backend e você quer gerar arquivos .d.ts no build.
Com qualquer uma delas, o componente genérico recebe o tipo e o compilador cobra consistência:
type SchemaFormProps<T> = {
schema: JSONSchema;
defaultValues?: Partial<T>;
onSubmit: (values: T) => Promise<void>;
};
Um renderizador por tipo
O coração da biblioteca é um registro que mapeia tipos de campo para componentes:
const registry: Record<string, React.FC<FieldProps>> = {
string: TextField,
number: NumberField,
boolean: SwitchField,
enum: SelectField,
date: DateField,
};
function resolverTipo(def: JSONSchema) {
if (def.enum) return 'enum';
if (def.format === 'date') return 'date';
return def.type as string;
}
export function SchemaForm<T>({ schema, onSubmit, defaultValues }: SchemaFormProps<T>) {
const methods = useForm<T>({ defaultValues, resolver: ajvResolver(schema) });
return (
<FormProvider {...methods}>
<form onSubmit={methods.handleSubmit(onSubmit)}>
{Object.entries(schema.properties).map(([name, def]) => {
const Field = registry[resolverTipo(def)];
return <Field key={name} name={name} schema={def} required={schema.required?.includes(name)} />;
})}
<Button type="submit">Salvar</Button>
</form>
</FormProvider>
);
}
Extensões para casos fora do padrão
Nem toda tela cabe no padrão. Use propriedades customizadas (prefixo x-, que o JSON Schema permite) para ajustar a UI sem quebrar a validação:
{
"motorista": {
"type": "string",
"title": "Motorista",
"x-component": "AsyncSelect",
"x-source": "/motoristas",
"x-order": 2
},
"observacao": { "type": "string", "x-hidden": true }
}
E permita overrides por entidade, para substituir um campo ou uma coluna por um componente próprio. O objetivo é cobrir 80% das telas e não bloquear os outros 20%.
Consultas complexas via query params
A parte que mais ganha valor é a listagem. Em vez de criar um endpoint por filtro, o front traduz o que o usuário escolhe na UI em query params padronizados:
GET /veiculos?filter[tipo]=in:TRUCK,CARRETA
&filter[capacidadeKg]=gte:20000
&filter[placa]=like:ABC
&sort=-capacidadeKg
&page=2&pageSize=20
No frontend
O estado dos filtros vive na URL, o que permite compartilhar, favoritar e recarregar a página sem perder o contexto:
function serializarFiltros(filtros: Filtro[]) {
const params = new URLSearchParams();
for (const { campo, operador, valor } of filtros) {
params.set(`filter[${campo}]`, `${operador}:${Array.isArray(valor) ? valor.join(',') : valor}`);
}
return params;
}
No backend
Um parser converte os parâmetros em uma query, sempre validando contra o schema:
const operadores = {
eq: (q, c, v) => q.where(c, v),
ne: (q, c, v) => q.whereNot(c, v),
gte: (q, c, v) => q.where(c, '>=', v),
lte: (q, c, v) => q.where(c, '<=', v),
in: (q, c, v) => q.whereIn(c, v.split(',')),
like: (q, c, v) => q.whereILike(c, `%${v}%`),
};
function aplicarFiltros(query, filtros, schema) {
for (const [campo, expr] of Object.entries(filtros)) {
if (!(campo in schema.properties)) throw new BadRequest(`Campo inválido: ${campo}`);
const [op, valor] = expr.split(/:(.+)/);
if (!(op in operadores)) throw new BadRequest(`Operador inválido: ${op}`);
operadores[op](query, campo, coagir(valor, schema.properties[campo]));
}
return query;
}
Relacionamentos e condições compostas
Para consultas mais ricas, a mesma ideia se estende:
- Filtros em relações:
filter[motorista.nome]=like:João, que o parser resolve comJOINapenas se a relação estiver declarada no schema. - Grupos OR:
filter[or][0][tipo]=eq:VUC&filter[or][1][capacidadeKg]=gte:20000. - Seleção de campos:
fields=placa,tipopara reduzir o payload. - Paginação por cursor em tabelas grandes, no lugar de
OFFSET, que degrada com páginas profundas.
Cuidados inegociáveis
- Whitelist de campos e operadores definida pelo schema, de modo que o usuário só filtra e ordena o que você permitiu (e idealmente só por colunas indexadas).
- Queries parametrizadas por meio de um query builder, nunca concatenando strings, para evitar SQL injection.
- Limite de paginação (
pageSizemáximo) e limite de profundidade/quantidade de filtros para impedir consultas que derrubam o banco. - Coerção de tipos guiada pelo schema:
"20000"na URL viranumberantes de chegar à query. - Autorização aplicada antes dos filtros do usuário (por exemplo, restringir ao tenant), nunca depois.
Juntando as peças: uma tela de CRUD
Com tudo isso, uma tela completa passa a ser pouco mais que configuração:
export function VeiculosPage() {
return (
<CrudPage
schema={veiculoSchema}
endpoint="/veiculos"
columns={['placa', 'tipo', 'capacidadeKg', 'ativo']}
filters={['tipo', 'capacidadeKg', 'placa']}
/>
);
}
O CrudPage cuida da listagem, filtros na URL, paginação, formulário em modal, validação e mensagens de erro. O que sobra para a equipe é o que realmente é específico do negócio.
Armadilhas que vi no caminho
- Abstração vazando: se toda tela precisa de override, o schema está pobre ou a biblioteca está rígida demais. Meça quantas telas precisam fugir do padrão.
- Schema virando linguagem de programação: evite colocar lógica dentro do schema. Condicionais complexas devem ser exceções tratadas em código.
- Performance de formulários grandes: use bibliotecas com inputs não controlados (como React Hook Form) e memoize os campos.
- Mensagens de erro genéricas: traduza as mensagens do validador para o idioma e o vocabulário do usuário.
Conclusão
Uma UI guiada por schema transforma a criação de telas administrativas em uma atividade declarativa: descreva a entidade, e a interface, a validação, os tipos e até a API de consulta decorrem dela. O ganho de velocidade é grande, mas o maior valor é a consistência e a manutenção centralizada. Comece pequeno, com um registro de campos e uma listagem filtrável, e deixe as necessidades reais das telas guiarem a evolução da biblioteca.