{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openinherit.org/v3/relationship.json",
  "title": "Relationship",
  "description": "Spousal/partnership relationship. N-partner support (no structural two-partner limit). Event-based timeline (status derived from events). No gendered role names. Financial instruments with MAHR/KETUBAH subtype validation. Cross-jurisdiction recognition for dual civil/religious status",
  "type": "object",
  "required": [ "id", "type", "partners" ],
  "propertyNames": {
    "pattern": "^(x-inherit-[a-z][a-z0-9-]*|[a-z][a-zA-Z0-9]*)$"
  },
  "properties": {
    "id": {
      "description": "Unique identifier for this relationship within the INHERIT document",
      "examples": [ "f2a3b4c5-d6e7-8901-f234-56789abcdef0" ],
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
      "format": "uuid"
    },
    "type": {
      "description": "The legal form of the relationship",
      "$comment": "marriage_civil: marriage registered with the state. marriage_religious: marriage conducted under religious law (use religiousSubtype for specifics). marriage_customary: marriage valid under customary law (e.g. African customary marriage). marriage_common_law: common-law marriage recognised by the jurisdiction (not all do). civil_partnership: civil partnership (UK, Germany pre-2017, etc.). civil_union: civil union (US states, France PACS, etc.). domestic_partnership: domestic partnership registration. de_facto: de facto or common-law relationship recognised for succession (Australia, NZ). cohabitation: cohabitation without legal recognition — may still affect claims in some jurisdictions. engagement: formal engagement or betrothal — relevant for lobola and mahr negotiations. Religious subtypes (nikah, kiddushin, hindu_vivah) go in religiousSubtype. marriage_customary covers customary unions.",
      "examples": [ "marriage_civil", "marriage_religious", "de_facto" ],
      "enum": [
        "marriage_civil",
        "marriage_religious",
        "marriage_customary",
        "marriage_common_law",
        "civil_partnership",
        "civil_union",
        "domestic_partnership",
        "de_facto",
        "cohabitation",
        "engagement"
      ]
    },
    "religiousSubtype": {
      "description": "The specific religious marriage form, when the type is MARRIAGE_RELIGIOUS",
      "$comment": "Legal relationship categories recognised by specific jurisdictions, not religious labels. nikah: Islamic marriage contract — a legally binding civil contract in 50+ jurisdictions (all OIC member states, plus recognised for succession purposes in UK, US, Canada, Australia, Singapore). kiddushin: Jewish marriage — legally binding in Israel; recognised as a valid marriage for succession in UK/US/Canada where properly registered. hindu_vivah: Hindu marriage — legally binding under Hindu Marriage Act 1955 (India), recognised in UK/Singapore/Malaysia. anand_karaj: Sikh marriage — legally binding under Anand Marriage Act 1909 (India), recognised in UK/Canada. Only meaningful when type is MARRIAGE_RELIGIOUS.",
      "examples": [ "nikah", "kiddushin", "hindu_vivah", "anand_karaj" ],
      "type": "string",
      "maxLength": 255
    },
    "selfDeclaredType": {
      "description": "How the parties themselves describe this relationship, which may differ from the legal classification",
      "examples": [ "married", "partners", "life companions" ],
      "type": "string",
      "maxLength": 255
    },
    "partners": {
      "description": "The people in this relationship. Minimum 2, no structural upper limit — supports polygamous marriages valid in their jurisdiction",
      "type": "array",
      "maxItems": 100,
      "minItems": 2,
      "items": {
        "$ref": "#/$defs/Partner"
      }
    },
    "events": {
      "description": "Chronological events determining relationship status. The authoritative status should be derived from the most recent event",
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/$defs/RelationshipEvent"
      }
    },
    "currentStatus": {
      "description": "The current status of the relationship. A convenience denormalisation — consumers should derive from the events array when available",
      "$comment": "ACTIVE: relationship is current and subsisting. SEPARATED_INFORMAL: partners are separated without legal proceedings. SEPARATED_LEGAL: legally separated by court order or deed. DIVORCED: marriage has been dissolved by divorce. ANNULLED: marriage has been annulled (void or voidable). DISSOLVED: civil partnership has been dissolved. WIDOWED: one partner has died. VOID: marriage declared void ab initio — never legally existed. PUTATIVE: marriage is void but at least one party believed it was valid — may confer limited inheritance rights in some jurisdictions. Convenience denormalisation. The authoritative status SHOULD be derived from the most recent event in the events array. Producers MUST keep this consistent with the event timeline. Consumers SHOULD derive from events when events are present.",
      "examples": [ "active", "divorced", "widowed" ],
      "enum": [
        "active",
        "separated_informal",
        "separated_legal",
        "divorced",
        "annulled",
        "dissolved",
        "widowed",
        "void",
        "putative"
      ]
    },
    "jurisdiction": {
      "description": "Primary jurisdiction where this relationship was formed or registered",
      "$ref": "common/jurisdiction.json"
    },
    "jurisdictionalRecognition": {
      "description": "How other jurisdictions recognise (or do not recognise) this relationship. Essential for cross-border estates",
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/$defs/JurisdictionalRecognition"
      }
    },
    "financialInstruments": {
      "description": "Financial instruments associated with this relationship — mahr, ketubah, lobola, prenuptial agreements, etc",
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/$defs/FinancialInstrument"
      }
    },
    "propertyRegime": {
      "description": "The marital property regime governing this relationship. Determines which assets the testator may freely dispose of",
      "$comment": "community_of_property: all assets jointly owned from marriage (South Africa default). separation_of_property: each partner owns what they acquire (England and Wales, Japan). community_of_acquests: assets acquired during marriage are joint, pre-marital assets remain separate (France default). deferred_community: assets are separate during marriage but shared on dissolution (Scandinavia, Germany). separate_as_modified: separate property modified by prenuptial agreement. islamic_dower: property is separate; wife has deferred mahr claim. us_community_property: 50/50 community property (CA, TX, AZ, WA, NV, NM, LA, ID, WI). us_community_with_survivorship: community property with right of survivorship (TX, AK, AZ, NV, WI). us_quasi_community: California-specific — property acquired elsewhere treated as community on death. hindu_separate: Hindu law — property is separate, but coparcenary property has survivorship rules.",
      "examples": [
        "separation_of_property",
        "us_community_property",
        "community_of_acquests"
      ],
      "enum": [
        "community_of_property",
        "separation_of_property",
        "community_of_acquests",
        "deferred_community",
        "separate_as_modified",
        "islamic_dower",
        "us_community_property",
        "us_community_with_survivorship",
        "us_quasi_community",
        "hindu_separate"
      ]
    },
    "notes": {
      "description": "Free-text notes about this relationship",
      "examples": [
        "Polygamous marriage valid under Nigerian customary law",
        "Agunah situation — civilly divorced in 2020 but get (Jewish divorce) not yet given"
      ],
      "type": "string",
      "maxLength": 2000
    },
    "provenance": {
      "description": "Consolidated provenance metadata — how this entity was created, by whom, and whether a human has verified it",
      "$ref": "common/provenance.json"
    }
  },
  "patternProperties": {
    "^x-inherit-[a-z][a-z0-9-]{1,54}$": {
      "type": "object",
      "maxProperties": 50,
      "propertyNames": {
        "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
        "maxLength": 64
      }
    }
  },
  "unevaluatedProperties": false,
  "$defs": {
    "Partner": {
      "description": "A partner in the relationship. Uses non-gendered terminology and ordinal positioning",
      "type": "object",
      "required": [ "personId", "ordinal" ],
      "properties": {
        "personId": {
          "description": "Reference to a Person.id",
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
          "format": "uuid"
        },
        "personIdDisplay": {
          "description": "Human-readable display name for the referenced person",
          "type": "string",
          "maxLength": 255
        },
        "displayLabel": {
          "description": "Optional non-gendered label for display purposes. Avoids gendered terms like 'husband' and 'wife'",
          "examples": [ "First Wife", "Partner A", "Spouse 1" ],
          "type": "string",
          "maxLength": 255
        },
        "ordinal": {
          "description": "Position in the partner list (1-based). Determines default display order",
          "examples": [ 1, 2, 3 ],
          "type": "integer",
          "minimum": 1
        }
      },
      "additionalProperties": false
    },
    "RelationshipEvent": {
      "description": "A chronological event in the relationship timeline. The current relationship status is derived from the most recent event",
      "type": "object",
      "required": [ "type", "eventDate" ],
      "properties": {
        "type": {
          "description": "The type of relationship event",
          "$comment": "ceremony: religious or cultural ceremony (nikah, kiddushin, Hindu vivah). registration: civil registration with the state. engagement: formal engagement or betrothal. marriage_contract: prenuptial or postnuptial agreement signed. property_regime_change: change to the marital property regime. separation_informal: partners separated without legal proceedings. separation_legal: legal separation (judicial or by deed). divorce_filed: divorce proceedings initiated. divorce_finalised: divorce absolute/final. financial_order: court financial order (consent order, clean break). annulment: marriage declared void or voidable and annulled. dissolution: civil partnership dissolved. death_of_partner: one partner has died. reconciliation: separated partners have reconciled. void_declaration: court declares the marriage void ab initio. mahr_payment: payment of Islamic mahr (prompt or deferred). lobola_payment: payment of African customary bride price.",
          "enum": [
            "ceremony",
            "registration",
            "engagement",
            "marriage_contract",
            "property_regime_change",
            "separation_informal",
            "separation_legal",
            "divorce_filed",
            "divorce_finalised",
            "financial_order",
            "annulment",
            "dissolution",
            "death_of_partner",
            "reconciliation",
            "void_declaration",
            "mahr_payment",
            "lobola_payment"
          ]
        },
        "eventDate": {
          "description": "Date this event occurred",
          "examples": [ "2015-06-20", "2024-03-15" ],
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "format": "date"
        },
        "jurisdiction": {
          "description": "Jurisdiction where this event took place or was registered",
          "$ref": "common/jurisdiction.json"
        },
        "notes": {
          "description": "Additional context about this event",
          "examples": [
            "Nikah ceremony held at the East London Mosque",
            "Decree absolute received"
          ],
          "type": "string",
          "maxLength": 2000
        }
      },
      "additionalProperties": false
    },
    "FinancialInstrument": {
      "description": "A financial instrument associated with the relationship — mahr, ketubah, lobola, prenuptial agreement, or marriage settlement",
      "$comment": "KETUBAH requires ketubahDetails",
      "type": "object",
      "allOf": [
        {
          "$comment": "MAHR requires maharDetails",
          "if": {
            "required": [ "type" ],
            "properties": {
              "type": {
                "const": "mahr"
              }
            }
          },
          "then": {
            "required": [ "maharDetails" ]
          }
        }
      ],
      "if": {
        "required": [ "type" ],
        "properties": {
          "type": {
            "const": "ketubah"
          }
        }
      },
      "then": {
        "required": [ "ketubahDetails" ]
      },
      "required": [ "type" ],
      "properties": {
        "type": {
          "description": "The type of financial instrument",
          "$comment": "MAHR: Islamic bridal gift — a legally recognised financial obligation enforceable in Shariah courts and in secular family/probate courts in 50+ jurisdictions. May be prompt (paid at marriage) or deferred (payable on death or divorce). KETUBAH: Jewish marriage contract — a legally recognised financial obligation enforceable in Israeli rabbinical courts and treated as a binding contract by secular courts in the UK, US, Canada, and Australia. Establishes the groom's obligations. LOBOLA: African customary bride price — a legally recognised financial obligation under the Recognition of Customary Marriages Act 1998 (South Africa) and equivalent statutes in Nigeria, Kenya, Zimbabwe, and other jurisdictions. Paid from the groom's family to the bride's family. PRENUPTIAL_AGREEMENT: agreement before marriage governing property division. POSTNUPTIAL_AGREEMENT: agreement after marriage governing property division. MARRIAGE_SETTLEMENT: formal settlement of property in connection with a marriage.",
          "enum": [
            "mahr",
            "ketubah",
            "lobola",
            "prenuptial_agreement",
            "postnuptial_agreement",
            "marriage_settlement"
          ]
        },
        "value": {
          "description": "Monetary value of the instrument, in minor currency units",
          "$ref": "common/money.json"
        },
        "status": {
          "description": "Payment status of this financial instrument",
          "$comment": "AGREED: terms agreed but not yet paid. PAID: fully paid. PARTIALLY_PAID: some payment made, balance outstanding. DEFERRED: payment deferred to a future event (death, divorce). DISPUTED: terms or amount in dispute. WAIVED: obligation waived by the receiving party.",
          "examples": [ "deferred", "paid" ],
          "enum": [
            "agreed",
            "paid",
            "partially_paid",
            "deferred",
            "disputed",
            "waived"
          ]
        },
        "description": {
          "description": "Free-text description of the instrument",
          "examples": [
            "Deferred mahr of 50,000 AED",
            "Prenuptial agreement governing UK and French assets"
          ],
          "type": "string",
          "maxLength": 2000
        },
        "documentRef": {
          "description": "Reference to a Document.id storing the instrument",
          "examples": [ "DOC-2015-KETUBAH-001" ],
          "type": "string",
          "maxLength": 500
        },
        "instrumentDate": {
          "description": "Date the instrument was signed or executed",
          "examples": [ "2015-06-20" ],
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "format": "date"
        },
        "inheritanceImpact": {
          "description": "How this instrument affects inheritance distribution",
          "examples": [
            "Deferred mahr is a priority debt — paid before inheritance distribution",
            "Prenuptial ring-fences pre-marital assets from the estate"
          ],
          "type": "string",
          "maxLength": 255
        },
        "maharDetails": {
          "description": "Structured mahr details. Required when the financial instrument type is MAHR",
          "$comment": "Required when type is MAHR. Structured mahr data for Islamic estates.",
          "type": "object",
          "properties": {
            "maharType": {
              "description": "Whether the mahr is prompt, deferred, or a combination",
              "$comment": "prompt: paid at the time of marriage (muajjal). deferred: payable on death or divorce (mu'ajjal). combination: partly prompt, partly deferred.",
              "examples": [ "deferred", "combination" ],
              "enum": [ "prompt", "deferred", "combination" ]
            },
            "recipientPersonId": {
              "description": "Reference to the Person.id of the mahr recipient (the wife)",
              "type": "string",
              "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
              "format": "uuid"
            },
            "recipientPersonIdDisplay": {
              "description": "Human-readable display name for the referenced recipient person",
              "type": "string",
              "maxLength": 255
            },
            "linkedLiabilityId": {
              "description": "Reference to the Liability.id representing the deferred mahr as an estate debt",
              "$comment": "Links to the Liability entity representing this mahr as an estate debt",
              "type": "string",
              "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
              "format": "uuid"
            }
          },
          "additionalProperties": false
        },
        "ketubahDetails": {
          "description": "Structured ketubah details. Required when the financial instrument type is KETUBAH",
          "$comment": "Required when type is KETUBAH. Structured ketubah data for Jewish estates.",
          "type": "object",
          "properties": {
            "principalAmount": {
              "description": "The ikkar ketubah — the standard principal amount",
              "$comment": "Ikkar ketubah — standard amount (200 zuz for virgin, 100 for widow/divorcee)",
              "$ref": "common/money.json"
            },
            "tosefetAmount": {
              "description": "The tosefet ketubah — the groom's voluntary additional amount",
              "$comment": "Tosefet ketubah — groom's additional amount",
              "$ref": "common/money.json"
            },
            "nedunya": {
              "description": "The nedunya — dowry brought by the bride into the marriage",
              "$comment": "Dowry brought by the bride",
              "$ref": "common/money.json"
            },
            "brideStatus": {
              "description": "The bride's status at the time of marriage, which determines the ikkar amount",
              "$comment": "virgin: betulah — determines the ikkar amount (200 zuz). widow: almanah — ikkar amount is 100 zuz. divorcee: gerushah — ikkar amount is 100 zuz.",
              "enum": [ "virgin", "widow", "divorcee" ]
            },
            "witnessPersonIds": {
              "description": "Person IDs of the ketubah witnesses. Under halacha, witnesses must be male, adult, and observant",
              "type": "array",
              "maxItems": 100,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
                "format": "uuid"
              }
            },
            "officiatingRabbi": {
              "description": "Name of the rabbi who officiated the ceremony",
              "examples": [
                "Rabbi David Goldstein",
                "Rabbi Miriam Berkowitz",
                "Rabbi Yosef Ben-Ami"
              ],
              "type": "string",
              "maxLength": 255
            }
          },
          "additionalProperties": false
        },
        "lobolaDetails": {
          "description": "Structured lobola details for African customary marriages",
          "$comment": "Structured lobola data for African customary estates.",
          "type": "object",
          "properties": {
            "negotiatedWith": {
              "description": "The family or person with whom the lobola was negotiated",
              "$comment": "Family or person lobola was negotiated with",
              "examples": [
                "Nkosi family, Johannesburg",
                "Chief Okafor, Enugu",
                "Mensah family, Accra"
              ],
              "type": "string",
              "maxLength": 255
            },
            "includesLivestock": {
              "description": "Whether the lobola includes livestock (cattle are traditional in many Southern African customs)",
              "examples": [ true, false ],
              "type": "boolean"
            },
            "livestockCount": {
              "description": "Number of livestock included in the lobola",
              "examples": [ 11, 6 ],
              "type": "integer",
              "minimum": 0
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "JurisdictionalRecognition": {
      "description": "How a specific jurisdiction recognises (or fails to recognise) this relationship. Critical for modelling civil/religious status divergence",
      "$comment": "How a jurisdiction recognises this relationship. Enables modelling of civil/religious status divergence (e.g. agunah: civilly divorced but halachically married).",
      "type": "object",
      "required": [ "jurisdiction", "recognised" ],
      "properties": {
        "jurisdiction": {
          "description": "The jurisdiction whose recognition status is recorded",
          "$ref": "common/jurisdiction.json"
        },
        "recognised": {
          "description": "Whether this jurisdiction recognises the relationship",
          "examples": [ true, false ],
          "type": "boolean"
        },
        "recognisedAs": {
          "description": "What this jurisdiction recognises the relationship as, if different from its declared type",
          "examples": [ "civil partnership", "cohabitation", "marriage" ],
          "type": "string",
          "maxLength": 255
        },
        "notes": {
          "description": "Additional context on recognition",
          "examples": [
            "Civilly divorced but halachically married (agunah situation)",
            "Same-sex marriage not recognised — treated as cohabitation"
          ],
          "type": "string",
          "maxLength": 2000
        }
      },
      "additionalProperties": false
    }
  }
}