Schema¶
Warning
This is an old version of the data standard. See latest version.
The beneficial ownership standard is made up of two parts:
- A data schema that sets out how beneficial ownership data MUST or SHOULD be formatted for interoperability, and that describes the fields of data that systems MUST or SHOULD provide.
- A set of implementation recommendations that describe the way in which beneficial ownership data SHOULD be collected and published.
Attention
This is the first rough draft of the schema. It is a living document, and undergoing constant updates.
It currently contains a draft structure and fields but does not yet specify any constraints or explicit required fields.
Comments are inviting using hypothes.is annotations (see sidebar on right-hand side), or GitHub issues (https://github.com/openownership/data-standard/issues/) before 20th March.
Conceptual model¶
The conceptual model for the standard was developed in late 2016/early 2017 and is documented here.
We model information on beneficial ownership in terms of a collection of statements. Each statement represents the assertions made by a particular agent at a particular point in time.
It is up to data consumers to decide which statements to trust, and to reconcile the identity of the entities and persons described in those statements based on the identifying information contained within each statement.
This abstraction is important to represent the reality of how data is provided, to support integration of data from different systems and bi-temporal modelling, and to recognise that any dataset may contain overlapping or conflicting claims about ownership and control that need to be resolved in application specific ways.
Schema browser¶
The draft Beneficial Ownership Data Standard is defined using JSON Schema 0.4. The structured schema can be accessed on GitHub or explored using the viewer below.
Serializations¶
We have currently modelled the schema with the option for:
- (1) Entity, person, qualification and provenance statements to be nested inside a beneficial ownership statement;
- (2) Each kind of statement to be provided at the same level of heiarchy, with a cross-reference between them;
This second option is sketched out with a view of serialisations that may make use of the JSON Lines format for sharing or streaming large quantities of statements, rather than enclosing all statements ot be exchanged in a single object.
Sections¶
The following tables are generated from the schema, and outline the different components of the data model.
Statement Groups¶
At the top level of any structured file is always an array of statementGroups
.
Field Name | Description | Format |
---|---|---|
statementGroups | Statement group: A statement group is used to collect together statements relating to a particular disclosure, company or individual. Statement groups are a logical grouping designed to limit duplication of provenance information, and bring together statements that contain cross references. Where statements in a statementGroup cross-references to other statements, those statements MUST also be contained within the group. See statementGroups | Object |
Each statementGroup MUST include an array of one or more beneficialOwnershipStatements
and, where a cross-reference publication pattern is followed, may include arrays of other statements.
Field Name | Description | Format |
---|---|---|
id | Statement group identifier: An optional globally unique and persistent identifier for this statement group. | string |
beneficialOwnershipStatements | Beneficial ownership statements: A collection of statements that describe the relationship between legal entities or between legal entities and natural persons, or that explain the non-availability of this information. Entity, person, qualification and provenance statements may be embeded within these statements, or provided in the neighbouring arrays and cross-referenced. See BeneficialOwnershipStatement section for further details. | Object Array |
entityStatements | Entity statements: A collection of statements that describe legal persons or arrangements. Cross-referenced within beneficial ownership statements. See EntityStatement section for further details. | Object Array |
personStatements | Person statements: A collection of statements that describe natural persons. Cross-referenced within beneficial ownership statements. See EntityStatement section for further details. | Object Array |
qualificationStatements | Qualification statements: A collection of statements that qualify a beneficial ownership statement. Cross-referenced within beneficial ownership statements. See QualificationStatement section for further details. | Object Array |
provenanceStatements | Provenance statements: A collection of provenance statements. See ProvenanceStatement section for further details. | Object Array |
provenance | One of ProvenanceStatement or StatementReference | |
replacesStatementGroup | Replaces statement group: If this statement group replaces all the statements from a previously published group, provide the globally unique identifier for the previous group here. Consuming applications are advised to mark all statements from the identified group as no longer active. | string |
BeneficialOwnershipStatement¶
A beneficial ownership statement is made up of statements about an entity, an interestedParty (either an entity or a person), and detailes of the interest. Additionally, qualifications on this, provenance and versioning information can be provided.
Field Name | Description | Format |
---|---|---|
id | See ID | Object |
date | See StatementDate | Object |
entity | One of StatementReference or EntityStatement | |
interestedParty | One of EntityStatement or PersonStatement or StatementReference | |
interests | Interests: A description of the interests held by the interestedParty covered by this statement in the entity covered by this statement. See Interest section for further details. | Object Array |
qualifications | Qualifications: A qualification statement can be used to record any additional information about this Beneficial Ownership Statement, including information about any reasons non-disclosure of information. | Array |
provenance | One of ProvenanceStatement or StatementReference | |
replacesStatement | See ReplacesStatement | Object |
Interest¶
Field Name | Description | Format |
---|---|---|
type | Type of interest: A codelist value indicating the nature of the interest. List options: [ ‘shareholding’, ‘voting-rights’, ‘appointment-of-board’, ‘influence-or-control’ ] | string |
interestLevel | Interest level: Is this interest held directly or indirectly? List options: [ ‘direct’, ‘indirect’, ‘unknown’ ] | string |
details | Details: This field may be used to provide the local name given to this kind of interest, or any further semi-structured or unstructured information to clarify the nature of the interest held. | string |
share | Percentage share: Where an exact percentage is available, this should be given, and maximum and minimum values set to the same as the exact percentage. Otherwise, maximum and minimum can be used to record the range into which the share of this kind of interest falls. See share | Object |
startDate | State date: When did this interest first occur. Please provide as precise a date as possible in ISO 8601 format. When only the year or year and month is known, these can be given as YYYY or YYYY-MM. | string |
endDate | End date: When did this interest cease. Please provide as precise a date as possible in ISO 8601 format. When only the year or year and month is known, these can be given as YYYY or YYYY-MM. | string |
EntityStatement¶
Field Name | Description | Format |
---|---|---|
id | See ID | Object |
type | Type: What kind of entity is this? The ‘registeredEntity’ code covers any legal entity created through an act of official registration, usually resulting in an identifier being assigned to the entity. The ‘arrangement’ code covers artificial entities, described in the data model for the purpose of associating one or more natural or legal persons together in an ownership or control relationship. List options: [ ‘registeredEntity’, ‘arrangement’ ] | string |
date | See StatementDate | Object |
name | Name: The declared name of this entity. | string |
jurisdiction | Jurisdiction: The jurisdiction in which this entity is registered, expressed using an ISO ISO_3166-2 2-Digit country code, or ISO_3166-2 sub-division code, where the sub-division in question (e.g. a sub-national state or region) has relevant jurisdiction over the registration of operation of this entity. | string |
identifiers | Identifiers: One or more official identifiers for this entity. Where available, official registration numbers should be provided. See Identifier section for further details. | Object Array |
createdDate | Created date: When was this entity first created or registered. Please provide as precise a date as possible in ISO 8601 format. When only the year or year and month is known, these can be given as YYYY or YYYY-MM. | string |
endDate | End date: If this entity is no longer active, provide the date on which it ceased. Please provide as precise a date as possible in ISO 8601 format. When only the year or year and month is known, these can be given as YYYY or YYYY-MM. | string |
addresses | Addresses: One or more addresses for this entity. See Address section for further details. | Object Array |
uri | URI: Where a persisten URI is available for this entity this should be included. | uri string |
provenance | One of ProvenanceStatement or StatementReference | |
replacesStatement | See ReplacesStatement | Object |
PersonStatement¶
Field Name | Description | Format |
---|---|---|
id | See ID | Object |
type | Type: The ultimate beneficial owner of a legal entity is always a natural person. List options: [ ‘naturalPerson’ ] | string |
date | See StatementDate | Object |
name | Name: The full name of this person. | string |
alternateNames | Alternate names: Other known names for this individual. See AlternateName section for further details. | Object Array |
identifiers | Identifiers: One or more official identifiers for this perrson. Where available, official registration numbers should be provided. See Identifier section for further details. | Object Array |
nationalities | Nationality: An array of ISO 2-Digit country codes representing nationalities held by this individual. | Array |
placeOfResidence | See Address | Object |
placeOfBirth | See Address | Object |
birthDate | Created date: The date of birth for this individual. Please provide as precise a date as possible in ISO 8601 format. When only the year or year and month is known, these can be given as YYYY or YYYY-MM. | string |
deathDate | End date: If this individual is no longer alive, provide their date of death. Please provide as precise a date as possible in ISO 8601 format. When only the year or year and month is known, these can be given as YYYY or YYYY-MM. | string |
addresses | Addresses: One or more addresses for this entity. See Address section for further details. | Object Array |
provenance | One of ProvenanceStatement or StatementReference | |
replacesStatement | See ReplacesStatement | Object |
AlternateName¶
Field Name | Description | Format |
---|---|---|
type | Type: What kind of alternative name is this? Select from ‘translation’, ‘formerName’,’birth’, and ‘alias’. List options: [ ‘translation’, ‘former’, ‘alias’, ‘birth’ ] | string |
fullName | Full name: The full name contains the complete name of a person as one string. | string |
familyName | Family name: A family name is usually shared by members of a family. This attribute also carries prefixes or suffixes which are part of the Family Name, e.g. ‘de Boer’, ‘van de Putte’, ‘von und zu Orlow’. Multiple family names, such as are commonly found in Hispanic countries, are recorded in the single Family Name field so that, for example, Miguel de Cervantes Saavedra’s Family Name would be recorded as ‘Cervantes Saavedra.’ | string |
givenName | Given names: A given name, or multiple given names, are the denominator(s) that identify an individual within a family. These are given to a person by his or her parents at birth or may be legally recognised as ‘given names’ through a formal process. All given names are ordered in one field so that, for example, the given name for Johan Sebastian Bach is ‘Johan Sebastian.’ | string |
patronymicName | Patronymic Name: Patronymic names are important in some countries. Iceland does not have a concept of family name in the way that many other European countries do, for example. In Bulgaria and Russia, patronymic names are in every day usage, for example, the ‘Sergeyevich’ in ‘Mikhail Sergeyevich Gorbachev’ | string |
QualificationStatement¶
Field Name | Description | Format |
---|---|---|
id | See ID | Object |
date | See StatementDate | Object |
type | Type of qualification statement: List options: [ ‘non-disclosure’, ‘redaction’, ‘restrictions-on-control’ ] | string |
description | Description: A description of this qualification | string |
provenance | One of ProvenanceStatement or StatementReference | |
replacesStatement | See ReplacesStatement | Object |
ProvenanceStatement¶
See the provenance pages for a discussion of provenance modelling.
Field Name | Description | Format |
---|---|---|
id | See ID | Object |
type: | Source type: What kind of source is this? [ToDo: Identify an appropriate codelist for this field] List options: [ ‘official-records’, ‘unverified-submission’, ‘verified-submission’ ] | string |
attributedTo | Attributed to: Which agent (individual, organisation or software process) was responsible for directly contributing this source. See attributedTo | Object |
generatedBy | Generated by: Which activity led to the creation of this source? See generatedBy | Object |
primarySource | Primary source: A link to a primary source. This may be a resolvable URI, or some other identifier for the source. | uri string |
derivedFrom | Derived from: If this source was derived from a prior source either provide the identifier of a provenanceStatement about that prior source, or nest the provenace statement here. One of ProvenanceStatement or StatementReference | |
replacesStatement | See ReplacesStatement | Object |
StatementReference¶
Field Name | Description | Format |
---|---|---|
type | Type: What type of statement is being referred to? List options: [ ‘entityStatement’, ‘personStatement’, ‘provenanceStatement’, ‘qualificationStatement’ ] | string |
id | ID: The identifier of the statement being referenced. | string |
uri | URI: A persistent URI for the statement being referenced. | uri string |
Common components¶
The following components are used at a number of points in the schema
Address¶
Field Name | Description | Format |
---|---|---|
type | Type: What type of address is this? List options: [ ‘placeOfBirth’, ‘home’, ‘residence’, ‘registered’, ‘service’, ‘alternative’ ] | string |
address | Address: The address, with each line or component of the address separated by a line-break or comma. This field may also include the postal code. | string |
postCode | Postcode: The postal code for this address. | string |
country | Country: The ISO 2-Digit county code for this address. | string |
Identifier¶
The identifier component is used to connect a statement to the person or entity that it refers to, using one or more existing known identifiers.
Field Name | Description | Format |
---|---|---|
id | ID: The identifier for this entity as provided in the declared scheme. | string |
scheme | Scheme: For entity statements, the scheme should be a entry from the org-id.guide codelist. For person statements, recognised values include ‘passport’, ‘internal’ and ‘id-card’. | string |
uri | URI: Where this identifier has a canonical URI this may be included | uri string |
Date¶
See https://github.com/openownership/data-standard/issues/12 for a discussion of handling fuzzy dates.
Our current schema uses a regular expression to allow YYYY, YYYY-MM, YYYY-MM-DD or full datetimes.
ID¶
Publishers MUST generate globally unique and persisent identifiers for each statement.
These SHOULD start with a uuid to avoid any clash between identifiers from different publishers, and MAY be suffixed with additional characters to distinguish versions of a statement as required by local implementations.
In many implementation scenarios, it will be appropriate to simply generate a distinct uuid for each statement.
Publication and use considerations¶
This section outlines considerations for publishers and consumers of the data
Immutability of statements¶
Statements are considered immutable. If a field is updated, this should be considered to create a new statement, with a new identifier.
Updating statements¶
Where a statementGroup
or statement
replaces a previous statement this should be explicitly declared using a replacesStatementGroup
or replacesStatement
property.