{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.parcelclear.com/agents/record-schema.json",
  "title": "ParcelClear Texas SB 17 record questionnaire",
  "description": "The facts one ParcelClear record collects about a Texas SB 17 transaction, and the shape they are stored in. There is no API today: these facts are entered by a person at parcelclear.com, and no endpoint accepts them. Answers are what a party attested. An unanswered fact reads as missing to the rule engine, which holds the file rather than passing it.",
  "type": "object",
  "x-parcelclear": {
    "rule_set_id": "tx-sb17",
    "rule_set_version": "1.0.7",
    "generated_at": "2026-09-08"
  },
  "additionalProperties": false,
  "required": [
    "party_type",
    "legal_name"
  ],
  "properties": {
    "party_role": {
      "description": "Who this party is in the transaction. Buyer is the person or entity taking the interest. Control person is an owner, officer, trustee, or beneficiary of a buyer entity or trust.",
      "type": "string",
      "enum": [
        "buyer",
        "control_person",
        "transferee",
        "other"
      ]
    },
    "party_type": {
      "description": "Individual, entity, trust, or government. The type decides which identity questions apply and whether a control-person tree is required.",
      "type": "string",
      "enum": [
        "individual",
        "entity",
        "trust",
        "government"
      ]
    },
    "legal_name": {
      "description": "Name exactly as it appears on the contract or entity filing. ParcelClear screens this name and any aliases against the OFAC SDN and Consolidated lists.",
      "type": "string"
    },
    "aliases": {
      "description": "Other names this party uses: prior names, trade names, transliterations. One per line. Each alias is screened separately.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "x-parcelclear-normalization": "split on commas, semicolons, and newlines"
    },
    "dob_or_formation_date": {
      "description": "Date of birth for a person, formation date for an entity or trust. Used to tell apart same-name list entries during review. Not shared outside this record.",
      "type": "string",
      "format": "date"
    },
    "us_citizen": {
      "description": "Answer for this party only. Citizenship status is one of the facts the Texas SB 17 rule set evaluates. Unknown answers hold the file; they never clear it.",
      "type": "boolean",
      "x-parcelclear-party-types": [
        "individual"
      ]
    },
    "lawful_permanent_resident": {
      "description": "Green-card holder. Relevant to the Texas SB 17 residency exceptions. Answer only what the party attests; ParcelClear does not verify immigration status.",
      "type": "boolean",
      "x-parcelclear-party-types": [
        "individual"
      ]
    },
    "lawfully_present_in_us": {
      "description": "Present in the United States under a valid visa or other lawful status. Relevant to the homestead exception under Texas SB 17.",
      "type": "boolean",
      "x-parcelclear-party-types": [
        "individual"
      ]
    },
    "domicile_country": {
      "description": "Where this party permanently lives or, for an entity, is headquartered. The rule set compares this to the designated-country list.",
      "type": "string",
      "x-parcelclear-normalization": "trimmed and upper-cased",
      "x-parcelclear-party-types": [
        "individual"
      ]
    },
    "citizenship_countries": {
      "description": "Every country of citizenship, one per line. Dual citizens list both. Missing a country that is on the designated list can change the result.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "x-parcelclear-normalization": "split on commas, semicolons, and newlines, then upper-cased",
      "x-parcelclear-party-types": [
        "individual"
      ]
    },
    "entity_hq_country": {
      "description": "Country of the entity's principal place of business.",
      "type": "string",
      "x-parcelclear-normalization": "trimmed and upper-cased",
      "x-parcelclear-party-types": [
        "entity",
        "trust"
      ]
    },
    "entity_formation_country": {
      "description": "Country whose law the entity was formed under.",
      "type": "string",
      "x-parcelclear-normalization": "trimmed and upper-cased",
      "x-parcelclear-party-types": [
        "entity",
        "trust"
      ]
    },
    "government_country": {
      "description": "The country whose government is acquiring the interest. Use the two-letter country code. Only applies when the party type is government.",
      "type": "string",
      "x-parcelclear-normalization": "trimmed and upper-cased",
      "x-parcelclear-party-types": [
        "government"
      ]
    },
    "control_persons": {
      "description": "Control persons of an entity or trust buyer. On a paid record each one is entered as a separate party and screened. The free worksheet takes this as a note and neither evaluates nor screens it.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/control_person"
      }
    },
    "control_tree_attested": {
      "description": "Your statement that the control persons listed are all of them, from the documents in this file. Leaving it unchecked holds the file; it is never treated as a yes.",
      "type": "boolean",
      "x-parcelclear-party-types": [
        "entity",
        "trust"
      ]
    },
    "interest_type": {
      "description": "Fee simple, leasehold, mineral, or other. The Texas rule set treats short leaseholds differently from fee interests; see the lease term field.",
      "type": "string",
      "enum": [
        "fee",
        "leasehold",
        "mineral",
        "other"
      ]
    },
    "lease_term_months": {
      "description": "Total term including renewal options, in months. Leave blank for non-lease interests.",
      "type": "number"
    },
    "intended_homestead": {
      "description": "Will the buyer live on the property as a primary residence? Relevant to the Texas SB 17 homestead exception for lawfully present individuals.",
      "type": "boolean"
    },
    "interest_held_before_2025_09_01": {
      "description": "Did the party already hold this interest before September 1, 2025? Texas SB 17 applies to interests acquired on or after that date.",
      "type": "boolean"
    },
    "post_closing_transfer_planned": {
      "description": "Is a transfer to another person or entity planned after closing? Texas SB 17 reaches indirect acquisitions, so ParcelClear records the intended transferee.",
      "type": "boolean"
    },
    "transferee_details": {
      "description": "Name and relationship of any planned transferee, recorded as text. It is not screened on its own. To screen that person, add them as a party with the transferee role.",
      "type": "string"
    }
  },
  "$defs": {
    "control_person": {
      "title": "Control person",
      "description": "One owner, officer, trustee, or beneficiary recorded under an entity or trust buyer. Each one is a party in its own right and is screened separately.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "party_type",
        "legal_name"
      ],
      "properties": {
        "party_role": {
          "description": "Who this party is in the transaction. Buyer is the person or entity taking the interest. Control person is an owner, officer, trustee, or beneficiary of a buyer entity or trust.",
          "type": "string",
          "enum": [
            "buyer",
            "control_person",
            "transferee",
            "other"
          ]
        },
        "party_type": {
          "description": "Individual, entity, trust, or government. The type decides which identity questions apply and whether a control-person tree is required.",
          "type": "string",
          "enum": [
            "individual",
            "entity",
            "trust",
            "government"
          ]
        },
        "legal_name": {
          "description": "Name exactly as it appears on the contract or entity filing. ParcelClear screens this name and any aliases against the OFAC SDN and Consolidated lists.",
          "type": "string"
        },
        "aliases": {
          "description": "Other names this party uses: prior names, trade names, transliterations. One per line. Each alias is screened separately.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "x-parcelclear-normalization": "split on commas, semicolons, and newlines"
        },
        "dob_or_formation_date": {
          "description": "Date of birth for a person, formation date for an entity or trust. Used to tell apart same-name list entries during review. Not shared outside this record.",
          "type": "string",
          "format": "date"
        },
        "us_citizen": {
          "description": "Answer for this party only. Citizenship status is one of the facts the Texas SB 17 rule set evaluates. Unknown answers hold the file; they never clear it.",
          "type": "boolean",
          "x-parcelclear-party-types": [
            "individual"
          ]
        },
        "lawful_permanent_resident": {
          "description": "Green-card holder. Relevant to the Texas SB 17 residency exceptions. Answer only what the party attests; ParcelClear does not verify immigration status.",
          "type": "boolean",
          "x-parcelclear-party-types": [
            "individual"
          ]
        },
        "lawfully_present_in_us": {
          "description": "Present in the United States under a valid visa or other lawful status. Relevant to the homestead exception under Texas SB 17.",
          "type": "boolean",
          "x-parcelclear-party-types": [
            "individual"
          ]
        },
        "domicile_country": {
          "description": "Where this party permanently lives or, for an entity, is headquartered. The rule set compares this to the designated-country list.",
          "type": "string",
          "x-parcelclear-normalization": "trimmed and upper-cased",
          "x-parcelclear-party-types": [
            "individual"
          ]
        },
        "citizenship_countries": {
          "description": "Every country of citizenship, one per line. Dual citizens list both. Missing a country that is on the designated list can change the result.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "x-parcelclear-normalization": "split on commas, semicolons, and newlines, then upper-cased",
          "x-parcelclear-party-types": [
            "individual"
          ]
        },
        "entity_hq_country": {
          "description": "Country of the entity's principal place of business.",
          "type": "string",
          "x-parcelclear-normalization": "trimmed and upper-cased",
          "x-parcelclear-party-types": [
            "entity",
            "trust"
          ]
        },
        "entity_formation_country": {
          "description": "Country whose law the entity was formed under.",
          "type": "string",
          "x-parcelclear-normalization": "trimmed and upper-cased",
          "x-parcelclear-party-types": [
            "entity",
            "trust"
          ]
        },
        "control_test_ids": {
          "description": "The control tests this person meets, by id, from control_person_tests in the active rule set. A control person with no test recorded leaves the tree incomplete, and an incomplete tree holds the file.",
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "CP-GP",
              "CP-MM",
              "CP-10",
              "CP-EO",
              "CP-RIGHT",
              "CP-TRUST"
            ]
          }
        }
      }
    }
  }
}