{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openinherit.org/v3/common/completeness.json",
  "title": "Completeness",
  "description": "A completeness score derived from a weighted checklist of estate data categories, scoped to a specific jurisdiction and estate status",
  "$comment": "Reusable completeness scoring definition. Producers compute a weighted checklist score against a jurisdiction and estate status combination. Consumers can display progress, flag gaps, and compare readiness across estates.",
  "type": "object",
  "required": [ "score", "maxScore", "checklist" ],
  "propertyNames": {
    "pattern": "^(x-inherit-[a-z][a-z0-9-]*|[a-z][a-zA-Z0-9]*)$"
  },
  "properties": {
    "score": {
      "description": "Overall completeness percentage, calculated from the weighted checklist items",
      "examples": [ 72, 100, 0, 45 ],
      "readOnly": true,
      "default": 0,
      "type": "integer",
      "maximum": 100,
      "minimum": 0
    },
    "maxScore": {
      "description": "Maximum possible score for this jurisdiction and estate status combination. May be less than 100 if certain categories are not applicable",
      "examples": [ 100, 85, 92 ],
      "readOnly": true,
      "type": "integer",
      "minimum": 0
    },
    "jurisdiction": {
      "description": "ISO 3166-1 alpha-2 country code or ISO 3166-2 subdivision code identifying which jurisdiction this scoring applies to",
      "examples": [ "GB", "US", "GB-SCT", "AU-NSW" ],
      "type": "string",
      "maxLength": 255
    },
    "estateStatus": {
      "description": "The estate status this completeness score was calculated against. Different statuses may require different data, affecting which checklist items are applicable",
      "examples": [
        "pre_death_planning",
        "grant_application",
        "administration"
      ],
      "type": "string",
      "maxLength": 255
    },
    "calculatedAt": {
      "description": "ISO 8601 date-time when this completeness score was computed",
      "examples": [ "2026-03-28T14:30:00Z" ],
      "readOnly": true,
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}",
      "format": "date-time"
    },
    "checklist": {
      "description": "The individual items assessed to produce the overall score. Each item belongs to a category, has a relative weight, and a status indicating whether the data is present",
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "required": [ "category", "item", "weight", "status" ],
        "properties": {
          "category": {
            "description": "The data category this checklist item belongs to",
            "$comment": "personal_details: testator identity, addresses, marital status. assets_and_valuations: real property, financial accounts, personal possessions, and their valuations. liabilities: mortgages, loans, debts, guarantees. beneficiaries: named beneficiaries and their shares or bequests. executors: appointed executors and their contact details. guardians: guardians for minor children. tax_information: tax residency, reference numbers, prior returns. legal_documents: wills, codicils, trusts, powers of attorney. lifetime_transfers: gifts, settlements, and transfers within the lookback period. pension_and_insurance: pension schemes, life insurance policies, death-in-service benefits.",
            "examples": [
              "personal_details",
              "assets_and_valuations",
              "tax_information"
            ],
            "enum": [
              "personal_details",
              "assets_and_valuations",
              "liabilities",
              "beneficiaries",
              "executors",
              "guardians",
              "tax_information",
              "legal_documents",
              "lifetime_transfers",
              "pension_and_insurance"
            ]
          },
          "item": {
            "description": "A human-readable label describing what was checked",
            "examples": [
              "Testator date of birth",
              "Property valuations within 12 months",
              "IHT nil-rate band utilization"
            ],
            "type": "string",
            "maxLength": 255,
            "minLength": 1
          },
          "weight": {
            "description": "Relative importance of this item. Higher weights contribute more to the overall score",
            "examples": [ 1, 3, 5, 10 ],
            "type": "integer",
            "minimum": 1
          },
          "status": {
            "description": "Whether the data for this item is present and sufficient",
            "$comment": "complete: the required data is present and valid. incomplete: the data is missing or insufficient. not_applicable: this item does not apply to the current jurisdiction or estate status. unknown: the system cannot determine whether the data is present.",
            "examples": [ "complete", "incomplete", "not_applicable" ],
            "enum": [ "complete", "incomplete", "not_applicable", "unknown" ]
          },
          "details": {
            "description": "Optional explanation of the status, such as what is missing or why the item is not applicable",
            "examples": [
              "No valuation on file for 3 of 5 properties",
              "Guardians not required — no minor children"
            ],
            "type": "string",
            "maxLength": 255
          }
        },
        "additionalProperties": false
      }
    }
  },
  "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
}