Data Schema / Schema reference

Schema reference

Attention

This is v0.1-rc (release candidate) of the Beneficial Ownership Data Standard. It includes updates to the data model and additional codelist information. Implementers should be aware that future changes are anticipated, before a version 1.0 release. See the Changelog and About pages for more information.

MUST and SHOULD are used in the schema to denote required and recommended elements of the Standard, as defined in RFC2119.

The following is an A - Z guide to the objects of the Data Standard’s schema, plus its codelists . Details of each object’s properties are provided in a table generated from the JSON schema. (For a structured view of how objects fit together in the JSON schema, use the Schema browser.)

The top-level objects are statements:

Statements are built up from a set of nested objects and properties, each of which has a field name, a title and a description that defines how the object or field should be used.

BODS data MAY be published as a valid JSON document. See Serialization for more options.

Address

A free text address string, providing as much address data as is relevant, suitable for processing using address parsing algorithms. For some uses (for example, Place of Birth) only a town and country are required.

Title Description Type Format Required
type string    
Type What type of address is this? See the addressType codelist.
address string    
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.
postCode string    
Postcode The postal code for this address.
country string    
Country The ISO 2-Digit county code for this address.

Note

A diversity of address formats are used across data management systems, and data is often inconsistently entered across data fields in these source systems (and legacy datasets). Therefore the BODS schema uses a very simple address format for data exchange. Consuming systems will need to parse BODS addresses before carrying out any structured comparison.

Designers of new data collection systems are encouraged to choose an appropriate structured format, with reference to established standards, and awareness of the need to accomodate addresses from across the world. See issue 18 for more details.

Agent

An individual, organisation or other responsible agent making, or supporting, a given statement or annotation.

Title Description Type Format Required
name string    
Name The name of the agent
uri string uri  
URI An optional URI to identify the agent.

Annotation

The annotations property of statements currently allows an array of these simple annotation objects to be included. An annotation can be used to hold information (structured or otherwise) for which a place does not exist elsewhere in the schema. See Sources and annotations for further guidance.

Title Description Type Format Required
statementPointerTarget string    
Statement Fragment Pointer An RFC6901 JSON Pointer describing the target fragment of the statement that this annotation applies to, starting from the root of the statement. A value of ‘/’ indicates that the annotation applies to the whole statement.
creationDate string date  
Creation Date The date this annotation was created.
createdBy object    
Created By The person, organisation or agent that created this annotation.
createdBy/name string    
Name The name of the person, organisation or agent that created this annotation.
createdBy/uri string uri  
URI An optional URI to identify person, organisation or agent that created this annotation.
motivation string    
Motivation The motivation for this annotation, chosen from a codelist. See the annotationMotivation codelist.
description string    
Description A free-text description to annotate this statement or field.
transformedContent string    
Transformed content A representation of the annotation target after the transformation in the description field has been applied. This field SHOULD only be used when the motivation is transformation.
url string uri  
URL A linked resource that annotates, provides context for or enhances this statement. The content of the resource, or the relationship to the statement, MAY be described in the description field.

Country

A country MUST have a name. A country SHOULD have an ISO 2-Digit county code.

Title Description Type Format Required
name string    
Name The name of the country
code string    
Country code The ISO 2-digit code for the country.

EntityStatement

A statement identifying and describing the entity that is the subject of the ownership or control described in an ownership or control statement.

Title Description Type Format Required
statementID string   Required
Statement Identifier

A persistent globally unique identifier for this statement.

See ID

statementType string   Required
Statement type This should always be ‘entityStatement.
statementDate string date  
Statement date

The date on which this statement was made.

See StatementDate

entityType string   Required
Type From the entityType codelist. 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 ‘legalEntity’ code covers other bodies with distinct legal personality (government departments, international institutions etc.). 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, but without implying that the parties to this arrangement have any other form of collective legal identity.
missingInfoReason string    
Missing information reason(s) For EntityStatements with the type ‘anonymousEntity’ or ‘unknownEntity’ this field should contain an explanation of the reason that detailed information on the entity is not provided. This may be a standard descriptive phrase from the source system, or a free-text justification.
name string    
Entity name The declared name of this entity.
alternateNames array[string]    
Alternative names An array of other names this entity is known by.
incorporatedInJurisdiction object    
Incorporated In Jurisdiction

Details on where this legal entity is incorporated

See Jurisdiction

identifiers array[Identifier]    
Identifiers

One or more official identifiers for this entity. Where available, official registration numbers should be provided.

See Identifier

foundingDate string    
Founding date When was this entity founded, 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.
dissolutionDate string    
Dissolution date If this entity is no longer active, provide the date on which it was disolved or 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.
addresses array[Address]    
Addresses

One or more addresses for this entity.

See Address

uri string uri  
URI Where a persistent URI is available for this entity this should be included.
replacesStatements array[string]    
Replaces statement(s)

