Guia de Conformidade - Especificacao Praxis x-ui v1.0.0

Objetivo

• Descrever como validar JSONs gerados por qualquer backend contra os JSON Schemas desta pasta.
• Definir criterios minimos (Core) e opcionais (Extended) de conformidade.
• Mapear, de forma resumida, quais chaves a UI consome e onde.

Como validar localmente (AJV CLI)

• Pre-requisitos: Node.js 18+
• Instalacao local do ajv-cli (projeto host):
  • npm i -D ajv ajv-formats ajv-cli
• Exemplos de execucao:
  • Validar x-ui de campo:
    • npx ajv -s ./x-ui-field.schema.json -d ./examples/x-ui-field.valid.json -c ajv-formats
    • npx ajv -s ./x-ui-field.schema.json -d ./examples/x-ui-field.invalid.json -c ajv-formats || echo "(esperado: invalido)"
  • Validar x-ui de operacao:
    • npx ajv -s ./x-ui-operation.schema.json -d ./examples/x-ui-operation.valid.json
  • Validar x-ui.resource:
    • npx ajv -s ./x-ui-resource.schema.json -d ./examples/x-ui-resource.valid.json
  • Validar x-ui.chart:
    • npx ajv -s ./x-ui-chart.schema.json -d ./examples/x-ui-chart.valid.json
    • npx ajv -s ./x-ui-chart.schema.json -d ./examples/x-ui-chart.invalid.json || echo "(esperado: invalido)"
  • Antes de publicar uma versao nova do starter com charts:
    • revisar ./x-ui-chart-publication-checklist.md

Criterios de Conformidade

• Core (minimo obrigatorio)
  • x-ui por campo segue o schema e utiliza chaves canonicas para tipo, controle e validacoes basicas
  • x-ui.resource presente no payload de /schemas/filtered contendo idField, idFieldValid, readOnly, capabilities
  • /schemas/surfaces e /schemas/actions publicam apenas discovery semantico e links para schemas canonicos resolviveis via /schemas/filtered
  • ETag forte no /schemas/filtered e hash deterministico em X-Schema-Hash
  • schemaId estavel conforme composicao path|operation|schemaType|internal|tenant|locale
  • quando x-ui.chart.source.kind = "praxis.stats", o contrato publicado exige source.resource e source.operation
  • quando um campo publicar x-ui.optionSource, o bloco deve obedecer o schema draft e manter convivio aditivo com o legado
