oneOf, allOf, anyOf

oneOf, anyOf e allOf são palavras-chave na especificação JSON Schema usadas para definir estruturas de dados compostas. Elas são essencialmente operadores lógicos aplicados à validação de dados. O Apidog oferece suporte completo a esses recursos do JSON Schema, ajudando você a criar documentação de API e regras de validação de dados mais precisas.

Conceitos básicos

allOf

allOf significa que os dados devem satisfazer simultaneamente todas as condições dos subesquemas, equivalente à operação AND em operações lógicas. Assim como a expressão "tanto... quanto..." na linguagem cotidiana, todas as condições devem ser atendidas simultaneamente para que a validação seja aprovada.

anyOf

oneOf

Tabela de comparação lógica

Palavra-chave	Operação lógica	Requisito da condição	Caso de uso típico
`allOf`	AND	Deve satisfazer todas as condições simultaneamente	Herança, extensão
`anyOf`	OR	Deve satisfazer pelo menos uma condição	Combinações opcionais
`oneOf`	XOR	Deve satisfazer exatamente uma condição	Escolhas mutuamente exclusivas

Uso no Apidog

1. Usando o editor visual

Etapa 1: Criar esquemas de dados

No seu projeto, clique em "Schemas" e, em seguida, em "New Schema".

Etapa 2: Adicionar composição de esquema

No painel de edição do esquema de dados, ao selecionar o tipo, clique em "Schema Composition" e escolha oneOf, anyOf ou allOf. Defina estruturas de dados específicas para cada subesquema.

2. Usando o editor de código JSON Schema

Você também pode editar diretamente o código JSON Schema no painel de edição do esquema de dados para definir esses padrões de composição lógica.

Aplicação na documentação de API

Definição de parâmetros da requisição

Ao definir parâmetros de requisição do endpoint, você pode usar esses padrões de composição para descrever estruturas de parâmetros complexas:

Acesse a página de edição da API.

Na seção "Request Parameters", selecione Body e escolha o tipo JSON.

Na estrutura de dados, clique em "Reference Schema", ou selecione a "Schema Composition" apropriada com base na lógica de negócios, ou defina um JSON Schema personalizado.

Composição de esquema de parâmetros da requisição

Definição de dados da resposta

Da mesma forma, você pode usar essa composição de esquema nos dados da resposta:

Na seção "Response", adicione exemplos de resposta.

Use a composição de esquema para descrever diferentes formatos de resposta.

Exemplos práticos de uso

Exemplo de allOf (operação AND)

Usar allOf permite combinar vários esquemas de dados, exigindo que os dados satisfaçam todas as condições simultaneamente. É como dizer "as informações do usuário devem incluir informações básicas AND informações de contato":

{
  "allOf": [
    {
      "description": "Basic user information",
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"]
    },
    {
      "description": "Contact information", 
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "phone": { "type": "string" }
      },
      "required": ["email"]
    }
  ]
}

Resultado: Os dados finais devem conter os campos id, name e email, sendo phone opcional. Todas as restrições dos subesquemas são mescladas e executadas, conforme mostrado abaixo:

Exemplo de anyOf (operação OR)

Usar anyOf fornece vários caminhos de validação opcionais — os usuários podem escolher um ou vários métodos. É como dizer "os usuários podem fazer login com nome de usuário/senha OR email/senha OR telefone/código de verificação":

{
  "type": "object",
  "properties": {
    "login": {
      "anyOf": [
        {
          "description": "Username/password login",
          "properties": {
            "username": { "type": "string" },
            "password": { "type": "string" }
          },
          "required": ["username", "password"]
        },
        {
          "description": "Email/password login",
          "properties": {
            "email": { "type": "string", "format": "email" },
            "password": { "type": "string" }
          },
          "required": ["email", "password"]
        },
        {
          "description": "Phone/verification code login",
          "properties": {
            "phone": { "type": "string" },
            "verifyCode": { "type": "string" }
          },
          "required": ["phone", "verifyCode"]
        }
      ]
    }
  }
}

Resultado: Os usuários podem fornecer informações para um ou vários métodos de login, desde que pelo menos um método satisfaça os requisitos de validação, conforme mostrado abaixo:

Exemplo de oneOf (operação XOR)

Usar oneOf garante que os usuários possam escolher apenas um método de pagamento e não possam fornecer vários métodos simultaneamente. É como dizer "o método de pagamento deve ser cartão de crédito XOR PayPal XOR transferência bancária — exatamente uma dessas opções":

{
  "type": "object", 
  "properties": {
    "payment": {
      "oneOf": [
        {
          "description": "Credit card payment",
          "type": "object",
          "properties": {
            "type": { "const": "credit_card" },
            "cardNumber": { "type": "string" },
            "expiryDate": { "type": "string" }
          },
          "required": ["type", "cardNumber", "expiryDate"],
          "additionalProperties": false
        },
        {
          "description": "PayPal payment", 
          "type": "object",
          "properties": {
            "type": { "const": "paypal" },
            "email": { "type": "string", "format": "email" }
          },
          "required": ["type", "email"],
          "additionalProperties": false
        },
        {
          "description": "Bank transfer",
          "type": "object", 
          "properties": {
            "type": { "const": "bank_transfer" },
            "accountNumber": { "type": "string" },
            "routingNumber": { "type": "string" }
          },
          "required": ["type", "accountNumber", "routingNumber"],
          "additionalProperties": false
        }
      ]
    }
  }
}

Resultado: Os usuários devem escolher exatamente um método de pagamento — eles não podem fornecer vários métodos simultaneamente, nem deixar de fornecer todos, conforme mostrado abaixo:

Melhores práticas

Ao escolher padrões de composição, primeiro esclareça sua lógica de negócios:

Precisa combinar/herdar vários esquemas → Use allOf (operação AND)

Precisa de combinações opcionais flexíveis → Use anyOf (operação OR)

Precisa de escolhas estritamente mutuamente exclusivas → Use oneOf (operação XOR)

Conceitos básicos#

Tabela de comparação lógica#

Uso no Apidog#

1. Usando o editor visual#

2. Usando o editor de código JSON Schema#

Aplicação na documentação de API#

Definição de parâmetros da requisição#

Definição de dados da resposta#

Exemplos práticos de uso#

Exemplo de allOf (operação AND)#

Exemplo de anyOf (operação OR)#

Exemplo de oneOf (operação XOR)#

Melhores práticas#