Skip to content

ADR-21: Contratos JSON para validação de entities

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

  1. Um diretório por aggregate root; filhos ficam em children/ dentro do mesmo diretório
  2. 1 contrato persistence = 1 registro no banco (EAV); se o objeto precisar de mais de um registro, deve ser separado em outro aggregate/contrato
  3. Contratos são escritos manualmente e validados pelo humano — não são gerados
  4. Contratos não substituem terms nem LinkML — são artefatos complementares e independentes
  5. O contrato testa o que o term deveria ser, permitindo confrontar e anotar divergências
  6. Cada contrato tem limite de escopo: se crescer demais, deve ser separado
  7. Contratos evoluem conforme a necessidade — revisitar e melhorar é parte do ciclo
  8. Nomes de campos em snake_case, alinhados ao PHP e terms
  9. $id segue https://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} — persistence ou api
  • {type} — schema ou example

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 validado

Consequê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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close