• Extended (recomendado)
  • preencher displayColumns/displayFields no x-ui de operacao
  • publicar x-ui.chart com version, kind, source, semantica analitica e eventos declarativos, mantendo o contrato agnostico de engine
  • quando source.kind = "praxis.stats", manter coerencia com os produtores reais da familia /stats/*, em especial group-by, timeseries e distribution
  • preencher x-ui.operationExamples.<schemaType> quando o OpenAPI publicar exemplos uteis
  • popular mensagens de validacao (*Message) para melhor UX
  • incluir capabilities.options|byId|all|filter|cursor quando aplicavel
  • manter /schemas/surfaces e /schemas/actions sincronizados com a semantica publicada por @UiSurface e @WorkflowAction
  • adotar custom.* para extensoes privadas do host
  • publicar x-ui.optionSource para fontes derivadas governadas, evitando promover INPUT em campos com semantica corporativa clara

Matriz - Chave da Spec -> Consumo na UI

• x-ui por campo
  • type, controlType -> SchemaNormalizerService / FieldDefinition
  • label -> rotulagem de inputs e colunas
  • placeholder, hint, helpText -> renderizacao de formulario
  • readOnly, disabled -> field-state.util.ts e componentes
  • validacoes (required, minLength, maxLength, pattern, min, max, range, *Message) -> helpers de validacao
  • selecao (options, endpoint, valueField, displayField, multiple, emptyOptionText) -> componentes de selecao
  • numerico (numericFormat, numeric*) -> componentes numericos
• x-ui por operacao
  • displayColumns -> padrao de colunas iniciais
  • operationExamples.<schemaType> -> exemplos operacionais para catalogo, playgrounds e documentacao contextual
• x-ui.chart
• version, kind, source -> identidade minima do contrato analitico metadata-driven
• dimensions, metrics, aggregations, filters, sort -> semantica analitica canonica
• metrics[].seriesKind, metrics[].axis -> serie heterogenea e eixo primario/secundario para charts combinados
• state, events -> estados e interacoes declarativas de plataforma
• x-ui.optionSource
  • key, type, resourcePath -> identidade minima da fonte derivada
  • dependsOn, excludeSelfField -> cascata e remocao do proprio predicado
  • searchMode, pageSize, includeIds, cachePolicy -> politica publica minima de consumo
• x-ui.resource
  • idField -> chave primaria no fluxo de CRUD/UI
  • idFieldValid/idFieldMessage -> diagnostico e alertas
  • readOnly -> bloqueio de edicao
  • capabilities -> habilitacao de acoes e utilitarios
• discovery semantico
  • /schemas/surfaces -> catalogo semantico de @UiSurface e surfaces automaticas do recurso
  • /schemas/actions -> catalogo semantico de @WorkflowAction

Compatibilidade de consumidor - @praxisui/charts

O draft canonico pode ser mais amplo que o runtime Angular atual.

Suportado hoje no runtime oficial:

• source.kind = "praxis.stats"
• kind: bar, horizontal-bar, line, pie, donut, area, stacked-bar, stacked-area, scatter
• kind: combo com dados locais/derivados e series heterogeneas por metrica
• uma metrica por chart quando a origem e praxis.stats
• pointClick e drillDown no fluxo atual
• orientation = "horizontal" para horizontal-bar
• scatter com leitura bidimensional minima: primeira dimensao no eixo x e primeira metrica no eixo y

Ainda nao suportado no runtime Angular atual:

• source.kind = "derived"
• kind = "combo" sobre source.kind = "praxis.stats" com multiplas metricas publicadas pelo backend
• aggregation = "distinct-count"
• events.selectionChange
• events.crossFilter
• theme.variant
• theme.palette como token string
• pie/donut com multiplas metricas

Publicacoes do starter devem deixar essa assimetria explicita ate que os consumidores sejam endurecidos no mesmo nivel.

Compatibilidade de consumidor - x-ui.optionSource

O draft canonico de x-ui.optionSource ainda pode ser mais amplo que o rollout implementado em cada consumidor.

Estado esperado por fase:

• documentado na RFC: x-ui-option-source-rfc.md
• validado no schema de campo: x-ui-field.schema.json
• ainda nao obrigatoriamente publicado/executado em todos os hosts
• ainda nao obrigatoriamente consumido pelo runtime Angular oficial

Diretriz de rollout:

• x-ui.optionSource deve entrar de forma aditiva
• endpoint, valueField e displayField permanecem validos durante a transicao
• um host pode publicar ambos os modelos para o mesmo campo quando isso reduzir risco de migracao
• consumidores nao devem inferir optionSource a partir de heuristicas locais se o backend ainda nao o publicar

Boas praticas e notas

• custom.*: prefixo reservado para extensoes de fornecedores/hosts
• o backend deve canonicalizar o payload antes de calcular o hash do schema
• o backend deve separar payload estrutural e payload documental antes de calcular o hash
• locale/tenant variam schemaId e os headers de cache

Compatibilidade (anotacoes temporarias)

• filterOptions: a spec define array, porem o starter atualmente serializa como string em alguns caminhos legados. Mantido assim por compatibilidade com consumidores atuais.
• optionSource: o schema draft ja valida o bloco, mas a publicacao em /schemas/filtered e o consumo runtime oficial dependem das PRs de rollout de backend/host/UI.

Suite de fixtures

• Esta pasta traz exemplos validos e invalidos para facilitar a automacao no CI.
• Os arquivos *.valid.json e *.invalid.json devem ser tratados como fixtures de validacao, nao como catalogo exaustivo de exemplos publicos.
• canonical-payload.json e x-ui-chart.valid.json tambem cumprem papel documental e podem ser referenciados em guias, desde que permanecam coerentes com os schemas publicados.
• os fixtures x-ui-field-option-source-*.json cobrem apenas o draft contratual inicial e nao implicam rollout completo da feature.
• Use estes arquivos como base para gerar casos especificos do seu dominio.