Manual de JSON Schema

O que é: um esquema rascunho 2020-12 sobre uma lista de campos que alguém já confirmou - validando a estrutura, nunca inventando regras de negócio.

Visão Geral

Produz JSON Schema a partir de uma lista canônica de campos confirmada, para validação, contratos de API, estruturas de importação e exportação, geração de formulários e documentação de esquemas.

JSON Schema valida a estrutura. Ele não computa, decide ou implica. Este é um auxiliar: ele não define sua própria tabela e renderiza qualquer lista de campos que o módulo ativo já confirmou, portanto, os nomes das propriedades aqui são os nomes que o módulo usa em seu mapeamento CSV, SQL, planilha e Notion.

Camada: n/a. Encaixa-se: em todas as fases. Código da tabela: n/a - renderiza a tabela do módulo ativo.

Quando Usar Esta Habilidade

• Preciso de um JSON Schema
• validar esta carga antes que ela entre
• criar um contrato de API para esta tabela
• documentar a forma deste arquivo de importação
• gerar um formulário a partir deste esquema
• transformar os campos acordados em um esquema

Use-o também quando um módulo confirmou uma lista de campos e o usuário deseja o contrato para o sistema que irá lê-lo, em vez da própria tabela.

Não o use para adicionar validação que o negócio não solicitou. Um esquema é uma promessa sobre o que uma carga pode conter, e cada restrição nele rejeita dados reais.

Como Funciona

Siga o contrato de execução compartilhado. As regras específicas do módulo abaixo definem apenas campos de domínio, decisões, cálculos e restrições de segurança.

Passo 1 - Identificar a intenção

Leia a solicitação e escolha a intenção antes de perguntar qualquer coisa.

• "Preciso de um esquema" -> um esquema estrito ou permissivo, conforme o Passo 5.
• "algo rejeitou minha carga" -> revisar ou corrigir: apenas a regra que causou isso.
• "quais campos são obrigatórios" -> conselho: responda a partir da lista de campos confirmada e ofereça o esquema em vez de emitir um.

Construa apenas o que foi solicitado. Uma correção não se torna uma reescrita, e um conselho não se torna um arquivo.

Passo 2 - Pergunte apenas o que está faltando

Reutilize tudo o que já foi confirmado, inclusive pelo módulo que possui a lista de campos: os nomes e tipos das propriedades, as opções de seleção, os campos de data e moeda, os campos calculados, os status e os IDs. Nunca pergunte novamente por informações que o usuário já forneceu.

Faça uma pergunta curta por mensagem, e apenas quando a resposta alterar o esquema:

P: O esquema deve rejeitar campos desconhecidos ou permiti-los?

Nada mais vale uma pergunta. Obrigatoriedade, opções e formatos vêm da lista de campos confirmada, não de uma nova rodada de perguntas.

Passo 3 - Mantenha o contexto interno

Mantenha as respostas nesta forma. Ela permanece interna - não é mostrada ao usuário a menos que ele peça, e nunca carrega um valor que o usuário não deu.

module: json-schema-manual
intent: null            # set in Step 1, one of: schema, review, fix, advice
source_module: null     # the module whose field list this renders
draft: "https://json-schema.org/draft/2020-12/schema"
additional_properties: null   # false | true - asked once, then held
example_instances: false
confirmed_facts: []     # only what the user actually said
open_questions: []      # the unanswered ones, in the order worth asking

source_module é o único campo que esta habilidade precisa e que uma habilidade de módulo não tem. Se for desconhecido, pergunte para qual tabela o contrato se destina, pois um esquema construído a partir de um palpite rejeita os dados reais.

Passo 4 - Recomende o menor fluxo de trabalho

Construa um artefato já solicitado sem perguntar novamente. Para solicitações apenas de conselho, dê uma recomendação curta e ofereça o artefato relevante.

Abordagem recomendada: um esquema de objeto, uma propriedade por campo confirmado, sem required que a lista de campos não marque como obrigatório, e sem enum que a lista de campos não defina. Rigor apenas onde o contrato está fechado.

Por que este: o dano de um esquema é assimétrico. Uma propriedade que ele omite passa dados que ninguém revisou; uma propriedade que ele marca como obrigatória, ou um enum que ele inventa, rejeita dados que eram perfeitamente válidos. Confirme as regras fechadas e permaneça em silêncio sobre o resto.

Fluxo de trabalho: Lista de campos confirmada -> Propriedades tipadas -> Obrigatoriedade aplicada da fonte -> (validado) -> Publicado como o contrato

Passo 5 - Construa apenas sob solicitação

Assim que o usuário pedir, emita o esquema como dados apenas. Mantenha a prosa fora dos dados legíveis por máquina; forneça links de arquivos e limitações materiais separadamente. Os nomes das propriedades vêm da lista de campos confirmada, idênticos ao CSV, SQL,

…