---
title: "form-json-config-editor JSON API (Canonical)"
slug: "form-json-config-editor-json-api"
doc_type: "api-reference"
component: "form-json-config-editor"
document_kind: "json-api-canonical"
reference_mode: "canonical"
contract_format: "json"
contract_source: "runtime-and-code"
description: "Referencia canonica do contrato JSON do componente form-json-config-editor."
category: "components"
sub_category: "config-editor"
audience:
  - "frontend"
  - "architect"
  - "platform-team"
level: "advanced"
status: "active"
owner: "praxis-ui"
source_of_truth:
  - "projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.ts"
  - "projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.spec.ts"
  - "projects/praxis-dynamic-form/src/lib/services/form-config.service.ts"
  - "projects/praxis-core/src/lib/models/form/form-config.model.ts"
source_of_truth_last_verified: "2026-03-05"
last_updated: "2026-03-05"
toc: true
sidebar: true
tags:
  - "json-api"
  - "canonical-contract"
  - "form-json-config-editor"
api_stability: "canonical"
schema_verified: true
runtime_verified: false
editor_coverage_verified: false
runtime_scope: "public"
legacy_paths_present: false
has_known_mismatches: false
related_components:
  - "praxis-table"
---

# form-json-config-editor

Este documento e a referencia canonica da API JSON de form-json-config-editor.

## Summary

- Tipo documental: API reference canonica de contrato JSON.
- Source of truth: runtime e codigo declarados no frontmatter.
- Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
- Resumo funcional herdado: `form-json-config-editor` e a superficie de edicao JSON direta para `FormConfig`. Ele oferece validacao local, formatacao, aplicacao manual de JSON e eventos de telemetria do editor.

## Scope and positioning

- Escopo: contrato JSON publico e limites de comportamento observavel.
- Fora de escopo: tutorial de adocao e walkthrough operacional detalhado.
- Posicionamento: referencia canonicamente governada para consumidores, arquitetos e mantenedores.

## Source of truth

| Source | Kind | Notes |
| --- | --- | --- |
| projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.ts | runtime-code | Source de implementacao declarado no repositorio. |
| projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.spec.ts | runtime-code | Source de implementacao declarado no repositorio. |
| projects/praxis-dynamic-form/src/lib/services/form-config.service.ts | runtime-code | Source de implementacao declarado no repositorio. |
| projects/praxis-core/src/lib/models/form/form-config.model.ts | runtime-code | Source de implementacao declarado no repositorio. |

## Support legend

- Active: suportado e observado no runtime atual.
- Partial: suporte parcial, com restricoes conhecidas.
- Declared-only: declarado em tipos/schema sem ligacao runtime confirmada.
- Schema-only: presente em schema/modelo sem confirmacao de execucao.
- Deprecated: mantido por compatibilidade legada com migracao prevista.

## Contract classification

### Canonical paths (public contract)

| Path | Type | Required | Default | Status | Notes |
| --- | --- | --- | --- | --- | --- |
| `config` | `FormConfig \| null` | No | `null` | Active | Payload principal editado/aplicado pelo componente. |
| `hooks.beforeValidate[]` | array | No | `[]` | Partial | Inserido por helper `insertHooksTemplate()` quando usado. |
| `hooks.beforeSubmit[]` | array | No | `[]` | Partial | Inserido por helper `insertHooksTemplate()` quando usado. |
| `behavior.reactiveValidation` | boolean | No | component-defined | Partial | Ativado por helper `enableReactiveValidation()`. |
| `behavior.reactiveValidationDebounceMs` | number | No | `200` (helper) | Partial | Configurado apenas quando helper é acionado. |

### Supported legacy paths

Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.

### Internal-only paths

| Path | Internal consumer | Runtime presence | Public support | Notes |
| --- | --- | --- | --- | --- |
| `jsonText` (estado interno) | editor textarea/runtime validation | Yes | No | Buffer temporário da edição textual, não persistido no contrato público. |
| `jsonTextChanges$` | pipeline debounce/validação | Yes | No | Subject interno para validação em 300ms. |

### Experimental paths

| Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
| --- | --- | --- | --- | --- |
| `hooks.beforeValidate[]` (inserção assistida) | ação manual `insertHooksTemplate()` | Partial | Não é aplicado automaticamente; depende de interação do usuário | Helper de produtividade, sem garantia de aderência semântica do hook. |

## Overview

Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecnico existente. O conteudo detalhado anterior foi preservado para manter rastreabilidade historica e reduzir perda de contexto.

## Public contract surface

### Top-level configuration blocks

| Block | Purpose | Required | Merge strategy | Notes |
| --- | --- | --- | --- | --- |
| `config` | Snapshot do `FormConfig` em edição | No | replace-object on apply | Fonte vem de input ou `FormConfigService.currentConfig`. |
| `hooks` | Bloco de hooks (opcional) | No | deep-merge helper-driven | Pode ser enriquecido por templates de ajuda. |
| `behavior` | Regras comportamentais do form | No | deep-merge helper-driven | Pode receber `reactiveValidation` por helper. |

### Nested configuration blocks

| Path | Type | Required | Default | Constraints | Notes |
| --- | --- | --- | --- | --- | --- |
| `hooks.beforeValidate[]` | array | No | `[]` | hook-contract | Inserido por helper com dedupe básico por conteúdo. |
| `hooks.beforeSubmit[]` | array | No | `[]` | hook-contract | Inserido por helper com dedupe básico por conteúdo. |
| `behavior.reactiveValidation` | boolean | No | false | boolean | Ativado por helper de validação reativa. |
| `behavior.reactiveValidationDebounceMs` | number | No | `200` | integer >= 0 | Preenchido quando ausente pelo helper. |

### Input bindings

| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
| --- | --- | --- | --- | --- | --- |
| `config` | `FormConfig \| null` | No | component-input/service | `JSON.stringify(config, null, 2)` | Se ausente, usa `FormConfigService.currentConfig`. |

### Output events

| Event | Payload | Trigger | Stability | Notes |
| --- | --- | --- | --- | --- |
| `configChange` | `FormConfig` | Apenas em `applyJsonChanges()` com JSON valido. | Partial | Preservado da documentação anterior. |
| `validationChange` | `JsonValidationResult` | Em cada ciclo de validacao (debounce 300ms). | Partial | Preservado da documentação anterior. |
| `editorEvent` | `JsonEditorEvent` | Eventos `validation`, `format` e `apply`. | Partial | Preservado da documentação anterior. |

### External side channels

| Channel | Direction | Contract | Failure mode | Notes |
| --- | --- | --- | --- | --- |
| `FormConfigService.currentConfig` | inbound | `FormConfig` snapshot | fail-soft | Fonte inicial quando `@Input() config` não é fornecido. |
| `FormConfigService.validateConfig()` | outbound validate | `FormConfig -> string[]` | reject invalid apply | Base canônica de validação estrutural/semântica. |
| `FormConfigService.loadConfig()` | outbound apply | `FormConfig` | fail-closed por try/catch | Atualiza estado global de configuração após apply válido. |

### Host/runtime dependencies

| Dependency | Required | Environment | Purpose | Notes |
| --- | --- | --- | --- | --- |
| `FormConfigService` | Yes | browser/dev/prod/ssr | validação + apply | Serviço central para validar e carregar config. |
| `ChangeDetectorRef` | Yes | browser/dev/prod/ssr | atualização visual | Atualiza estado de validação/formatação no editor. |
| `rxjs` (`debounceTime`) | Yes | browser/dev/prod/ssr | pipeline de validação | Debounce fixo de 300ms para texto em edição. |

## Coverage matrix

| Surface | Verified | Coverage status | Evidence | Notes |
| --- | --- | --- | --- | --- |
| Runtime | false | Partial | source_of_truth + conteudo preservado | Revisao estrutural concluida; validacao comportamental fina pode exigir follow-up. |
| Schema/Types | true | Partial | interfaces/modelos citados | Mapeamento formal de todos os campos ainda pode requerer refinamento. |
| Editor/Tooling | false | Partial | secoes de editor quando presentes | Cobertura de editor/tooling nem sempre confirmada por evidencia direta. |

## Runtime coverage boundaries

- Cobertura consolidada com base em documentacao existente e source of truth declarado.
- Comportamentos fora de evidencia direta foram marcados como not-yet-verified ou Partial.
- Compatibilidade legada, quando detectada, foi separada em classificacao explicita.

