ADR-21: Contratos JSON para validação de entities
Status: Aceito Data: 2026-04-21
Contexto
O pipeline terms→LinkML→PHP (ADR-20) gera código a partir de definições canônicas em YAML. Porém, a distância entre a declaração do term e o objeto final dificulta validação visual: o term descreve semântica, o MANUAL block descreve atributos, e o PHP gerado materializa tudo — mas nenhum artefato mostra como o objeto realmente se parece em runtime.
Antes de investir em MANUAL blocks e geração PHP, é necessário validar a forma esperada de cada entity de modo independente, visual e testável.
Decisão
Cada aggregate root materializable terá um par de contratos JSON (persistência + API) em .vigim/ddd/json-schema/contract/{aggregate}/. Cada par consiste em:
- JSON Schema (Draft 2020-12) — contrato formal com types, required, enums, descrições
- JSON example — objeto com dados fictícios realistas para validação visual
Camadas
| Camada | Escopo | Arquivo |
|---|---|---|
persistence |
Como o objeto vive no backend (EAV/banco) | {identifier}.persistence.schema.json + {identifier}.persistence.example.json |
api |
Como o objeto é entregue ao frontend (NextJS) | {identifier}.api.schema.json + {identifier}.api.example.json |
Regras
- Um diretório por aggregate root; filhos ficam em
children/dentro do mesmo diretório - 1 contrato persistence = 1 registro no banco (EAV); se o objeto precisar de mais de um registro, deve ser separado em outro aggregate/contrato
- Contratos são escritos manualmente e validados pelo humano — não são gerados
- Contratos não substituem terms nem LinkML — são artefatos complementares e independentes
- O contrato testa o que o term deveria ser, permitindo confrontar e anotar divergências
- Cada contrato tem limite de escopo: se crescer demais, deve ser separado
- Contratos evoluem conforme a necessidade — revisitar e melhorar é parte do ciclo
- Nomes de campos em
snake_case, alinhados ao PHP e terms $idseguehttps://docs.helico.com.br/schema/contract/{aggregate}/{layer}
Nomes de arquivo
Todos os arquivos de contrato seguem o padrão {identifier}.{layer}.{type}.json:
{identifier}— identifier do term (snake_case){layer}—persistenceouapi{type}—schemaouexample
Isso vale tanto para o aggregate root quanto para filhos em children/.
Estrutura
.vigim/ddd/json-schema/contract/
README.md
{aggregate}/
{identifier}.persistence.schema.json
{identifier}.persistence.example.json
{identifier}.api.schema.json
{identifier}.api.example.json
children/ ← quando o aggregate tem filhos
{child}.persistence.schema.json
{child}.persistence.example.json
...Decisões de design
Video e audio no content_bank (não info)
Vídeo da Unidade e Áudios da Unidade são filhos de Informações Gerais da Unidade na árvore de terms, mas nos contratos JSON vivem na seção content_bank do unit_content, não na seção info. Motivo: info é editorial puro (texto/referências), enquanto content_bank organiza assets com tags enum para classificação, hashing granular e vínculos via relations. Video e audio são assets consumíveis com metadados de mídia (url, duration, tags) — a seção content_bank é o local correto para esse tipo de estrutura.
Ciclo de trabalho
1. Escolher aggregate root
2. Redigir contrato persistence (schema + example)
3. Redigir contrato api (schema + example)
4. Validar visualmente com o humano
5. Confrontar com term existente — anotar divergências
6. Ajustar term/MANUAL block se necessário
7. Commit atômico do contrato validadoConsequências
- Validação visual antes de investir em MANUAL blocks e geração PHP
- Especificação consumível pelo frontend (NextJS) independente do LinkML
- Separação explícita entre camada de persistência e camada de API
- Contratos testáveis com ferramentas JSON Schema padrão
- Artefato adicional a manter manualmente
- Risco de drift entre contrato e term/LinkML se não confrontados regularmente
ADRs relacionados
- ADR-20 — Pipeline terms→LinkML→PHP — o contrato JSON complementa este pipeline.
- ADR-30 — Domínio Content — informa quais entities precisam de contrato.
- ADR-10 — Persistência EAV e critérios de uso — define o modelo de persistência que o contrato persistence reflete.
Histórico
Renumerado de ADR-902.