{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/propraven-com/json-schema/propraven-com-owner-card-schema.json",
  "title": "OwnerCard",
  "description": "The owner card: the owner of record and how to reach them by mail, from what the publishing authorities released.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/propraven-com-openapi.json#/components/schemas/OwnerCard",
  "type": "object",
  "required": [
    "subject",
    "owner",
    "contact",
    "note"
  ],
  "properties": {
    "subject": {
      "type": "object",
      "description": "{ kind: \"parcel\", canonical_id } or { kind: \"owner\", parcels_considered, parcels_capped }.",
      "required": [
        "kind",
        "canonical_id"
      ],
      "properties": {
        "kind": {
          "type": "string"
        },
        "canonical_id": {
          "type": "string"
        }
      }
    },
    "owner": {
      "type": "object",
      "required": [
        "name",
        "name_status",
        "entity_type",
        "roles"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "name_status": {
          "type": "string",
          "enum": [
            "present",
            "missing",
            "placeholder",
            "confidential"
          ]
        },
        "entity_type": {
          "type": "string"
        },
        "roles": {
          "type": "array"
        }
      }
    },
    "contact": {
      "type": "object",
      "required": [
        "owner_name",
        "owner_name_status",
        "owner_roles",
        "owner_name_provenance",
        "co_owners",
        "co_owner_status",
        "mailing",
        "mailing_alternates",
        "entity",
        "phones",
        "phone_status",
        "emails",
        "none_published",
        "hidden_low_confidence",
        "people_on_permits",
        "people_on_permits_status",
        "other_addresses",
        "other_addresses_status",
        "other_addresses_scope"
      ],
      "properties": {
        "owner_name": {
          "type": "string"
        },
        "owner_name_status": {
          "type": "string"
        },
        "owner_roles": {
          "type": "array"
        },
        "owner_name_provenance": {
          "type": "object",
          "required": [
            "source",
            "as_of",
            "as_of_basis",
            "grade"
          ],
          "properties": {
            "source": {
              "type": "object",
              "required": [
                "authority",
                "dataset",
                "url"
              ],
              "properties": {
                "authority": {
                  "type": "string"
                },
                "dataset": {
                  "type": "string"
                },
                "url": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            },
            "as_of": {
              "type": "string"
            },
            "as_of_basis": {
              "type": "string"
            },
            "grade": {
              "type": "string"
            }
          }
        },
        "co_owners": {
          "type": "array",
          "description": "The other owners the same assessor record names, in the record's order; never the owner again. Name mode: across the side-read parcels, distinct by name.",
          "items": {
            "$ref": "#/$defs/CoOwner"
          }
        },
        "co_owner_status": {
          "type": "string",
          "description": "none_listed is claimed only for a record whose state's co-owners were loaded from the release that serves it; not_checked when the lookup could not run, the state is not loaded yet, or the loaded row was read beside a different owner.",
          "enum": [
            "listed",
            "none_listed",
            "not_checked"
          ]
        },
        "mailing": {
          "$ref": "#/$defs/MailingAddress"
        },
        "mailing_alternates": {
          "type": "array",
          "description": "Parcel mode: a latest-deed grantee address naming the same owner, when it differs.",
          "items": {
            "$ref": "#/$defs/MailingAddress"
          }
        },
        "entity": {
          "type": "object",
          "description": "Secretary of State principals (entity type, status, registered agent, officers) when the owner is an entity. When the parcel record carries no registered agent or officers, they come from the single matching Secretary of State filing (`principals_basis: sos_registry`).",
          "required": [
            "entity_type",
            "status",
            "state_of_formation",
            "formation_date",
            "registered_agent",
            "officers",
            "source",
            "as_of",
            "as_of_basis",
            "grade"
          ],
          "properties": {
            "entity_type": {
              "type": "string"
            },
            "status": {
              "type": [
                "string",
                "null"
              ]
            },
            "state_of_formation": {
              "type": [
                "string",
                "null"
              ]
            },
            "formation_date": {
              "type": [
                "string",
                "null"
              ]
            },
            "registered_agent": {
              "type": [
                "string",
                "null"
              ]
            },
            "officers": {
              "type": "array"
            },
            "source": {
              "type": "object",
              "required": [
                "authority",
                "dataset",
                "url"
              ],
              "properties": {
                "authority": {
                  "type": "string"
                },
                "dataset": {
                  "type": "string"
                },
                "url": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            },
            "as_of": {
              "type": [
                "string",
                "null"
              ]
            },
            "as_of_basis": {
              "type": [
                "string",
                "null"
              ]
            },
            "grade": {
              "type": "string"
            },
            "principals_basis": {
              "type": "string",
              "enum": [
                "parcel_record",
                "sos_registry"
              ]
            }
          }
        },
        "phones": {
          "type": "array",
          "description": "OWNER phones (owner role only) published on a building permit filed in the current owner's era and naming them (grade C): { e164, display, ext, phone_raw, role_basis, permit_ref, source, as_of, as_of_basis, grade } Also the latest deed's buyer phone where the deed source publishes a contact block (Indiana sales disclosure forms), name-matched to the current owner (basis: deed_contact_phone, deed_ref; account required).",
          "items": {
            "type": "object"
          }
        },
        "phone_status": {
          "type": "string",
          "description": "none_published is claimed only after the permit lookup ran; not_checked when it could not (timeout, no acquisition date, no owner name).",
          "enum": [
            "published",
            "none_published",
            "not_checked"
          ]
        },
        "emails": {
          "type": "array",
          "description": "OWNER e-mails a building permit published (a key naming the owner's e-mail, e.g. Mecklenburg owner_email_address), on a permit filed in the current owner's era whose owner name matches the current owner (grade C): { email, valid, basis: permit_owner_email, email_key, permit_ref, source, as_of, as_of_basis, grade } Also the latest deed's buyer e-mail where the deed source publishes a contact block (Indiana sales disclosure forms), when the buyer's name matches the current owner (grade C, account required): { email, email_raw (as published), valid, basis: deed_contact_email, deed_ref, source, as_of, as_of_basis: sale_date | recording_date, grade }.",
          "items": {
            "type": "object"
          }
        },
        "none_published": {
          "type": "array",
          "items": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "phone",
              "email",
              null
            ]
          }
        },
        "hidden_low_confidence": {
          "type": "number"
        },
        "people_on_permits": {
          "type": "array",
          "description": "Applicant, contractor and unknown-role phones on the parcel's permits (name mode: across the side-read parcels), newest first, one per (role, number), at most 10: { role: applicant|contractor|unknown (the publisher states no role), role_basis, name, e164, display, ext, phone_raw, permit_ref, era: current_owner|prior_owner|unknown, source, as_of, as_of_basis, grade }. Never the owner's phone.",
          "items": {
            "type": "object"
          }
        },
        "people_on_permits_status": {
          "type": "string",
          "description": "none_published only after the parcel's permits were read in full; not_checked when the read did not run or stopped at its cap.",
          "enum": [
            "listed",
            "none_published",
            "not_checked"
          ]
        },
        "other_addresses": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "parcel_id",
              "state",
              "county",
              "kind",
              "address",
              "same_as",
              "grade",
              "link",
              "basis",
              "label_note",
              "evidence",
              "mail_merge",
              "owner_name_on_record",
              "owner_roles",
              "cited_by",
              "parcels_citing",
              "source",
              "as_of",
              "as_of_basis"
            ],
            "properties": {
              "parcel_id": {
                "type": "string"
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "county": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "address": {
                "type": "object",
                "required": [
                  "line1",
                  "city",
                  "state",
                  "zip5",
                  "zip4",
                  "label",
                  "mail_ready",
                  "po_box"
                ],
                "properties": {
                  "line1": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "city": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "state": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "zip5": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "zip4": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "label": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "mail_ready": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "po_box": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  }
                }
              },
              "same_as": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "grade": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "link": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "basis": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "label_note": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "evidence": {
                "type": "array"
              },
              "mail_merge": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "owner_name_on_record": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "owner_roles": {
                "type": "array"
              },
              "cited_by": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "parcel_id",
                    "state",
                    "county"
                  ],
                  "properties": {
                    "parcel_id": {
                      "type": "string"
                    },
                    "state": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "county": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "parcels_citing": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "source": {
                "type": "object",
                "required": [
                  "authority",
                  "dataset",
                  "url"
                ],
                "properties": {
                  "authority": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "dataset": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "url": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              "as_of": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "as_of_basis": {
                "type": "string"
              }
            }
          }
        },
        "other_addresses_status": {
          "type": "string"
        },
        "other_addresses_scope": {
          "type": "object",
          "required": [
            "name_basis",
            "spellings",
            "parcels_read",
            "capped",
            "copies_skipped",
            "parcels_linked",
            "possible_found",
            "possible_listed",
            "possible_cap",
            "possible_withheld_reason",
            "listed_capped",
            "evidence_providers",
            "co_owner_link"
          ],
          "properties": {
            "name_basis": {
              "type": "string"
            },
            "spellings": {
              "type": "number"
            },
            "parcels_read": {
              "type": "number"
            },
            "capped": {
              "type": "boolean"
            },
            "copies_skipped": {
              "type": "number"
            },
            "parcels_linked": {
              "type": "number"
            },
            "possible_found": {
              "type": "number"
            },
            "possible_listed": {
              "type": "number"
            },
            "possible_cap": {
              "type": "number"
            },
            "possible_withheld_reason": {
              "type": [
                "string",
                "null"
              ]
            },
            "listed_capped": {
              "type": "boolean"
            },
            "evidence_providers": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "id",
                  "status"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "status": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            },
            "co_owner_link": {
              "type": "string"
            }
          }
        },
        "co_owner_scope": {
          "type": "object",
          "description": "Name mode: { parcels_checked, parcels_considered }."
        },
        "mailing_addresses": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/MailingAddress"
          },
          "description": "Name mode: the owner's distinct mailing addresses, most-cited first."
        },
        "phone_scope": {
          "type": "object",
          "description": "Name mode: { parcels_checked, parcels_considered }."
        },
        "email_status": {
          "type": "string",
          "enum": [
            "published",
            "none_published",
            "not_checked"
          ],
          "description": "none_published is claimed only after the permit lookup ran (as phone_status); before 2026-10-09 the card claimed \"no email\" without looking."
        },
        "registry_filings": {
          "type": "array",
          "description": "Secretary of State filings whose registry name equals the owner's exactly (public.sos_name_key; FL Sunbiz today): { registry, doc_number, name, status, filing_type, file_date, state_of_formation, principal_address, mailing_address, registered_agent { name, type, address }, principals [{ title, role, party_type, name, address }], as_of, source, grade }. Grade B for the one filing under the name in the parcel's own state, else C.",
          "items": {
            "type": "object"
          }
        },
        "registry_status": {
          "type": "string",
          "enum": [
            "listed",
            "none_found",
            "not_an_entity",
            "not_checked"
          ],
          "description": "not_an_entity: the owner name reads as an individual and is never looked up in a business registry."
        }
      }
    },
    "note": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "CoOwner": {
      "type": "object",
      "description": "A co-owner of record: another owner the SAME assessor record names beside the owner (OWNER2, ownname2, ADD_OWNER ...), as the county published it. Same source and as-of date as the owner name. Account required, like every people field.",
      "properties": {
        "name": {
          "type": "string"
        },
        "basis": {
          "type": "string",
          "enum": [
            "assessor_co_owner"
          ]
        },
        "source": {
          "$ref": "#/$defs/ContactSource"
        },
        "as_of": {
          "type": [
            "string",
            "null"
          ]
        },
        "as_of_basis": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "roll_year",
            "release_vintage",
            null
          ]
        },
        "grade": {
          "type": "string",
          "enum": [
            "A",
            "B",
            "C",
            "D"
          ]
        }
      }
    },
    "ContactSource": {
      "type": "object",
      "required": [
        "authority",
        "dataset",
        "url"
      ],
      "properties": {
        "authority": {
          "type": "string",
          "description": "Who published the value, e.g. the county assessor."
        },
        "dataset": {
          "type": "string"
        },
        "url": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "MailingAddress": {
      "type": "object",
      "description": "One mailing address, read from ONE address column family of the record (owner_mailing_* or owner_*), never a street from one family and a ZIP from the other.",
      "required": [
        "basis",
        "line1",
        "city",
        "state",
        "zip5",
        "zip4",
        "mail_ready",
        "po_box",
        "equals_situs",
        "zip_conflict",
        "parcels_citing",
        "parcels_citing_basis",
        "label",
        "source",
        "as_of",
        "as_of_basis",
        "grade"
      ],
      "properties": {
        "basis": {
          "type": "string",
          "description": "Where the address came from, e.g. owner_mailing, owner_address, deed_grantee."
        },
        "line1": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "zip5": {
          "type": "string"
        },
        "zip4": {
          "type": [
            "string",
            "null"
          ]
        },
        "mail_ready": {
          "type": "boolean",
          "description": "Street, city, state and a 5-digit ZIP are all present and consistent."
        },
        "po_box": {
          "type": "boolean"
        },
        "equals_situs": {
          "type": "boolean",
          "description": "The mailing address is the property itself (owner-occupied)."
        },
        "zip_conflict": {
          "type": "boolean"
        },
        "parcels_citing": {
          "type": "number",
          "description": "Owner (name) cards only: how many of the owner's parcels carry this address."
        },
        "parcels_citing_basis": {
          "type": "string"
        },
        "label": {
          "type": "string",
          "description": "The address as one mailing label."
        },
        "source": {
          "$ref": "#/$defs/ContactSource"
        },
        "as_of": {
          "type": "string"
        },
        "as_of_basis": {
          "type": "string"
        },
        "grade": {
          "type": "string",
          "description": "A = the authority's own complete record; D = contradictory (hidden unless include_low_confidence=true).",
          "enum": [
            "A",
            "B",
            "C",
            "D"
          ]
        }
      },
      "additionalProperties": false
    }
  }
}