{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/eckari-com/json-schema/eckari-com-company-uk-owners-output-schema.json",
  "title": "company_uk_owners_output",
  "description": "Contains public sector information licensed under the Open Government Licence v3.0 (Companies House).",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/eckari-com-openapi.json#/components/schemas/company_uk_owners_output",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "company_number",
    "query",
    "active_count",
    "ceased_count",
    "items",
    "page",
    "statements",
    "active_statement_count",
    "exemptions",
    "ownership_status"
  ],
  "properties": {
    "company_number": {
      "type": "string"
    },
    "query": {
      "type": "object",
      "description": "The resolved filter, echoed because page.total depends on it.",
      "additionalProperties": false,
      "required": [
        "include_ceased"
      ],
      "properties": {
        "include_ceased": {
          "type": "boolean"
        }
      }
    },
    "active_count": {
      "type": "integer",
      "description": "Register-wide count of PSC entries with no cessation date. Not a count of the returned page."
    },
    "ceased_count": {
      "type": "integer",
      "description": "Register-wide count of ceased PSC entries. Not a count of the returned page."
    },
    "items": {
      "type": "array",
      "description": "PSC entries in the register's own order. Ceased entries are omitted unless include_ceased is true.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "kind",
          "is_active",
          "notified_on",
          "ceased_on",
          "natures_of_control",
          "is_sanctioned"
        ],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "PSC name as published. Null only for super-secure entries, where the register withholds the individual's particulars."
          },
          "kind": {
            "type": [
              "string",
              "null"
            ],
            "description": "PSC kind (e.g. individual-person-with-significant-control, corporate-entity-person-with-significant-control, legal-person-with-significant-control, super-secure-person-with-significant-control, or the *-beneficial-owner variants for registered overseas entities)."
          },
          "is_active": {
            "type": "boolean",
            "description": "Derived; true when the register records no cessation date for this PSC entry. It describes the entry, not the company — a dissolved company can still carry a PSC entry with no cessation date, so check company.uk.status for the company's own state."
          },
          "notified_on": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "ceased_on": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "natures_of_control": {
            "type": "array",
            "description": "How this person or entity controls the company, in the register's own order — one entry per nature of control, each carrying the register code and its official text. Empty when the register lists none.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "code",
                "description"
              ],
              "properties": {
                "code": {
                  "type": "string",
                  "description": "Companies House natures_of_control code exactly as published (e.g. ownership-of-shares-75-to-100-percent, voting-rights-25-to-50-percent, right-to-appoint-and-remove-directors, significant-influence-or-control). The stable key for machine matching."
                },
                "description": {
                  "type": "string",
                  "description": "Official Companies House text for the code, from the register's published psc_descriptions enumeration (e.g. \"The person holds, directly or indirectly, more than 75% of the shares in the company.\"). An unrecognised future code echoes back as its own description; never invented."
                }
              }
            }
          },
          "nationality": {
            "type": [
              "string",
              "null"
            ]
          },
          "country_of_residence": {
            "type": [
              "string",
              "null"
            ]
          },
          "date_of_birth": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": false,
            "required": [
              "month",
              "year"
            ],
            "properties": {
              "month": {
                "type": "integer"
              },
              "year": {
                "type": "integer"
              }
            }
          },
          "address": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": false,
            "properties": {
              "care_of": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "premises": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "address_line_1": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "address_line_2": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "po_box": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "locality": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "region": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "identification": {
            "type": [
              "object",
              "null"
            ],
            "description": "Corporate/legal-person identification where applicable.",
            "additionalProperties": false,
            "properties": {
              "legal_authority": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "legal_form": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "place_registered": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "registration_number": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country_registered": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "is_sanctioned": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Register-declared flag, passed through unchanged. Companies House only ever populates it for beneficial owners on the Register of Overseas Entities, where the filer declares whether the person is designated under UK sanctions legislation; it is null for every other PSC entry and null does NOT mean 'not sanctioned'. This is NOT a sanctions screening result: Eckari runs no screening, checks no list and infers nothing. Screen against an authoritative sanctions source before relying on it."
          }
        }
      }
    },
    "statements": {
      "type": "array",
      "description": "PSC statements filed against the company — the register's own explanation of why a PSC entry is absent or incomplete (no registrable person, PSC not identified, restrictions notice, super-secure, and the Register of Overseas Entities beneficial-owner statements). Ceased statements are omitted unless include_ceased is true. This collection is fetched whole, not paged by limit/offset, so ownership_status does not drift between pages.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "statement",
          "description",
          "notified_on",
          "ceased_on",
          "linked_psc_name"
        ],
        "properties": {
          "statement": {
            "type": "string",
            "description": "Companies House statement key (e.g. no-individual-or-entity-with-signficant-control, psc-exists-but-not-identified, restrictions-notice-issued-to-psc, no-beneficial-owner-identified)."
          },
          "description": {
            "type": "string",
            "description": "Official statement text from the Companies House psc_descriptions enumeration. Falls back to the raw key when the register publishes a key we do not yet carry; never invented."
          },
          "notified_on": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "ceased_on": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "linked_psc_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the PSC the statement refers to, where the register links one."
          }
        }
      }
    },
    "active_statement_count": {
      "type": "integer",
      "description": "Number of statements with no cessation date. Unaffected by include_ceased."
    },
    "page": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "limit",
        "offset",
        "returned",
        "total",
        "has_more",
        "next_offset"
      ],
      "properties": {
        "limit": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The page size applied (the requested limit, default 10)."
        },
        "offset": {
          "type": "integer",
          "description": "The register index this page started at (the requested offset)."
        },
        "returned": {
          "type": "integer",
          "description": "Number of PSC entries in this response."
        },
        "total": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Register-wide count of PSC entries matching the filter in force: the register's total when include_ceased is true, and its active count when it is false. Never a count of this page."
        },
        "has_more": {
          "type": "boolean",
          "description": "Authoritative end-of-list signal; true when PSC entries matching the current filter remain beyond this page — either because more matches were read than limit allows, or because the register list was not exhausted within the three-page read budget. items.length < limit is NOT a valid end-of-list test, and neither is comparing against active_count or ceased_count, which are register-wide."
        },
        "next_offset": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Derived; the register index to pass as offset to continue after the last PSC returned. Because ceased entries are filtered after the read, this is the register index of the next matching entry and can be greater than offset + returned. Null exactly when has_more is false."
        }
      }
    },
    "exemptions": {
      "type": "array",
      "description": "PSC exemptions recorded against the company. This is where the register records a listed company's exemption from the PSC regime (DTR5 / voting shares admitted to a regulated market) — it is a separate register collection from statements, and it is the reason a listed PLC discloses no PSC. Historic (closed) exemptions are returned too, flagged by is_current false.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "exemption_type",
          "description",
          "exempt_from",
          "exempt_to",
          "is_current"
        ],
        "properties": {
          "exemption_type": {
            "type": "string",
            "description": "Companies House exemption key (e.g. psc-exempt-as-trading-on-uk-regulated-market, disclosure-transparency-rules-chapter-five-applies)."
          },
          "description": {
            "type": "string",
            "description": "Official exemption text from the Companies House exemption_descriptions enumeration. Falls back to the raw key when unknown; never invented."
          },
          "exempt_from": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "exempt_to": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date the exemption ended; null while it remains in force., format: date"
          },
          "is_current": {
            "type": "boolean",
            "description": "Derived; true when the register records no end date for the exemption."
          }
        }
      }
    },
    "ownership_status": {
      "type": "string",
      "description": "Single derived answer to \"does this company disclose owners, and if not, why not?\". Precedence, highest first. (1) pscs_listed — at least one active PSC entry is listed in items (this also covers the Register of Overseas Entities statement all-beneficial-owners-identified, which is meaningful only alongside listed entries). (2) exempt_listed_company — a current PSC exemption, or an active statement whose key starts psc-exempt-. (3) no_psc_declared — an active statement no-individual-or-entity-with-signficant-control (or its -partnership form), or the Register of Overseas Entities statement no-beneficial-owner-identified: the entity positively declares it has no registrable person. (4) psc_not_identified — an active statement saying an owner exists but the register does not (yet) identify them: psc-exists-but-not-identified, psc-details-not-confirmed, steps-to-find-psc-not-yet-completed, psc-contacted-but-no-response, psc-has-failed-to-confirm-changed-details, restrictions-notice-issued-to-psc, awaiting-confirmation-from-psc, their -partnership forms, the Register of Overseas Entities keys at-least-one-beneficial-owner-unidentified and information-not-provided-for-at-least-one-beneficial-owner (and the combined form), and all-beneficial-owners-identified filed with no PSC entry on the register. (5) super_secure — an active super-secure statement, or an active PSC entry the register marks super-secure, where the individual's particulars are withheld. (6) no_information — the register holds no PSC entry, no active statement and no exemption at all. Any other active statement key, including one the register publishes in future, is reported as psc_not_identified, so no_information is never returned while the register is explaining itself. An empty items list never on its own means the company has no owner. Paging caveat: for a company whose every active PSC entry is super-secure, a page that skips past those entries reports pscs_listed rather than super_secure — both are truthful (the entry is listed), and no page can turn a company with disclosed PSCs into super_secure.",
      "enum": [
        "pscs_listed",
        "exempt_listed_company",
        "no_psc_declared",
        "psc_not_identified",
        "super_secure",
        "no_information"
      ]
    }
  }
}