control-statement-schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A Control Statement is a statement by a company or entity about a the control of a company. In its most straightforward, Company A may say that Entity B controls it. Each statement should be about a single control relationship, i.e. if Company A has two controlling entities, B and C, and those   control relationships are distinct (e.g. they started at a different time) then they should each be stored as a indiviudal Control Statements. They should only be stored in the same Control Statement if it is logically part of the same control mechanism, e.g. if company A is controlled by person C and person D, who control the shares *jointly*. Control Statements can be used to describe that an entity has no controlling entity, or that the controlling entity is not disclosed. Beneficial Ownership is a specific example of control relationships, and the ultimate_beneficial_owner flag can be used to signify that a person is the Ultimate Beneficial Owner of a company",
  "properties": {
    "subject_entity": {
      "$ref": "includes/entity.json"
    },
    "control_level": {
      "description": "The level of control, i.e. whether the control is direct (i.e. there are no intermediaries), indirect (there are intermediaries) or unknown. It can be null in the case where a company is saying that there are no controlling entities",
      "enum": [
        "direct",
        "indirect",
        "unknown",
        null
      ]
    },
    "ultimate_beneficial_owner": {
      "description": "Whether the controlling entities are the ultimate beneficial owners (i.e. individuals who ultimately control the company)",
      "type": "boolean"
    },
    "controlling_entities": {
      "type": "array",
      "items": {
        "$ref": "includes/entity.json"
      }
    },
    "control_mechanisms": {
      "description": "The mechanism(s) by which the controlling party/parties control the company",
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": [
              "string",
              "null"
            ],
            "minLength": 2
          },
          {
            "$ref": "#/definitions/control_mechanism"
          }
        ]
      }
    },
    "no_controlling_entities_reasons": {
      "description": "The reason why no controlling entities are declared, for example because the entity has been unable to discover them, or there are no controlling entities (e.g. 100 people owned 1% each), or the companies is exempt from reporting (as some listed companies are in some jurisdictions)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "uid": {
      "description": "Unique id/reference for the control relationship entity record if the external source has given it one",
      "type": "string"
    },
    "url": {
      "description": "Persistent URL on the external source for the control relationship entity record, if there is one",
      "type": "string"
    },
    "source_url": {
      "description": "Source url of the web page for the filing or if there is not persistent URL the page from which it can be found (e.g. search page). This field is required.",
      "type": "string",
      "minLength": 11
    },
    "confidence": {
      "description": "Confidence in accuracy of data",
      "type": "string",
      "enum": [
        "HIGH",
        "MEDIUM",
        "LOW"
      ]
    },
    "start_date": {
      "description": "Date on which control started",
      "type": "string",
      "format": "date"
    },
    "start_date_type": {
      "enum": [
        "at",
        "before",
        "after"
      ]
    },
    "end_date": {
      "description": "Date on which control ended",
      "type": "string",
      "format": "date"
    },
    "end_date_type": {
      "enum": [
        "at",
        "before",
        "after"
      ]
    },
    "retrieved_at": {
      "description": "Date-time this was retrieved from the source",
      "type": "string",
      "format": "date-time"
    },
    "sample_date": {
      "description": "Date on which we know this to be true (for example the date the control statement was published)",
      "type": "string",
      "format": "date"
    },
    "other_attributes": {
      "description": "Use for other attributes for which we don't yet have curated schema attributes",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "control_level",
    "subject_entity",
    "retrieved_at",
    "source_url",
    "sample_date",
    "confidence"
  ],
  "definitions": {
    "control_mechanism": {
      "title": "Control Mechanism",
      "description": "A specific mechanism(s) by which controls of a company is exercised",
      "oneOf": [
        {
          "properties": {
            "mechanism_type": {
              "enum": [
                "share_ownership"
              ]
            },
            "mechanism_properties": {
              "properties": {
                "number_of_shares": {
                  "description": "Number of shares",
                  "type": "integer"
                },
                "percentage_of_shares": {
                  "description": "Percentage of shares",
                  "oneOf": [
                    {
                      "type": "number",
                      "maximum": 100,
                      "minimum": 0
                    },
                    {
                      "$ref": "includes/range.json"
                    }
                  ]
                },
                "share_class": {
                  "description": "Share class or classes",
                  "type": "string"
                },
                "exercised_via": {
                  "enum": [
                    "trust",
                    "firm",
                    null
                  ]
                }
              }
            },
            "source_description": {
              "description": "Description of the control relationship as given by the source",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        {
          "properties": {
            "mechanism_type": {
              "enum": [
                "voting_rights"
              ]
            },
            "mechanism_properties": {
              "properties": {
                "voting_percentage": {
                  "description": "Percentage of votes",
                  "oneOf": [
                    {
                      "type": "number",
                      "maximum": 100,
                      "minimum": 0
                    },
                    {
                      "$ref": "includes/range.json"
                    }
                  ]
                },
                "exercised_via": {
                  "enum": [
                    "trust",
                    "firm",
                    null
                  ]
                }
              }
            },
            "source_description": {
              "description": "Description of the control relationship as given by the source",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        {
          "properties": {
            "mechanism_type": {
              "enum": [
                "right_to_appoint_and_remove_directors"
              ]
            },
            "mechanism_properties": {
              "properties": {
                "exercised_via": {
                  "enum": [
                    "trust",
                    "firm",
                    null
                  ]
                }
              }
            },
            "source_description": {
              "description": "Description of the control relationship as given by the source",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        {
          "properties": {
            "mechanism_type": {
              "enum": [
                "right_to_appoint_and_remove_members"
              ]
            },
            "mechanism_properties": {
              "properties": {
                "exercised_via": {
                  "enum": [
                    "trust",
                    "firm",
                    null
                  ]
                }
              }
            },
            "source_description": {
              "description": "Description of the control relationship as given by the source",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        {
          "properties": {
            "mechanism_type": {
              "enum": [
                "right_to_appoint_and_remove_person"
              ]
            },
            "mechanism_properties": {
              "properties": {
                "exercised_via": {
                  "enum": [
                    "trust",
                    "firm",
                    null
                  ]
                }
              }
            },
            "source_description": {
              "description": "Description of the control relationship as given by the source",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        {
          "properties": {
            "mechanism_type": {
              "enum": [
                "right_to_share_surplus_assets"
              ]
            },
            "mechanism_properties": {
              "properties": {
                "exercised_via": {
                  "enum": [
                    "trust",
                    "firm",
                    null
                  ]
                },
                "percentage_rights": {
                  "description": "Percentage of rights to assets in the event of a winding up of the entity",
                  "oneOf": [
                    {
                      "type": "number",
                      "maximum": 100,
                      "minimum": 0
                    },
                    {
                      "$ref": "includes/range.json"
                    }
                  ]
                }
              }
            },
            "source_description": {
              "description": "Description of the control relationship as given by the source",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        {
          "properties": {
            "mechanism_type": {
              "enum": [
                "significant_influence_or_control"
              ]
            },
            "mechanism_properties": {
              "properties": {
                "exercised_via": {
                  "enum": [
                    "trust",
                    "firm",
                    null
                  ]
                }
              }
            },
            "source_description": {
              "description": "Description of the control relationship as given by the source",
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      ]
    }
  }
}