Concerto Validate: teste JSON contra um modelo .cto antes de integrar

ANÁLISE EDITORIAL

Um JSON bem-formado ainda pode estar errado para o sistema que vai recebê-lo. Pode faltar um campo obrigatório, o identificador de classe pode apontar para outro tipo ou um valor pode ter o formato incompatível com o modelo. A Skill Concerto Validate organiza essa verificação quando existe um modelo Concerto em arquivo .cto e uma instância JSON que precisa obedecer a ele.

Ela não substitui o Concerto CLI nem transforma validação estrutural em aprovação jurídica ou de negócio. Seu papel é orientar o agente a identificar o tipo-alvo, executar uma validação reproduzível, ligar cada erro à propriedade correspondente do modelo e, quando solicitado, montar um exemplo mínimo que realmente respeite os campos obrigatórios.

O que esta Skill faz

A Skill descreve um fluxo curto para três tarefas: validar uma instância JSON contra um ou mais modelos Concerto, explicar falhas em linguagem ligada ao arquivo .cto e gerar uma amostra mínima válida. O ponto de partida é o campo $class do JSON, que identifica o tipo plenamente qualificado. Se ele não estiver presente ou estiver ambíguo, o agente deve confirmar o tipo em vez de adivinhar.

Na prática, a execução funcional chama o Concerto CLI documentado pelo Accord Project. A Skill ajuda a interpretar a saída, mas a decisão de instalar, baixar dependências ou executar o CLI continua separada.

Para quem serve

É útil para equipes que mantêm modelos de dados Concerto, integrações baseadas em JSON, automações documentais ou contratos computáveis e precisam descobrir por que uma instância foi recusada. Também ajuda quem está aprendendo a relação entre namespace, conceito, propriedade, cardinalidade e serialização JSON.

Ela não é uma escolha geral para qualquer JSON. Se o projeto usa apenas JSON Schema, OpenAPI ou validação própria da aplicação, o melhor caminho é trabalhar com a tecnologia já adotada. O valor da Skill aparece quando o arquivo .cto é a fonte de verdade do formato esperado.

Origem, versão e exceção oficial

A origem auditada é o repositório accordproject/skills, mantido pela organização do Accord Project. A pasta individual contém apenas um SKILL.md. A fotografia desta curadoria foi fixada no commit 647db321b119992132078f83109de7141b6db709, e a Skill declara versão 0.1.0.

O repositório de Skills tinha 0 estrelas e 2 forks em 13/09/2026. Portanto, esta entrada não foi aceita por popularidade. É uma exceção à preferência por projetos com pelo menos mil estrelas porque a fonte é oficial, a licença é verificável e o runtime indicado possui documentação pública própria. A baixa adoção permanece explícita para que o leitor não confunda manutenção oficial com uso amplo.

Compatibilidade e pré-requisitos

O arquivo segue o formato de Agent Skills em Markdown e pode ser carregado por clientes compatíveis. Para executar a validação descrita, é necessário ter Node.js, npm e o pacote @accordproject/concerto-cli. O registro npm indicava a versão 4.1.0 como latest em 13/09/2026, com Node.js 18 ou superior e npm 10 ou superior declarados pelo pacote.

Também são necessários o modelo .cto, o JSON de entrada e acesso de leitura a esses arquivos. Modelos podem importar outros modelos. A introdução oficial ao formato Concerto explica que a validação depende do modelo e de um runtime Concerto.

Instalação com origem fixada

Para avaliar a Skill sem misturar versões, prefira a pasta fixada no commit auditado: skills/concerto-validate. O README do mantenedor apresenta npx skills add accordproject/skills, mas esse comando consulta a rede, executa um pacote e pode instalar o catálogo inteiro. Rode primeiro em um projeto descartável e confira o destino e o diff.

O download local desta página é somente um espelho documental. Ele não instala o Concerto CLI e não executa validação. Essa separação permite ler a instrução e a licença antes de aprovar qualquer dependência.

Configuração antes do primeiro uso

