JSON Schema

Keywords como type, properties, required, additionalProperties, minimum, maximum, pattern e enum descrevem quais instâncias são aceitas. Um comando de termostato pode exigir target_c entre 16 e 30, mode em heat, cool ou off e request_id em formato UUID. O validador deve usar o dialect declarado em $schema. Drafts possuem diferenças; uma keyword desconhecida pode ser ignorada em vez de falhar. Por isso, a versão precisa ser fixada. JSON distingue number, integer, string, boolean, object, array e null, mas não distingue int32 de int64. Formatos como date-time são anotações ou validações opcionais, conforme a implementação. O contrato deve testar o validador real. additionalProperties false reduz campos inesperados, porém dificulta evolução; unevaluatedProperties pode oferecer controle mais preciso em composição.

$defs armazena schemas reutilizáveis, e $ref aponta a um URI ou fragmento. Identificadores com $id estabelecem base de resolução. Isso permite definir entidade, timestamp e qualidade uma vez. Referências podem ser locais, remotas ou empacotadas. Dependência remota em tempo de execução é arriscada: indisponibilidade ou alteração do schema quebra validação. Produção deve resolver e fixar versões. Referências circulares são permitidas em modelos recursivos, mas nem todas as ferramentas geram código bem. Em uma árvore de dispositivos, recursão pode ser adequada. Em payloads simples de IoT, prefira clareza. URLs de $id identificam; não precisam necessariamente ser buscadas, dependendo do resolver. Não use um endereço mutável para versões diferentes.

allOf exige todos os subschemas; anyOf aceita um ou mais; oneOf exige exatamente um; not exclui. if/then/else aplica regras condicionais. Um dispositivo pode ter base comum e variantes por type. Se type é dimmer, brightness é obrigatório; se switch, brightness pode ser proibido. Composição melhora expressividade, mas pode gerar mensagens de erro complexas e schemas difíceis de manter. oneOf com variantes sobrepostas é fonte de falhas porque duas podem validar. Use discriminador explícito. allOf não é herança orientada a objetos e não mescla properties automaticamente; additionalProperties em um subschema pode bloquear campos de outro. Draft 2020‑12 e unevaluatedProperties ajudam, mas o autor precisa compreender avaliação.

title, description, default, examples, deprecated, readOnly e writeOnly documentam e alimentam interfaces. O validador normalmente não injeta default; a aplicação decide. Confundir default com valor automático gera divergência. readOnly e writeOnly são anotações usadas por OpenAPI e geradores, não uma política de acesso por si. Exemplos devem incluir unidade e casos de borda. A descrição precisa declarar semântica, como “temperatura do ar em °C, resolução 0,1 °C, UTC”. JSON Schema não possui unidade nativa universal; pode-se usar extensão ou objeto value/unit. A documentação deve distinguir valor ausente de null. Um campo nullable é representado por type [number, null] em JSON Schema puro.

A keyword $schema identifica o metaschema e o dialect. Draft 2020‑12 organiza vocabulários de core, applicator, validation, unevaluated, format annotation e content. Implementações podem suportar subconjuntos. O metaschema valida a forma do schema, mas não prova que o modelo representa o domínio. Vocabulários customizados podem adicionar unidade, classificação ou políticas, porém reduzem portabilidade. Ferramentas que não conhecem a extensão podem ignorar. Em integrações de casa inteligente, extensões devem ser prefixadas, documentadas e evitadas no núcleo quando uma estrutura padrão resolve. A validação do schema em CI previne erros de keyword e referência.