---
title: "Dynamic Filter Payload Contract"
slug: "dynamic-filter-payload-contract"
description: "Contrato operacional do payload do filtro dinamico, cobrindo eventos do PraxisFilter, envio ao backend e normalizacao aplicada pelo metadata-starter."
doc_type: "reference"
document_kind: "host-guide"
component: "table"
category: "integration"
audience:
  - "host"
  - "frontend"
  - "backend"
  - "architect"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-filter"
  - "payload"
  - "GenericFilterDTO"
  - "metadata-starter"
  - "http"
order: 27
icon: "send"
toc: true
sidebar: true
search_boost: 1.2
reading_time: 18
estimated_setup_time: 40
version: "1.0"
related_docs:
  - "dynamic-filter-architecture-overview"
  - "dynamic-filter-range-filters-guide"
  - "dynamic-fields-inline-components-guide"
  - "dynamic-fields-inline-filter-runtime-contract"
  - "table-overview"
keywords:
  - "submit"
  - "change"
  - "GenericFilterDTO"
  - "POST /filter"
source_of_truth:
  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.spec.ts"
  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/controller/base/AbstractResourceQueryController.java"
  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/web/FilterRequestBodyAdvice.java"
  - "../praxis-metadata-starter/docs/examples/filter-dto.md"
  - "../praxis-metadata-starter/docs/guides/FILTROS-E-PAGINACAO.md"
last_updated: "2026-03-07"
---

# Dynamic Filter Payload Contract

## Objetivo

Formalizar como o payload do filtro dinâmico nasce na UI, como deve ser enviado pelo host e como o `praxis-metadata-starter` o trata antes de construir a consulta.

Nota de trilha:

- `table` documenta o payload da feature
- `dynamic-fields` documenta o shape que cada inline coloca no formulario antes do envio

## Pré-requisitos

- Conhecimento básico do `PraxisFilter` e dos endpoints resource-oriented de filtro.
- DTO de filtro backend implementando `GenericFilterDTO`.
- Entendimento mínimo de `controlType`, `@Filterable` e operações de range.

## Quando usar

Use este documento para:

- implementar integração host -> backend sem adivinhação;
- revisar shape do payload emitido por `change` e `submit`;
- alinhar frontend e backend sobre o que é aceito como filtro válido;
- depurar `400 FILTER_PAYLOAD_INVALID`.

## Contrato funcional

O runtime do filtro expõe dois eventos principais:

- `change`: mudanças incrementais do formulário;
- `submit`: snapshot que normalmente deve ser enviado ao backend.

Além disso, existem eventos auxiliares como `clear`, `tagsChange`, `selectedFieldIdsChange`, `metaChanged` e `schemaStatusChange`, mas eles não substituem o payload principal do filtro.

O fluxo oficial do payload é o seguinte.

```mermaid
sequenceDiagram
  participant UI as PraxisFilter
  participant Host
  participant Controller as AbstractResourceQueryController
  participant Advice as FilterRequestBodyAdvice
  participant Normalizer as RangePayloadNormalizer
  participant DTO as GenericFilterDTO
  participant Builder as GenericSpecificationsBuilder

  UI->>Host: submit or change payload
  Host->>Controller: POST /filter
  Controller->>Advice: intercept request body
  Advice->>Normalizer: normalize ranges and aliases
  Normalizer->>DTO: canonical payload
  DTO->>Builder: typed filter ready for specification
  Builder-->>Controller: query/specification pronta ou erro
  Controller-->>Host: result payload or 400 FILTER_PAYLOAD_INVALID
```

## O que o host realmente envia

O host deve serializar o DTO produzido pela UI como JSON e enviá-lo para o controller correspondente.

Superfícies padrão do starter:

- `POST /filter`
- `POST /filter/cursor`
- `POST /locate`
- `POST /options/filter`

O shape exato depende do seu `FilterDTO`, mas o princípio é o mesmo: cada propriedade enviada deve corresponder a um campo filtrável do backend.

## Pipeline do payload

### 1. Runtime Angular

O `PraxisFilter` agrega o estado do formulário e emite objetos do tipo `Record<string, any>`.

Aspectos relevantes do runtime:

- ranges vazios não devem sobreviver à serialização;
- estado avançado e preferências visuais podem ser persistidos localmente;
- aliases inline e metadata overrides influenciam a UI, mas não devem gerar um contrato HTTP arbitrário.

### 2. Envio HTTP

O host é responsável por:

- observar `submit` ou `change`;
- aplicar debounce/estratégia de busca adequada;
- enviar o JSON ao endpoint correto;
- não inventar transformações fora do contrato do backend.

### 3. Interceptação no backend

No `praxis-metadata-starter`, o request body passa por `FilterRequestBodyAdvice` antes da desserialização final.

Esse ponto é central para a doc:

- o payload não é consumido “como veio”;
- ranges podem ser canonicalizados;
- payload inválido já pode falhar nessa etapa.

### 4. Normalização de ranges

`RangePayloadNormalizer` converte payloads canônicos para o formato de lista esperado pelos DTOs tipados.

Isso inclui:

- arrays canônicos;
- objetos canônicos;
- nomes de bound reconhecidos pela plataforma para domínios como data, numérico e monetário.