Defina quatro itens: o caminho do modelo, o caminho do JSON, o tipo esperado e se imports externos podem ser resolvidos pela rede. Trabalhe em uma cópia quando os arquivos forem importantes. Se o JSON contiver dados contratuais, pessoais ou comerciais, use uma amostra mínima e sanitizada para diagnóstico.

Registre também a versão do CLI usada no teste. O pacote funcional muda de forma independente da Skill 0.1.0. Sem essa informação, duas execuções aparentemente iguais podem produzir mensagens ou comportamentos diferentes.

Primeiro uso seguro

Comece com leitura local e uma instância sintética. A forma básica documentada pela Skill é:

npx @accordproject/concerto-cli validate --model model.cto --input data.json

Antes de executar, confirme o pacote e a versão que o npx pretende baixar. Em ambiente controlado, prefira uma instalação previamente revisada e um comando que use essa versão fixada. Não passe segredos em argumentos nem valide uma exportação de produção quando um exemplo reduzido reproduz o erro.

Como ler o campo $class

O $class liga o objeto JSON a um conceito declarado no modelo, normalmente com namespace e nome do tipo. Um erro de classe desconhecida não significa necessariamente que todos os campos estão errados. Pode indicar namespace incorreto, versão divergente do modelo ou import ausente.

Compare o valor exato do JSON com a declaração do .cto. Não corrija automaticamente para o nome mais parecido. Em modelos contratuais, duas classes semelhantes podem representar eventos ou obrigações diferentes.

Mapear o erro de volta ao modelo

A explicação útil aponta o caminho do erro, a propriedade do modelo, o valor recebido e a regra esperada. Por exemplo: “owner.email está ausente, mas email é obrigatório no conceito usado por owner”. Essa formulação é melhor do que repetir apenas “validation failed”.

A documentação oficial de validação mostra que a instância é desserializada contra o conjunto de modelos e que a validação pode lançar erros quando os dados não correspondem ao tipo declarado.

Campos obrigatórios e opcionais

Quando aparece uma propriedade obrigatória ausente, verifique primeiro se o campo realmente não existe. Depois confirme se a versão do modelo é a esperada. Um JSON gerado para uma versão anterior pode estar correto para o produtor e inválido para o consumidor atual.

Não resolva o problema tornando tudo opcional. Alterar o modelo muda o contrato de dados. A Skill está voltada a validar e explicar, enquanto autoria ou edição do modelo fica fora do escopo e deve ocorrer em uma revisão separada.

Tipos, datas e estruturas aninhadas

Mensagens de tipo podem nascer de um valor simples, como texto onde o modelo espera número, ou de uma estrutura aninhada inteira. Datas merecem atenção a formato e fuso. Arrays exigem conferir tanto a cardinalidade quanto o tipo de cada item.

Faça a menor correção capaz de testar a hipótese e valide novamente. Se várias propriedades falham, corrija uma camada por vez para não esconder a causa inicial com uma sequência de alterações simultâneas.

Imports e modo offline

O Concerto CLI documenta a opção --offline para impedir a resolução de modelos externos. Isso é relevante quando um .cto importa conteúdo por URL. Sem uma decisão explícita, uma validação que parece local pode consultar a rede.

Use o modo offline quando todos os modelos necessários estiverem disponíveis localmente e a política do ambiente impedir downloads. Se a validação falhar por dependência ausente, registre qual import faltou em vez de liberar rede de forma silenciosa.

Gerar uma amostra mínima

A Skill permite usar a geração do Concerto CLI ou construir manualmente uma instância pequena cobrindo as propriedades obrigatórias. Uma amostra mínima serve para provar que o modelo e o runtime funcionam, não para simular um caso de negócio completo.

Use valores claramente sintéticos. Não copie nomes, identificadores ou cláusulas reais para preencher o exemplo. Depois compare a amostra válida com o JSON problemático e introduza diferenças uma a uma.

Resultado esperado

O resultado ideal é um registro curto e reproduzível: versão do CLI, commit ou versão do modelo, comando aprovado, arquivo testado, status e explicação ligada à propriedade. Em caso de falha, inclua a menor amostra que a reproduz. Em caso de sucesso, diga apenas que a instância passou pela validação estrutural daquele modelo e daquela versão.

