[
  {
    "description": "Vertical $family Routing (Across Tables)",
    "database": {
      "types": [
        {
          "name": "entity",
          "variations": ["entity", "organization", "person", "bot"],
          "schemas": [
            {
              "$id": "entity",
              "type": "object",
              "properties": {
                "type": { "type": "string" },
                "id": { "type": "string" }
              }
            }
          ]
        },
        {
          "name": "organization",
          "variations": ["organization", "person"],
          "schemas": [
            {
              "$id": "organization",
              "type": "entity",
              "properties": {
                "name": { "type": "string" }
              }
            }
          ]
        },
        {
          "name": "person",
          "variations": ["person"],
          "schemas": [
            {
              "$id": "person",
              "type": "organization",
              "properties": {
                "first_name": { "type": "string" }
              }
            }
          ]
        },
        {
          "name": "bot",
          "variations": ["bot"],
          "schemas": [
            {
              "$id": "bot",
              "type": "entity",
              "properties": {
                "model": { "type": "string" }
              }
            }
          ]
        }
      ],
      "schemas": [
        {
          "$id": "family_entity",
          "$family": "entity"
        }
      ]
    },
    "tests": [
      {
        "description": "Matches base entity",
        "schema_id": "family_entity",
        "data": { "type": "entity", "id": "1" },
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "Matches descendant person natively",
        "schema_id": "family_entity",
        "data": { "type": "person", "id": "2", "first_name": "Bob" },
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "Missing type fails out immediately",
        "schema_id": "family_entity",
        "data": { "id": "3", "first_name": "Bob" },
        "action": "validate",
        "expect": { "success": false, "errors": [ { "code": "MISSING_TYPE", "details": { "path": "" } } ] }
      },
      {
        "description": "Alias matching failure",
        "schema_id": "family_entity",
        "data": { "type": "alien", "id": "4" },
        "action": "validate",
        "expect": { "success": false, "errors": [ { "code": "NO_FAMILY_MATCH", "details": { "path": "" } } ] }
      }
    ]
  },
  {
    "description": "Matrix $family Routing (Vertical + Horizontal Intersections)",
    "database": {
      "types": [
        {
          "name": "entity",
          "variations": ["entity", "organization", "person", "bot"],
          "schemas": [
            {
              "$id": "entity",
              "type": "object",
              "properties": {
                "type": { "type": "string" }
              }
            },
            {
              "$id": "light.entity",
              "type": "entity",
              "properties": {
                "kind": { "type": "string" }
              }
            }
          ]
        },
        {
          "name": "organization",
          "variations": ["organization", "person"],
          "schemas": [
            {
              "$id": "organization",
              "type": "entity"
            },
            {
              "$id": "light.organization",
              "type": "light.entity"
            }
          ]
        },
        {
          "name": "person",
          "variations": ["person"],
          "schemas": [
            {
              "$id": "person",
              "type": "organization"
            },
            {
              "$id": "light.person",
              "type": "light.organization"
            }
          ]
        },
        {
          "name": "bot",
          "variations": ["bot"],
          "schemas": [
            {
              "$id": "bot",
              "type": "entity"
            },
            {
              "$id": "light.bot",
              "type": "light.entity"
            }
          ]
        }
      ],
      "schemas": [
        {
          "$id": "family_light_org",
          "$family": "light.organization"
        }
      ]
    },
    "tests": [
      {
        "description": "Matches light.organization exact matrix target",
        "schema_id": "family_light_org",
        "data": { "type": "organization", "kind": "light" },
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "Matches descendant light.person through matrix evaluation",
        "schema_id": "family_light_org",
        "data": { "type": "person", "kind": "light" },
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "Structurally fails to route bot (bot is not descendant of organization)",
        "schema_id": "family_light_org",
        "data": { "type": "bot", "kind": "light" },
        "action": "validate",
        "expect": { "success": false, "errors": [ { "code": "NO_FAMILY_MATCH", "details": { "path": "" } } ] }
      }
    ]
  },
  {
    "description": "Horizontal $family Routing (Virtual Variations)",
    "database": {
      "schemas": [
        {
          "$id": "widget",
          "type": "object",
          "properties": {
            "type": { "type": "string" }
          }
        },
        {
          "$id": "stock.widget",
          "type": "widget",
          "properties": {
            "kind": { "type": "string" },
            "amount": { "type": "integer" }
          }
        },
        {
          "$id": "super_stock.widget",
          "type": "stock.widget",
          "properties": {
            "super_amount": { "type": "integer" }
          }
        },
        {
          "$id": "family_widget",
          "$family": "widget"
        },
        {
          "$id": "family_stock_widget",
          "$family": "stock.widget"
        }
      ]
    },
    "tests": [
      {
        "description": "Base widget resolves stock widget horizontally",
        "schema_id": "family_widget",
        "data": { "type": "widget", "kind": "stock", "amount": 5 },
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "Base widget resolves nested super stock widget natively via descendants crawl",
        "schema_id": "family_widget",
        "data": { "type": "widget", "kind": "super_stock", "amount": 5, "super_amount": 10 },
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "stock.widget explicit family resolves nested super stock via fast path",
        "schema_id": "family_stock_widget",
        "data": { "type": "widget", "kind": "super_stock", "amount": 5, "super_amount": 10 },
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "stock.widget fails when presented an invalid payload constraint",
        "schema_id": "family_stock_widget",
        "data": { "type": "widget", "kind": "super_stock", "amount": 5, "super_amount": "not_an_int" },
        "action": "validate",
        "expect": { "success": false, "errors": [ { "code": "INVALID_TYPE", "details": { "path": "super_amount" } } ] }
      }
    ]
  },
  {
    "description": "Strict oneOf Punc Pointers (Tagged Unions)",
    "database": {
      "types": [
        {
          "name": "entity",
          "variations": ["entity", "person", "bot"],
          "schemas": [
            {
              "$id": "entity",
              "type": "object",
              "properties": {
                "type": { "type": "string" }
              }
            }
          ]
        },
        {
          "name": "person",
          "variations": ["person"],
          "schemas": [
            {
              "$id": "person",
              "type": "entity"
            },
            {
              "$id": "full.person",
              "type": "person",
              "properties": {
                "kind": { "type": "string" },
                "age": { "type": "integer" }
              },
              "required": ["age"]
            }
          ]
        },
        {
          "name": "bot",
          "variations": ["bot"],
          "schemas": [
            {
              "$id": "bot",
              "type": "entity"
            },
            {
              "$id": "full.bot",
              "type": "bot",
              "properties": {
                "kind": { "type": "string" },
                "version": { "type": "string" }
              },
              "required": ["version"]
            }
          ]
        }
      ],
      "schemas": [
        {
          "$id": "oneOf_union",
          "oneOf": [
            { "type": "full.person" },
            { "type": "full.bot" }
          ]
        }
      ]
    },
    "tests": [
      {
        "description": "Throws MISSING_TYPE if discriminator matches neither",
        "schema_id": "oneOf_union",
        "data": { "kind": "full", "age": 5 },
        "action": "validate",
        "expect": { "success": false, "errors": [ { "code": "MISSING_TYPE", "details": { "path": "" } } ] }
      },
      {
        "description": "Golden match throws pure structural error exclusively on person",
        "schema_id": "oneOf_union",
        "data": { "type": "person", "kind": "full", "age": "five" },
        "action": "validate",
        "expect": { "success": false, "errors": [ { "code": "INVALID_TYPE", "details": { "path": "age" } } ] }
      },
      {
        "description": "Golden matches perfectly",
        "schema_id": "oneOf_union",
        "data": { "type": "person", "kind": "full", "age": 5 },
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "Fails nicely with NO_ONEOF_MATCH",
        "schema_id": "oneOf_union",
        "data": { "type": "alien", "kind": "full", "age": 5 },
        "action": "validate",
        "expect": { "success": false, "errors": [ { "code": "NO_ONEOF_MATCH", "details": { "path": "" } } ] }
      }
    ]
  },
  {
    "description": "JSONB Field Bubble oneOf Discrimination (Promoted IDs)",
    "database": {
      "schemas": [
        {
          "$id": "metadata",
          "type": "object",
          "properties": {
            "type": { "type": "string" }
          }
        },
        {
          "$id": "invoice.metadata",
          "type": "metadata",
          "properties": {
            "invoice_id": { "type": "integer" }
          },
          "required": ["invoice_id"]
        },
        {
          "$id": "payment.metadata",
          "type": "metadata",
          "properties": {
            "payment_id": { "type": "integer" }
          },
          "required": ["payment_id"]
        },
        {
          "$id": "oneOf_bubble",
          "oneOf": [
            { "type": "invoice.metadata" },
            { "type": "payment.metadata" }
          ]
        }
      ]
    },
    "tests": [
      {
        "description": "Extracts golden match natively from explicit JSONB type discriminator",
        "schema_id": "oneOf_bubble",
        "data": { "type": "invoice.metadata", "invoice_id": "nan" },
        "action": "validate",
        "expect": {
          "success": false,
          "errors": [ { "code": "INVALID_TYPE", "details": { "path": "invoice_id" } } ]
        }
      },
      {
        "description": "Valid payload succeeds perfectly in JSONB universe",
        "schema_id": "oneOf_bubble",
        "data": { "type": "payment.metadata", "payment_id": 123 },
        "action": "validate",
        "expect": { "success": true }
      }
    ]
  },
  {
    "description": "Standard JSON Schema oneOf",
    "database": {
      "schemas": [
        {
          "$id": "oneOf_scalars",
          "oneOf": [
            { "type": "integer" },
            { "minimum": 2 }
          ]
        },
        {
          "$id": "oneOf_dedupe",
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "shared": { "type": "integer" }
              },
              "required": ["shared"]
            },
            {
              "type": "object",
              "properties": {
                "shared": { "type": "integer" },
                "extra": { "type": "string" }
              },
              "required": ["shared", "extra"]
            }
          ]
        }
      ]
    },
    "tests": [
      {
        "description": "Valid exclusively against first scalar choice",
        "schema_id": "oneOf_scalars",
        "data": 1,
        "action": "validate",
        "expect": { "success": true }
      },
      {
        "description": "Fails mathematically if matches both schemas natively",
        "schema_id": "oneOf_scalars",
        "data": 3,
        "action": "validate",
        "expect": { "success": false }
      },
      {
        "description": "Deduper merges shared errors dynamically exactly like JSON Schema",
        "schema_id": "oneOf_dedupe",
        "data": { "shared": "nan" },
        "action": "validate",
        "expect": {
          "success": false,
          "errors": [
            { "code": "NO_ONEOF_MATCH", "details": { "path": "" } },
            { "code": "INVALID_TYPE", "details": { "path": "shared" } }
          ]
        }
      }
    ]
  }
]