Tipos, propriedades e campos obrigatórios

A maioria dos schemas começa com objetos. Objetos JSON viram contratos úteis quando você descreve suas propriedades e decide quais campos são obrigatórios.

{
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "profile": {
      "type": "object",
      "properties": {
        "displayName": { "type": "string" }
      },
      "required": ["displayName"]
    }
  },
  "required": ["email", "profile"]
}

type

A palavra-chave type descreve primitivos e contêineres JSON:

• object
• array
• string
• number
• integer
• boolean
• null

Use integer apenas quando frações forem inválidas. Use number para decimais, como preços, coordenadas e proporções.

properties

properties mapeia nomes de campos para schemas. Cada propriedade pode ter seu próprio tipo e restrições aninhadas.

Objetos aninhados devem ser modelados com intenção. Se um valor aninhado tem campos significativos, dê a ele um bloco de schema em vez de deixá-lo como um object genérico.

required

required é um array com nomes de propriedades que precisam existir. Um erro comum é achar que toda propriedade listada em properties é obrigatória automaticamente. Não é.

Isso permite descrever campos opcionais sem forçar clientes a enviá-los:

{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "subtitle": { "type": "string" }
  },
  "required": ["title"]
}

Obrigatório não significa não vazio

Uma string obrigatória ainda pode ser vazia, a menos que você adicione minLength.

{ "type": "string", "minLength": 1 }

Pense em required como regra de presença. Pense em minLength, minimum e pattern como regras de valor.