## Resolution model

### Merge order

1. `@Input() config` (quando presente)
2. fallback para `FormConfigService.currentConfig`
3. edição textual (`jsonText`) com validação incremental
4. apply explícito (`applyJsonChanges`) substitui snapshot no serviço

### Fallback order

`config` input -> `FormConfigService.currentConfig` -> objeto vazio serializado (`{}`) em caso de falha de stringify.

### Override points

- `@Input() config`
- ações de toolbar do editor (`applyJsonChanges`, `formatJson`, helpers)
- estado compartilhado via `FormConfigService`

### Runtime normalization

- `JSON.stringify(..., null, 2)` padroniza saída formatada.
- `validateJson()` força contrato de objeto JSON antes de qualquer apply.
- helpers inserem blocos mínimos (`hooks`, `behavior`) com dedupe básico.

### Precedence rules

- `@Input() config` tem precedência sobre `currentConfig` na inicialização.
- `applyJsonChanges()` só executa quando `isValidJson=true`.
- `formatJson()` não altera estado quando JSON está inválido.

## Validation and error semantics

### Validation model

| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
| --- | --- | --- | --- | --- |
| texto vazio | pre-parse | reject | `JSON não pode estar vazio` | Atualiza `validationChange` e `editorEvent(validation)`. |
| parse JSON | parse | reject | `Erro de sintaxe JSON` | Captura erro de parse e mantém `isValidJson=false`. |
| raiz não-objeto | semantic | reject | `Configuração deve ser um objeto` | Arrays/primitivos não são aceitos como contrato raiz. |
| `validateConfig(parsed)` | semantic | reject | `errors.join('; ')` | Usa `FormConfigService` como autoridade de validação. |
| apply inválido | apply | no-op | `Erro ao aplicar configuração JSON` | Emite `editorEvent(type='apply')` com `isValid=false`. |

### Error semantics

Validação e apply são fail-closed: payload inválido não é aplicado no serviço. O componente mantém estado editável e reporta erros via `validationChange` e `editorEvent`.

### Fail-open / fail-closed behavior

| Condition | Mode | Runtime behavior | Consumer impact |
| --- | --- | --- | --- |
| JSON inválido durante edição | fail-closed para apply | bloqueia `applyJsonChanges()` | evita propagar config inconsistente |
| erro em `JSON.stringify` inicial | fail-open | usa `'{}'` no editor | editor permanece utilizável |
| erro em `formatJson` | fail-soft | mantém texto atual e emite evento de erro | sem perda automática de conteúdo |
| erros de validação de contrato | fail-closed para apply | mantém `isValidJson=false` até correção | exige correção explícita antes de aplicar |

### Invalid or unknown field handling

- Campos desconhecidos: comportamento depende da estrategia do componente (ignore, warn ou reject).
- Campos invalidos: podem gerar fallback, warning ou falha conforme implementacao.
- Registrar divergencias observadas em Known limitations and mismatches.

### Runtime warnings vs hard failures

| Condition | Severity | Observability | Consumer action |
| --- | --- | --- | --- |
| partial-or-declared-only-coverage | warning | logs/eventos do componente | confirmar ligacao runtime antes de uso critico |

## Detailed API

### Preserved technical reference (normalized from previous revision)

### 1. Visao Geral e Quando Usar
`form-json-config-editor` e a superficie de edicao JSON direta para `FormConfig`.
Ele oferece validacao local, formatacao, aplicacao manual de JSON e eventos de telemetria do editor.

Use quando precisar de:
- edicao avancada/manual de schema de formulario;
- validacao continua de JSON com debounce;
- fluxo explicito de "validar -> aplicar";
- apoio didatico para hooks e validacao reativa via atalhos no proprio editor.

### 2. Contrato da API

#### 2.1 Inputs
| Input | Tipo | Padrao | Obrigatorio | Status | Comportamento |
| --- | --- | --- | --- | --- | --- |
| `config` | `FormConfig \| null` | `null` | Nao | Active | Se ausente, usa `FormConfigService.currentConfig`. |