### 5. Construção da consulta

Depois da normalização, `GenericSpecificationsBuilder` monta a predicate com base em `@Filterable`.

Para o frontend, a consequência prática é simples:

- a UI pode ser rica;
- o contrato final precisa continuar mapeável para `GenericFilterDTO`.

## Exemplo de payload enviado pela UI

```json
{
  "name": "Alice",
  "departmentId": 10,
  "salaryRange": {
    "minPrice": 6500,
    "maxPrice": 15000,
    "currency": "BRL"
  },
  "admissionPeriod": {
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
  },
  "status": [
    "ACTIVE",
    "PENDING"
  ]
}
```

## Entity Lookup em coleções

Quando um filtro usa `entityLookup` com `multiple=true`, o `PraxisFilter` não deve persistir nem emitir a coleção rica do runtime como contrato HTTP final. A tabela agora reaproveita o helper canônico de `@praxisui/core` e respeita o mesmo `payloadMode` já usado pelo `dynamic-form`.

Regras:

- `multiple=true` sem `payloadMode` explícito envia `ids`
- `multiple=true` com `payloadMode: "entityRefs"` envia `[{ id, type }]`
- o `entityType` padrão vem de `optionSource.entityKey` quando a linha ainda não trouxer `type`

Exemplo com `ids`:

```json
{
  "supplierIds": ["sup_1", "sup_2"]
}
```

Exemplo com `entityRefs`:

```json
{
  "suppliers": [
    { "id": "sup_1", "type": "supplier" },
    { "id": "sup_2", "type": "legacy-supplier" }
  ]
}
```

Diretriz:

- hosts não devem criar um serializer paralelo para filtros de entidade em tabela;
- `PraxisFilter` já deve emitir o payload canônico pronto para envio ao backend.

## Como o starter trata esse payload

Para campos simples:

- valores seguem diretamente para o `FilterDTO`.

Para ranges:

- o backend pode converter o objeto em lista canônica;
- chaves auxiliares consumidas pelo normalizador são removidas do payload final desserializado;
- listas com limites inválidos ou conflitantes retornam erro.

Exemplo de canonicalização:

```json
{
  "salaryRange": [6500, 15000],
  "admissionPeriod": ["2026-03-01", "2026-03-31"]
}
```

## Regras práticas para o frontend

1. Envie apenas propriedades semanticamente preenchidas.
   Não envie objetos vazios, listas com três posições ou placeholders neutros.

2. Prefira objeto canônico ou lista canônica para ranges.
   Não envie payload escalar para operações Java de range.

3. Não serialize metadata de UI junto com o DTO.
   `label`, `tooltip`, `clearButton` e `inlineAutoSize` são contrato de renderização, não de busca.

4. Use nomes canônicos nos contratos novos.
   Para numérico genérico, prefira `{ min, max }`; para monetário, `{ minPrice, maxPrice }`; para datas, `{ startDate, endDate }`.

5. Considere `change` e `submit` como contrato de integração, não como detalhe interno.

## Query Context na Orquestração de Página

Quando o filtro dinâmico participar de um `praxis-dynamic-page`, o contrato recomendado entre widgets não é mais gravar diretamente `filterCriteria` em cada consumidor.

O caminho canônico passa a ser:

- `praxis-filter` emite `requestSearch` com o DTO filtrado
- a página escreve esse payload em `page.state`
- a página ou o builder propagam um `queryContext` para widgets de dados

Exemplo recomendado:

```json
{
  "queryContext": {
    "filters": {
      "departmentId": 10,
      "status": "ACTIVE"
    },
    "sort": ["nome,asc"],
    "page": {
      "index": 0,
      "size": 25
    }
  }
}
```

Diretriz de compatibilidade:

- `filterCriteria` continua válido em componentes que ainda publicam esse contrato
- para novo authoring, recipes e bindings, prefira `queryContext`
- a semântica mínima garantida hoje é `queryContext.filters`; `sort`, `limit` e `page` devem ser consumidos apenas por widgets que já declararam suporte a esses campos
- `queryContext.filters` continua sendo um DTO plano com semântica de conjunção simples; filtros compostos com OR ou grupos aninhados devem evoluir pelo contrato canônico proposto em `projects/praxis-core/docs/rfc-query-context-filter-expression.md`, não por aliases ou payloads ad hoc do frontend

## Payloads que devem ser evitados

Exemplos inválidos ou indesejáveis:

```json
{ "salaryRange": 1500 }
```

```json
{ "salaryRange": [10, 20, 30] }
```

```json
{ "admissionPeriod": { "startDate": null, "endDate": null } }
```

```json
{ "salaryRange": { "from": 10, "minPrice": 20 } }
```

O último caso é especialmente perigoso porque pode configurar fonte conflitante para o mesmo bound.

## Como documentar esta feature daqui para frente

Toda documentação de filtro dinâmico precisa citar explicitamente:

- qual evento gera o payload;
- qual endpoint o recebe;
- como o `FilterRequestBodyAdvice` o intercepta;
- como `RangePayloadNormalizer` o canonicaliza;
- quais falhas devolvem `400`.

Sem isso, a doc tende a ficar “bonita na UI” e incompleta na integração real.