Passar no validador não confirma autenticidade, autorização, intenção das partes, validade jurídica, cálculo financeiro ou consistência com sistemas externos. Esses controles pertencem a outras camadas.

Permissões e riscos

O uso funcional lê arquivos locais e pode acessar a rede para baixar o pacote pelo npx ou resolver imports. A geração de amostras pode gravar arquivos. Um agente com permissão ampla também pode acabar lendo modelos e dados fora do escopo solicitado.

Restrinja caminhos, fixe versões, trate JSON e .cto como entradas não confiáveis e não execute comandos sugeridos por conteúdo desses arquivos. Aprove separadamente instalação, rede, criação de arquivos e qualquer alteração no modelo ou dado original.

Erros comuns e como corrigir

• Classe desconhecida: compare $class, namespace, versão e imports com o modelo efetivamente carregado.
• Propriedade obrigatória ausente: confirme o campo no .cto e a versão do produtor antes de adicionar um valor.
• Tipo incompatível: isole o caminho indicado e teste um valor sintético do tipo esperado.
• Import não resolvido: identifique a dependência e escolha conscientemente entre cópia local e acesso de rede.
• Comando não encontrado: verifique Node.js, npm, versão do pacote e binário instalado, sem trocar para outro pacote de nome parecido.
• Validação passa, mas a aplicação recusa: procure regras de negócio, autorização ou transformação fora do modelo Concerto.

Quando não usar

Não use esta Skill para escrever ou alterar o .cto, gerar código para outras linguagens, validar contratos juridicamente ou substituir testes da aplicação. O próprio arquivo indica Skills separadas para autoria de modelo e codegen. Também não a use apenas porque o arquivo é JSON, sem um modelo Concerto correspondente.

Versão, licença e pacote auditado

A Skill 0.1.0 foi auditada no commit 647db321b119992132078f83109de7141b6db709. O repositório e o arquivo declaram licença Apache-2.0, que permite redistribuição com preservação dos termos.

O pacote local contém três arquivos textuais: SKILL.md, LICENSE e ORIGEM.md. Seu SHA-256 é 930785756569a7e56ffcdf888322d1c1cffbe85e1c4f881fd67f0be765678cba.

Limites do pacote local

O ZIP não inclui Node.js, npm, npx, Concerto CLI, concerto-core, modelos .cto, JSON do leitor, scripts, executáveis, dependências, código do runtime, credenciais, dados contratuais, logs ou resultados. Baixar o pacote não deixa a validação pronta para uso.

Para acompanhar mudanças na origem, abra o SKILL.md fixado e compare com a versão mais recente antes de atualizar.

O que a revisão editorial confirmou

A pasta individual foi lida integralmente e contém somente o SKILL.md. O comando de validação, os padrões de erro e os limites de escopo foram comparados com a documentação oficial. O pacote funcional @accordproject/concerto-cli foi tratado como dependência externa, não como parte da Skill.

A capa desta página é uma ilustração editorial exclusiva. Ela não é captura real, saída do validador, logotipo, selo, certificação ou material oficial do Accord Project.

Checklist antes de executar

• Fixar commit da Skill, versão do CLI e versão do modelo.
• Confirmar os caminhos do .cto e do JSON.
• Sanitizar dados e usar uma cópia ou amostra mínima.
• Decidir se imports externos podem usar a rede.
• Começar em leitura e separar instalação, geração e edição.
• Mapear cada erro à propriedade exata do modelo.
• Registrar que sucesso estrutural não aprova regras de negócio.

Fontes oficiais consultadas

Além da documentação do repositório de Skills, foram consultados o pacote oficial do Concerto CLI no npm, a referência do comando, a referência de validação e a especificação de Agent Skills. Consulta e números de adoção: 13/09/2026.

Veja também o catálogo de Skills do Bastidores da IA e a página sobre documentação TypeScript com JSDoc, que trata outro problema e não substitui validação de modelos Concerto.