#### 2.2 Outputs
| Output | Payload | Quando emite |
| --- | --- | --- |
| `configChange` | `FormConfig` | Apenas em `applyJsonChanges()` com JSON valido. |
| `validationChange` | `JsonValidationResult` | Em cada ciclo de validacao (debounce 300ms). |
| `editorEvent` | `JsonEditorEvent` | Eventos `validation`, `format` e `apply`. |

Tipos relevantes:

```ts
interface JsonValidationResult {
  isValid: boolean;
  error?: string;
  config?: FormConfig;
}

interface JsonEditorEvent {
  type: 'apply' | 'format' | 'validation';
  payload: JsonValidationResult;
}
```

### 3. Mapeamento de Comportamento
- Validacao:
  - `onJsonTextChange` envia para subject interno com debounce de 300ms.
  - `validateJson` exige objeto JSON e chama `FormConfigService.validateConfig`.
- Aplicacao:
  - `applyJsonChanges` so aplica quando `isValidJson=true`.
  - Em sucesso: `loadConfig` no service + `configChange` + `editorEvent(type='apply')`.
- Formatacao:
  - `formatJson` reformata com `JSON.stringify(parsed, null, 2)`.
- Helpers de produtividade:
  - `insertHooksTemplate()` adiciona exemplos em `hooks.beforeValidate/beforeSubmit`.
  - `enableReactiveValidation()` injeta `behavior.reactiveValidation=true` com debounce padrao.

Cobertura de paths JSON:
- `Active`: todo objeto que passa em `validateConfig`.
- `Partial`: validacao estrutural/funcional depende do escopo de regras de `FormConfigService.validateConfig`.

### 4. Exemplo Minimo
```html
<form-json-config-editor
  [config]="formConfig"
  (validationChange)="onJsonValidation($event)"
  (configChange)="onJsonApply($event)"
></form-json-config-editor>
```

### 5. Exemplo Corporativo (telemetria + gate de aplicacao)
```ts
onJsonValidation(result: JsonValidationResult) {
  this.canApply = result.isValid;
}

onEditorEvent(event: JsonEditorEvent) {
  audit.log('form-json-editor', event.type, { valid: event.payload.isValid });
}
```

```html
<form-json-config-editor
  [config]="workingConfig"
  (validationChange)="onJsonValidation($event)"
  (editorEvent)="onEditorEvent($event)"
  (configChange)="commitDraft($event)"
></form-json-config-editor>
```

### 6. Problemas Comuns e Armadilhas
1. Esperar `configChange` a cada digitacao.
Correcao: `configChange` so sai em `Aplicar JSON`.

2. Tratar `isValidJson` como garantia de regra de negocio final.
Correcao: e validacao do contrato local; politica de negocio continua no host/backend.

3. Aplicar JSON sem observar `validationChange`.
Correcao: use `validationChange` para controlar UX de bloqueio/liberacao.

4. Assumir que `formatJson` corrige erros semanticos.
Correcao: formatacao so normaliza indentacao; nao corrige contrato invalido.

5. Sobrescrever config corrente sem versionamento/auditoria.
Correcao: em ambiente corporativo, registre diff e origem antes de persistir.

6. Usar helpers (`insertHooksTemplate`, `enableReactiveValidation`) como contrato final.
Correcao: sao aceleradores de autoria, nao template normativo obrigatorio.

### 7. Referencias Cruzadas
- Orquestrador superior: `projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts`
- Service de validacao/carga: `projects/praxis-dynamic-form/src/lib/services/form-config.service.ts`
- Modelo base: `projects/praxis-core/src/lib/models/form/form-config.model.ts`

### 8. Premissas
- O host controla persistencia definitiva do JSON aplicado.
- O editor nao executa hooks nem simula submit; apenas valida/edita configuracao.
- Integracao corporativa deve incluir rastreio de alteracoes (quem/quando/o que).

### 9. Relatorio de Validacao Estrutural
- Visao geral: PASS
- Inputs/outputs e tipos de evento: PASS
- Mapeamento de comportamento: PASS
- Exemplo minimo: PASS
- Exemplo corporativo: PASS
- Problemas comuns (>=5): PASS
- Referencias cruzadas: PASS
- Premissas explicitas: PASS

## JSON path index

