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.

Conceptual Model

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

Share

Field Name Description Format
exact Exact share: The exact share of this interest held (where available). number
maximum Maximum share: The upper bound of the share of this interest known to be held. number
minimum Minimum share: The lower bound of the share of this interest known to be held. number
exclusiveMinimum Exclusive minimum: If exclusiveMinimum is true, then the share is at least greater than the minimum value given. E.g. if minimum is 25, the share is at least 25.1, and not simply 25. boolean
exclusiveMaximum Exclusive maximum: If exclusiveMaximum is true, then the share is at least less than the maximum value given. E.g. if maximum is 50, the share is less than 49.999, and not simply 50. boolean

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.