[
  {
    "description": "Entity families via pure $ref graph",
    "database": {
      "types": [
        {
          "name": "entity",
          "variations": [
            "entity",
            "organization",
            "person"
          ],
          "schemas": [
            {
              "$id": "entity",
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            },
            {
              "$id": "light.entity",
              "$ref": "entity"
            }
          ]
        },
        {
          "name": "organization",
          "variations": [
            "organization",
            "person"
          ],
          "schemas": [
            {
              "$id": "organization",
              "$ref": "entity",
              "properties": {
                "name": {
                  "type": "string"
                }
              }
            }
          ]
        },
        {
          "name": "person",
          "variations": [
            "person"
          ],
          "schemas": [
            {
              "$id": "person",
              "$ref": "organization",
              "properties": {
                "first_name": {
                  "type": "string"
                }
              }
            },
            {
              "$id": "light.person",
              "$ref": "light.entity"
            }
          ]
        }
      ],
      "puncs": [
        {
          "name": "get_entities",
          "schemas": [
            {
              "$id": "get_entities.response",
              "$family": "entity"
            }
          ]
        },
        {
          "name": "get_light_entities",
          "schemas": [
            {
              "$id": "get_light_entities.response",
              "$family": "light.entity"
            }
          ]
        }
      ]
    },
    "tests": [
      {
        "description": "Family matches base entity",
        "schema_id": "get_entities.response",
        "data": {
          "id": "1",
          "type": "entity"
        },
        "action": "validate",
        "expect": {
          "success": true
        }
      },
      {
        "description": "Family matches descendant person",
        "schema_id": "get_entities.response",
        "data": {
          "id": "2",
          "type": "person",
          "name": "ACME",
          "first_name": "John"
        },
        "action": "validate",
        "expect": {
          "success": true
        }
      },
      {
        "description": "Graph family matches light.entity",
        "schema_id": "get_light_entities.response",
        "data": {
          "id": "3",
          "type": "entity"
        },
        "action": "validate",
        "expect": {
          "success": true
        }
      },
      {
        "description": "Graph family matches light.person (because it $refs light.entity)",
        "schema_id": "get_light_entities.response",
        "data": {
          "id": "4",
          "type": "person"
        },
        "action": "validate",
        "expect": {
          "success": true
        }
      },
      {
        "description": "Graph family excludes organization (missing light. schema that $refs light.entity)",
        "schema_id": "get_light_entities.response",
        "data": {
          "id": "5",
          "type": "organization",
          "name": "ACME"
        },
        "action": "validate",
        "expect": {
          "success": false,
          "errors": [
            {
              "code": "FAMILY_MISMATCH",
              "path": ""
            }
          ]
        }
      }
    ]
  },
  {
    "description": "Ad-hoc non-entity families (using normal json-schema object structures)",
    "database": {
      "puncs": [
        {
          "name": "get_widgets",
          "schemas": [
            {
              "$id": "widget",
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "widget_type": {
                  "type": "string"
                }
              }
            },
            {
              "$id": "special_widget",
              "$ref": "widget",
              "properties": {
                "special_feature": {
                  "type": "string"
                }
              }
            },
            {
              "$id": "get_widgets.response",
              "$family": "widget"
            }
          ]
        }
      ]
    },
    "tests": [
      {
        "description": "Ad-hoc family matches strictly by shape (no magic variations for base schemas)",
        "schema_id": "get_widgets.response",
        "data": {
          "id": "1",
          "widget_type": "special",
          "special_feature": "yes"
        },
        "action": "validate",
        "expect": {
          "success": true
        }
      }
    ]
  }
]