| Path | Type | Required | Default | Status | Notes |
| --- | --- | --- | --- | --- | --- |
| `$` | `FormConfig` | Yes | `{ "sections": [] }` | Active | Raiz do JSON editado e emitido por `configChange`. |
| `sections[]` | `FormSection[]` | Conditional | `[]` | Active | Estrutura principal do formulário validada localmente via parse/JSON. |
| `behavior.reactiveValidation` | `boolean` | No | `false` | Partial | Pode ser inserido pelo helper `enableReactiveValidation()`. |
| `behavior.reactiveValidationDebounceMs` | `number` | No | `300` | Partial | Usado como sugestão de configuração no helper de validação reativa. |
| `hooks.*` | `object` | No | n/a | Partial | Pode ser inserido por `insertHooksTemplate()` para acelerar autoria. |

## Events

| Event | Payload | Trigger | Stability | Notes |
| --- | --- | --- | --- | --- |
| `configChange` | `FormConfig` | Apenas em `applyJsonChanges()` com JSON valido. | Partial | Preservado da documentação anterior. |
| `validationChange` | `JsonValidationResult` | Em cada ciclo de validacao (debounce 300ms). | Partial | Preservado da documentação anterior. |
| `editorEvent` | `JsonEditorEvent` | Eventos `validation`, `format` e `apply`. | Partial | Preservado da documentação anterior. |

## Styling API

| Token/Class | Scope | Purpose | Notes |
| --- | --- | --- | --- |
| `.json-config-editor` | root container | layout principal do editor JSON | Container flex de alto nível para card + editor. |
| `.educational-card` | summary card | contexto educacional e status de uso | Card introdutório com destaque visual e orientação de uso. |
| `.json-editor-toolbar` | toolbar | ações de refresh/format/apply e templates | Barra de ações com fallback responsivo para telas menores. |
| `.json-textarea` | editor field | edição monoespaçada de JSON | Ajusta fonte, overflow e legibilidade para payloads longos. |
| `.badge.ok/.err/.warn` | status badges | feedback de validação e alteração | Estado visual de JSON válido/inválido e mudanças pendentes. |

## Editor and tooling notes

- Cobertura de editor/tooling foi separada da cobertura de runtime para evitar confusao de suporte.
- Quando nao houver evidencia direta no codigo, o status deve permanecer not yet verified.

## Examples

### Minimal valid

```json
{
  "sections": []
}
```

### Typical/common

```json
{
  "sections": [
    {
      "id": "main",
      "title": "Dados",
      "rows": []
    }
  ],
  "actions": []
}
```

### Advanced

```json
{
  "sections": [],
  "behavior": {
    "reactiveValidation": true,
    "reactiveValidationDebounceMs": 300
  },
  "hooks": {
    "beforeSubmit": [
      {
        "type": "custom",
        "handler": "sanitizePayload"
      }
    ]
  }
}
```

### Enterprise scenario

```json
{
  "sections": [],
  "metadata": {
    "version": "2026.03",
    "owner": "platform-team"
  },
  "behavior": {
    "reactiveValidation": true,
    "reactiveValidationDebounceMs": 500
  },
  "hooks": {
    "beforeSubmit": [
      {
        "type": "custom",
        "handler": "auditBeforeSubmit"
      }
    ]
  }
}
```

## Known limitations and mismatches

| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
| --- | --- | --- | --- | --- | --- |
| none-reported | Nenhum mismatch explícito detectado na evidência preservada. | Manter monitoramento contínuo. | Baixo | n/a | n/a |

## Compatibility and migration notes

| Concern | Affected versions | Migration action | Deadline | Notes |
| --- | --- | --- | --- | --- |
| legacy aliases and mixed status vocabulary | pre-canonical docs | unificar para taxonomia canonica (Active/Partial/Declared-only/...) | next-doc-cycle | manter backward compatibility documentada |

## Source references

| Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
| --- | --- | --- | --- | --- |
| local-file | projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
| local-file | projects/praxis-dynamic-form/src/lib/json-config-editor/json-config-editor.component.spec.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
| local-file | projects/praxis-dynamic-form/src/lib/services/form-config.service.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
| local-file | projects/praxis-core/src/lib/models/form/form-config.model.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
