oneOf — 正確に1つのスキーマに一致
JSON Schemaの oneOf キーワードで、複数のスキーマのうち正確に1つにのみ一致するバリデーションを定義する方法を解説します。
Composition
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"payment": {
"oneOf": [
{
"type": "object",
"properties": {
"method": { "const": "credit_card" },
"cardNumber": { "type": "string", "pattern": "^\\d{13,19}$" },
"expiry": { "type": "string", "pattern": "^(0[1-9]|1[0-2])/\\d{2}$" }
},
"required": ["method", "cardNumber", "expiry"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"method": { "const": "bank_transfer" },
"iban": { "type": "string", "pattern": "^[A-Z]{2}\\d{2}[A-Z0-9]{11,30}$" }
},
"required": ["method", "iban"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"method": { "const": "paypal" },
"email": { "type": "string", "format": "email" }
},
"required": ["method", "email"],
"additionalProperties": false
}
]
}
},
"required": ["payment"]
}Test Data
{
"payment": {
"method": "credit_card",
"cardNumber": "4111111111111111",
"expiry": "12/26"
}
}詳細な説明
JSON Schemaの oneOf キーワードは、指定した複数のスキーマのうち正確に1つにのみ値が一致する排他的OR条件を定義します。0個または2個以上のスキーマに一致する場合は無効です。
基本構文:
{
"oneOf": [
{ "type": "object", "required": ["type"], "properties": { "type": { "const": "email" }, "address": { "type": "string" } } },
{ "type": "object", "required": ["type"], "properties": { "type": { "const": "phone" }, "number": { "type": "string" } } }
]
}
注意点:
oneOfは全てのサブスキーマを評価する必要があるため、anyOfよりもパフォーマンスが低くなる可能性があります。- discriminator（判別子）プロパティを使用してサブスキーマを効率的に選択するのがベストプラクティスです。
- エラーメッセージが複雑になりやすいため、デバッグが難しくなる場合があります。
ユースケース
メールまたは電話番号のいずれか、異なるペイロード形式のWebhookイベント、判別共用体型のバリデーションに使用します。