oneOf, allOf, anyOf

oneOf, anyOf y allOf son palabras clave de la especificación JSON Schema que se utilizan para definir estructuras de datos compuestas. Son, esencialmente, operadores lógicos aplicados a la validación de datos. Apidog admite plenamente estas funciones de JSON Schema, lo que le ayuda a crear documentación de API y reglas de validación de datos más precisas.

Conceptos básicos

allOf

allOf significa que los datos deben satisfacer simultáneamente todas las condiciones de los subesquemas, lo que equivale a la operación AND en las operaciones lógicas. Al igual que la expresión «tanto... como...» en el lenguaje cotidiano, todas las condiciones deben cumplirse simultáneamente para que la validación se apruebe.

anyOf

oneOf

Tabla de comparación lógica

Palabra clave	Operación lógica	Requisito de condición	Caso de uso típico
`allOf`	AND	Debe satisfacer todas las condiciones simultáneamente	Herencia, extensión
`anyOf`	OR	Debe satisfacer al menos una condición	Combinaciones opcionales
`oneOf`	XOR	Debe satisfacer exactamente una condición	Opciones mutuamente excluyentes

Uso en Apidog

1. Uso del editor visual

Paso 1: Crear esquemas de datos

En su proyecto, haga clic en "Schemas" y, a continuación, en "New Schema".

Paso 2: Añadir composición de esquemas

En el panel de edición del esquema de datos, al seleccionar el tipo, haga clic en "Schema Composition" y elija oneOf, anyOf o allOf. Defina estructuras de datos específicas para cada subesquema.

2. Uso del editor de código JSON Schema

También puede editar directamente el código JSON Schema en el panel de edición del esquema de datos para definir estos patrones de composición lógica.

Aplicación en la documentación de API

Definición de parámetros de petición

Al definir parámetros de petición de endpoint, puede utilizar estos patrones de composición para describir estructuras de parámetros complejas:

Acceda a la página de edición de la API.

En la sección "Request Parameters", seleccione Body y elija el tipo JSON.

En la estructura de datos, haga clic en "Reference Schema", o seleccione la "Schema Composition" adecuada según la lógica de negocio, o defina un JSON Schema personalizado.

Composición de esquemas de parámetros de petición

Definición de datos de respuesta

Del mismo modo, puede utilizar esta composición de esquemas en los datos de respuesta:

En la sección "Response", añada ejemplos de respuesta.

Utilice la composición de esquemas para describir diferentes formatos de respuesta.

Ejemplos prácticos de uso

Ejemplo de allOf (operación AND)

El uso de allOf le permite combinar varios esquemas de datos, lo que exige que los datos satisfagan todas las condiciones simultáneamente. Es como decir «la información del usuario debe incluir información básica AND información de contacto»:

{
  "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: Los datos finales deben contener los campos id, name y email, mientras que phone es opcional. Todas las restricciones de los subesquemas se combinan y ejecutan, como se muestra a continuación:

Ejemplo de anyOf (operación OR)

El uso de anyOf proporciona varias rutas de validación opcionales: los usuarios pueden elegir uno o varios métodos. Es como decir «los usuarios pueden iniciar sesión mediante nombre de usuario/contraseña OR correo electrónico/contraseña OR teléfono/código de verificación»:

{
  "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: Los usuarios pueden proporcionar información para uno o varios métodos de inicio de sesión, siempre que al menos un método satisfaga los requisitos de validación, como se muestra a continuación:

Ejemplo de oneOf (operación XOR)

El uso de oneOf garantiza que los usuarios solo puedan elegir un método de pago y que no puedan proporcionar varios métodos simultáneamente. Es como decir «el método de pago debe ser tarjeta de crédito XOR PayPal XOR transferencia bancaria: exactamente una de estas opciones»:

{
  "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: Los usuarios deben elegir exactamente un método de pago: no pueden proporcionar varios métodos simultáneamente ni tampoco omitirlos todos, como se muestra a continuación:

Prácticas recomendadas

Al elegir patrones de composición, primero aclare su lógica de negocio:

Si necesita combinar/heredar varios esquemas → Use allOf (operación AND)

Si necesita combinaciones opcionales flexibles → Use anyOf (operación OR)

Si necesita opciones estrictamente mutuamente excluyentes → Use oneOf (operación XOR)

Conceptos básicos#

Tabla de comparación lógica#

Uso en Apidog#

1. Uso del editor visual#

2. Uso del editor de código JSON Schema#

Aplicación en la documentación de API#

Definición de parámetros de petición#

Definición de datos de respuesta#

Ejemplos prácticos de uso#

Ejemplo de allOf (operación AND)#

Ejemplo de anyOf (operación OR)#

Ejemplo de oneOf (operación XOR)#

Prácticas recomendadas#