JSON Schema OneOf Examples: A Complete Guide

JSON Schema OneOf is a powerful validation feature that allows you to specify that a value must match one of several possible schemas. This comprehensive guide will walk you through practical examples of implementing OneOf in your JSON schemas, helping you create more flexible and robust data validation rules.

What is JSON Schema OneOf?

The OneOf keyword in JSON Schema allows you to define an array of schemas, where a valid JSON data must conform to at least one of them. Unlike AllOf (which requires matching all schemas) or AnyOf (which allows matching any), OneOf enforces exclusivity - the data can only match one schema in the array.

Basic OneOf Syntax

The simplest OneOf implementation requires an array of schemas. Here's a basic example:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "value": {
      "oneOf": [
        {"type": "string"},
        {"type": "number"},
        {"type": "boolean"}
      ]
    }
  }
}

This schema validates that the "value" property can be either a string, number, or boolean, but not a combination of these types.

OneOf with Multiple Schemas

For more complex scenarios, you can define detailed schemas within the OneOf array:

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {"const": "user"},
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"}
      },
      "required": ["type", "name", "email"]
    },
    {
      "type": "object",
      "properties": {
        "type": {"const": "admin"},
        "username": {"type": "string"},
        "permissions": {"type": "array"}
      },
      "required": ["type", "username", "permissions"]
    }
  ]
}

This example validates either a user object with name and email, or an admin object with username and permissions.

OneOf with Required Properties

You can combine OneOf with required properties to enforce specific field combinations:

{
  "oneOf": [
    {
      "properties": {
        "payment_method": {"const": "credit_card"},
        "card_number": {"type": "string"},
        "expiry_date": {"type": "string", "format": "date"}
      },
      "required": ["payment_method", "card_number", "expiry_date"]
    },
    {
      "properties": {
        "payment_method": {"const": "bank_transfer"},
        "account_number": {"type": "string"},
        "routing_number": {"type": "string"}
      },
      "required": ["payment_method", "account_number", "routing_number"]
    }
  ]
}

This ensures that payment data must use either credit card details or bank transfer information, with all required fields present for each method.

OneOf in Real-World Applications

OneOf is particularly useful in API design where you need to handle multiple response formats or data structures. For example, an API might return either a success response with data or an error response with error details. Using OneOf allows you to validate both possibilities in a single schema.

Another common use case is handling polymorphic data, where an object can be of different types but share some common properties. OneOf enables you to define specific schemas for each type while maintaining a consistent interface.

Common Pitfalls and Best Practices

When implementing OneOf, be aware that schemas must be mutually exclusive. If multiple schemas could match the same data, validation becomes ambiguous. Always test your OneOf schemas thoroughly to ensure they behave as expected.

Best practices include keeping schemas simple, using descriptive property names, and providing clear error messages. Document your OneOf schemas thoroughly so developers understand the validation rules.

FAQ Section

Q: How does OneOf differ from AnyOf?

A: OneOf requires the data to match exactly one schema in the array, while AnyOf allows matching any number of schemas (including multiple). OneOf is more restrictive and ensures data exclusivity.

Q: Can OneOf contain nested schemas?

A: Yes, OneOf can contain complex nested schemas, including objects with their own properties, arrays, and even nested OneOf or AnyOf statements.

Q: Is OneOf supported in all JSON Schema validators?

A: OneOf is part of the JSON Schema specification and is supported by most modern validators, though implementation details may vary slightly.

Q: How should I handle validation errors with OneOf?

A: Validation errors with OneOf typically indicate that the data didn't match any of the provided schemas. Review all schemas and ensure your data conforms to at least one of them.

Test Your JSON Schemas

Validating JSON schemas with OneOf can be complex, especially when dealing with nested structures or multiple conditions. To ensure your schemas work correctly, use our JSON Schema Validator tool. It provides instant feedback on your schema syntax and validation rules, helping you catch errors before they impact your applications.

Our validator supports all JSON Schema features including OneOf, AnyOf, AllOf, and more. Simply paste your schema and test data to see if they match according to your validation rules.

Start using the JSON Schema Validator today to streamline your development process and ensure data integrity across your applications.