If this statement replaces a previous statement or statements, provide the identifier(s) for the previous statement(s) here. Consuming applications are advised to mark the identified statements as no longer active.

See ReplacesStatements

source object    
Source

The source of information about this entity, or of information that supports an anonymous or unknown entity statement.

See Source

annotations array[Annotation]    
Annotations

Annotations about this statement or parts of this statement

See Annotation

Identifier

The identifier component is used to connect a statement to the real-world person or entity that it refers to, using one or more existing known identifiers. See [Real world identifiers](identifiers.md) for technical guidance on when and how to use this component.

An identifier that has been assigned to this person or entity. The scheme or list from which the identifier is drawn should be declared.

Title Description Type Format Required
id string    
ID The identifier for this person or entity as provided in the declared scheme.
scheme string    
Scheme For entity statements, the scheme should be a entry from the org-id.guide codelist. For person statements, the scheme should have the pattern {JURISDICTION}-{TYPE} where JURISDICTION is an ISO 3-digit country code and TYPE is one of PASSPORT, TAXID or IDCARD.
schemeName string    
Scheme name
uri string uri  
URI Where this identifier has a canonical URI this may be included

Interest

A description of the interest held by an interestedParty in another entity.

Title Description Type Format Required
type string    
Type of interest A codelist value indicating the nature of the interest. See the interestType codelist
interestLevel string    
Interest level Is this interest held directly or indirectly?
beneficialOwnershipOrControl boolean    
Beneficial ownership or control Does this statement assert this as a beneficial ownership or control interest? A beneficial ownership or control interest is always between a natural person and some entity, and exists where the person ultimately benefits from, or has a degree of control over, the entity. There may be cases where a person has an interest in an entity, but where there are arrangements or other conditions that mean this interest does not constitute beneficial ownership or control.
details string    
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.
share object    
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.
startDate string    
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.
endDate string    
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.

InterestedParty

The interested party has some level of ownership or control over the entity referenced in this ownership or control statement. This should be described with reference to either an entity statement or person statement, or, where the interested party is unknown, details of why.

Title Description Type Format Required
describedByEntityStatement string    
Described by entity statement A reference to a statement describing a registered entity, trust or arrangement that has an ownership or control interest in the subject of this statement. An entityStatement should be used when the direct interests to be described represents known control or ownership by anyone other than a natural person.
describedByPersonStatement string    
Described by person statement A reference to a statement describing a natural person who has an ownership or control interest in the subject of this statement.
unspecified object    
Unspecified or unknown ownership and control When confirmation has been provided that no interested party exists, where ownership and control information does not need to be provided, or where details of ownership and control are unknown, information explaining this should be given using the unspecified reason and description. Where there is a natural person with ownership or control, but their name or details are not known, or cannot be disclosed for some reason, unspecified should not be used, but instead a reference to a personStatement should be provided but identifying details of the person left blank.
unspecified/reason string   Required
Reason The reason that an interested party cannot be specified. From the unspecifiedReason codelist.
unspecified/description string    
Description Any supporting information about the absence of a confirmed beneficial owner. This field may be used to provide set phrases from a source system, or for a free-text explanation.

Jurisdiction

A jurisdiction MUST have a name. A jurisdiction SHOULD have an ISO ISO_3166-2 2-Digit country code, or ISO_3166-2 sub-division code.

Title Description Type Format Required
name string    
Name The name of the jurisdiction
code string    
Country code The ISO_3166-2 2-Digit country code, or ISO_3166-2 sub-division code of the jurisdiction

Name

