Esquema JSON em solicitações

Um Esquema JSON descreve declarativamente o formato de uma saída válida: tipos, chaves obrigatórias, restrições de valores e aninhamento. Quando transmitido a uma API de saída estruturada, ele se torna um contrato rígido; quando incorporado a uma instrução, torna-se uma orientação forte.

Dominar a autoria de esquemas é a habilidade central da geração estruturada.

No modo rigoroso, os provedores exigem que toda propriedade seja listada em required e que additionalProperties seja false. Os campos opcionais são expressos como uma união com null, e não por omissão.

Inclua a validação no esquema em vez de fazer pós-processamento:

• enum para escolhas fixas.
• minimum/maximum para intervalos numéricos.
• pattern para cadeias de caracteres validadas por expressões regulares.
• format para indicações como date-time ou email.

Use items para vetores homogêneos e adicione minItems/maxItems para limitar o comprimento. Para tuplas posicionais, forneça um vetor de esquemas por meio de prefixItems.

Modele resultados polimórficos com oneOf e um campo discriminador. O modelo escolhe exatamente um ramo, e seu desserializador seleciona com base na etiqueta.

Escrever esquemas manualmente é propenso a erros. Derive-os de modelos tipados para que o esquema e seu código nunca se afastem um do outro.

Cada description no esquema é lida pelo modelo. Use-as para orientar a semântica, não apenas para documentar campos.

Por exemplo, uma descrição como 'código de país ISO-3166 alfa-2, em letras maiúsculas' melhora significativamente a acurácia do campo. Trate as descrições como microinstruções incorporadas ao contrato.

Quando o provedor não oferece suporte nativo, incorpore o esquema à instrução e exija conformidade. Combine-o com um único exemplo no contexto e uma instrução explícita de somente JSON, sem prosa.

Esquemas excessivamente profundos ou ramificados confundem o modelo e aumentam o custo de tokens. Orientações:

• Mantenha o aninhamento superficial; reduza os níveis sempre que possível.
• Prefira enumerações a cadeias de caracteres livres.
• Divida um esquema enorme em várias chamadas focadas.
• Alguns provedores limitam a profundidade do aninhamento e o número total de propriedades; verifique os limites.

Use $defs e $ref para reutilizar subesquemas, por exemplo, um Address usado no faturamento e no envio. Observe que alguns modos rigorosos restringem a profundidade da recursão; portanto, verifique o suporte antes de depender de referências autorreferentes.

Há uma classe sutil de erros: o esquema está malformado, não a saída. Use validate para verificar os esquemas na integração contínua em relação ao metamodelo do Esquema JSON e faça uma verificação de ida e volta com um objeto de exemplo por meio do seu validador antes de publicar.

Agora você consegue criar esquemas precisos:

• O modo rigoroso exige que todos os campos sejam obrigatórios e que additionalProperties seja falso.
• Restrinja escalares com enumerações, intervalos, padrões e formatos.
• Modele o polimorfismo com discriminadores oneOf.
• Gere esquemas a partir de modelos tipados; trate as descrições como microinstruções.
• Valide o próprio esquema na integração contínua.

A seguir: aplicando esquemas a chamadas de ferramentas e funções.