An name by which this individual is known. Names should be provided in fullName, and may optionally be broken down in the familyName, givenName and patronymicName fields, based on the [EC ISA Core Person Vocabulary](https://joinup.ec.europa.eu/solution/e-government-core-vocabularies) definitions.

Title Description Type Format Required
type string    
Type What kind of name is this? See the nameType codelist.
fullName string    
Full name The full name contains the complete name of a person as one string.
familyName string    
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.’
givenName string    
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 Johann Sebastian Bach is ‘Johann Sebastian.’
patronymicName string    
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’

OwnershipOrControlStatement

An ownership or control statement is made up of an entity, an interested party (a reference to an entity, natural person, arrangement or trust), details of the interest and provenance information for the statement.

Title Description Type Format Required
statementID string   Required
Statement Identifier

A persistent globally unique identifier for this statement.

See ID

statementType string   Required
Statement type This should always be set to ownershipOrControlStatement.
statementDate string date  
Statement date

The date on which this statement was made.

See StatementDate

subject object   Required
Subject The subject of an ownership or control relationship.
subject/describedByEntityStatement string   Required
Described by entity statement Provide the identifier of the statement which describes the entity that the subject of an ownership or control interest.
interestedParty object   Required
Interested party

The interested party has some level of ownership or control over the entity referenced in this ownership or control statement. This should be described with reference to either an entity statement or person statement, or, where the interested party is unknown, details of why.

See InterestedParty

interests array[Interest]    
Interests

A description of the interests held by the interestedParty covered by this statement in the entity covered by this statement.

See Interest

source object    
Source

The source of the information that links the entity and the interested party, or that supports a null statement.

See Source

annotations array[Annotation]    
Annotations

Annotations about this statement or parts of this statement

See Annotation

replacesStatements array[string]    
Replaces statement(s)

If this statement replaces a previous statement or statements, provide the identifier(s) for the previous statement(s) here. Consuming applications are advised to mark the identified statements as no longer active.

See ReplacesStatements

PEPStatus

A description of a politically-exposed person status.

Title Description Type Format Required
reason string    
Reason The reason for this person being declared a politically-exposed person.
jurisdiction object    
Jurisdiction

A jurisdiction MUST have a name. A jurisdiction SHOULD have an ISO ISO_3166-2 2-Digit country code, or ISO_3166-2 sub-division code.

See Jurisdiction

startDate string    
State date When did this PEP status begin. 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.
endDate string    
End date When did this PEP status end. 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.

PersonStatement

A person statement describes the information known about a natural person at a particular point in time, or from a given submission of information

Title Description Type Format Required
statementID string   Required
Statement Identifier

A persistent globally unique identifier for this statement.

See ID

statementType string   Required
Statement type This should always be ‘personStatement.
statementDate string date  
Statement date

The date on which this statement was made.

See StatementDate

personType string    
Person type Use the personType codelist. The ultimate beneficial owner of a legal entity is always a natural person. Where the beneficial owner has been identified, but information about them cannot be disclosed, use ‘anonymousPerson’. Where the beneficial owner has not been clearly identified, use ‘unknownPerson’. Where the beneficial owner has been identified use knownPerson.
missingInfoReason string    
Missing information reason(s) For PersonStatements with the type ‘anonymousPerson’ or ‘unknownPerson’ this field should contain an explanation of the reason that detailed information on the person is not provided. This may be a standard descriptive phrase from the source system, or a free-text justification.
names array[Name]    
Names

One or more known names for this individual.

See Name

identifiers array[Identifier]    
Identifiers

One or more official identifiers for this perrson. Where available, official registration numbers should be provided.

See Identifier

nationalities array[Country]    
Nationality

An array of ISO 2-Digit country codes representing nationalities held by this individual.

See Country

placeOfBirth object    
Place of birth

A free text address string, providing as much address data as is relevant, suitable for processing using address parsing algorithms. For some uses (for example, Place of Birth) only a town and country are required.

See Address

birthDate string    
Date of birth 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.
deathDate string    
Death 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.
placeOfResidence object    
Place of residence

A free text address string, providing as much address data as is relevant, suitable for processing using address parsing algorithms. For some uses (for example, Place of Birth) only a town and country are required.

See Address

addresses array[Address]    
Addresses

One or more addresses for this entity.

See Address

pepStatus array[PEP Status]    
Politically Exposed Person Status

One or more descriptions of this person’s Politically-Exposed Person (PEP) status.

See PepStatus

source object    
Source

The source of information about this person, or of information that supports an unknown or anonymous person statement.

See Source

annotations array[Annotation]    
Annotations

Annotations about this statement or parts of this statement

See Annotation

replacesStatements array[string]    
Replaces statement(s)

If this statement replaces a previous statement or statements, provide the identifier(s) for the previous statement(s) here. Consuming applications are advised to mark the identified statements as no longer active.

See ReplacesStatements

ReplacesStatements

replacesStatements

If this statement replaces a previous statement or statements, provide the identifier(s) for the previous statement(s) here. Consuming applications are advised to mark the identified statements as no longer active.

See Updating statements for technical guidance on working with updates to data.

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.

Title Description Type Format Required
exact number    
Exact share The exact share of this interest held (where available).
maximum number    
Maximum share The upper bound of the share of this interest known to be held.
minimum number    
Minimum share The lower bound of the share of this interest known to be held.
exclusiveMinimum boolean    
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.
exclusiveMaximum boolean    
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.

Source

The source object is used to explain where information in a statement originated from, and to link to supporting information.

Title Description Type Format Required
type array[string]    
Source type What type of source is this? Multiple tags can be combined. Values should come from the source type codelist.
description string    
Description Where required, additional free-text information about the source of this statement can be provided here.
url string    
Source URL If this information was fetched from an external URL, or a machine or human readable web page is available that provides additional information on how this statement was sourced, provide the URL.
retrievedAt string date-time  
Retrieved at If this statement was imported from some external system, include a timestamp indicating when this took place. The statement’s own date should be set based on the source information.
assertedBy array[Agent]    
Asserted by

Who is making this statement? This may be the name of the person or organisation making a self-declaration (in which case, please make sure the name field matches the organisation or person name field), or the name or description of some other party. If this statement has been verified, this may also include the name of the organisation providing verification.

See Agent

See Sources and annotations for a discussion of provenance modelling.

StatementDate

Dates MUST conform with the extended format of ISO 8601. All of the following, for example, are valid:

  • A full datetime string (YYYY-MM-DDTHH:MM:SSZ)
  • A year, month and day (YYYY-MM-DD)
  • A year and month (YYYY-MM)
  • A year (YYYY)

Codelists

AddressType

code title description technical note
placeOfBirth Place of birth    
home Home address    
residence Residential address    
registered Registered address    
service Service address    
alternative Alternative address    

AnnotationMotivation

code title description technical note
commenting Commenting The description field provides contextual comments for a field, object or statement.  
correcting Correcting The value of this field, object or statement has been corrected, using the method in the description field and/or from the original value given in the description field.  
identifying Identifying The value of this field, object or statement has been augmented or processed for the purpose of identifying natural persons or legal entities, using the method in the description field.  
linking Linking The description provide contextual material that explains the field, object or statement. URLs to linked material are be provided in the url field.  
transformation Transformation The values of this field, object or statement have been changed from their original form using the method in the description field. The transformed representation may be provided in the transformedContent field.  

EntityType

code title description technical note
registeredEntity Registered Entity Any legal entity created through an act of official registration. In most cases, registered entities will have an official issued identifier.  
legalEntity Legal entity A body with distinct legal personality, such as a government departments or international institutions, but which is not otherwise uniquely identified in some official register.  
arrangement Arrangement An artificial entity, created by agreements, contracts or other processes.  
anonymousEntity Anonymous entity An entity that has been identified, but for which no identifying information is being published.  
unknownEntity Unknown entity An entity that has not been identified.  

InterestLevel

code title description technical note
direct Direct The interest is held directly.  
indirect Indirect The interest is held through one or more intermediate entities (including arrangements).  
unknown Unknown The interest may be direct or indirect.  

InterestType

code title description technical note
shareholding Shareholding    
voting-rights Voting rights    
appointment-of-board Appointment of board    
influence-or-control Influence or control    
senior-managing-official Senior managing official    
settlor-of-trust Settlor of trust    
trustee-of-trust Trustee of a trust.    
protector-of-trust Protector of a trust    
beneficiary-of-trust Beneficiary of a trust    
other-influence-or-control-of-trust Other influence or control of a trust    
rights-to-surplus-assets Rights to surplus assets    
rights-to-profit-or-income Rights to receive profits or income    

NameType

code title description technical note
individual Given name    
translation Translation of name    
former Former name    
alias Alias    
aka Also Known As    
nick Nickname    
birth Birth name    

PersonType

code title description technical note
knownPerson Known person This person has been identified, and information such as names, identifiers or biographical information may be provided about them.  
anonymousPerson Anonymous person This person has been identified, but identifying information is being withheld. The reason for non disclosure should be given in the accompanying missingInfoReason field.  
unknownPerson Unknown person The identity of this person has not been discovered or confirmed.  

SourceType

code title description technical note
selfDeclaration Self declaration The information was provided by the individual or entity referred to in this statement, or by their authorised representative.  
officialRegister Official register The information was taken from an official register.  
thirdParty Third party The information was provided by a third party, not directly related to the individual, entity or interests described by this statement.  
primaryResearch Primary research The information was provided as a result of research into primary sources.  
verified Verified The information has been verified through the process documented in the associated description.  

StatementType

code title description technical note
personStatement Person Statement   The parent object should be validated using the person-statement schema.
entityStatement Entity Statement   The parent object should be validated using the entity-statement schema
ownershipOrControlStatement Ownership or Control Statement   The parent object should be validated using the ownership-or-control-statement schema.

UnspecifiedReason

code title description technical note
no-beneficial-owners No beneficial owners There are no beneficial owners who need to disclose ownership according to the rules under which this statement is made.  
subject-unable-to-confirm-or-identify-beneficial-owner Subject unable to confirm or identify beneficial owner The subject of this ownership or control statement has, as the disclosing party, been unwilling or unable to confirm the existence identify a beneficial owner.  
interested-party-has-not-provided-information Interested party has not provided information The interested party in this ownership or control statement has not provided enough information to identify or confirm the identity of the beneficial owner.  
subject-exempt-from-disclosure Subject exempt from disclosure The subject of this ownership or control statement is not required to disclose its beneficial owner. (Replaces noNotifiableOwners.)  
interested-party-exempt-from-disclosure Interested party exempt from disclosure The interested party in this ownership or control statement is exempt from having their identity disclosed.  
unknown Unknown reason The reason an interested party cannot be provided is not known.