Merge pull request #689 from openownership/schema-reference-edits

Schema reference edits

docs/standard/schema-browser.rst

@@ -7,13 +7,14 @@ Schema browser
 
 The draft Beneficial Ownership Data Standard schema is defined using `JSON Schema 2020-12 <https://json-schema.org/>`_.
 
-Within each BODS statement are ``recordDetails`` for one of three elements: an entity, a person, or a relationship. The structure of each of the related top level objects in the schema can be explored using the viewers below. (Click on object buttons to reveal their properties.)
+A BODS dataset is an array of Statements. Each Statement contains ``recordDetails`` for one of three beneficial ownership elements. The structure of these objects can be explored using the viewers below. (Click on object buttons to reveal their properties.)
 
 * :ref:`schema-browser-statement`
 * :ref:`schema-browser-entity`
 * :ref:`schema-browser-person`
 * :ref:`schema-browser-relationship`
 
+For an A - Z guide to the the Data Standard's schema objects and codelists, see the :ref:`schema-reference`.
 
 .. _schema-browser-statement:
 
@@ -28,8 +29,8 @@ View the `Statements JSON schema <../_static/statement.json>`_ or explore it usi
 
 .. _schema-browser-entity:
 
-Entity record details
----------------------
+Record details (entity)
+------------------------
 
 View the `Entity record details JSON schema <../_static/entity-record.json>`_ or explore it using the viewer below.
 
@@ -40,8 +41,8 @@ View the `Entity record details JSON schema <../_static/entity-record.json>`_ or
 
 .. _schema-browser-person:
 
-Person record details
----------------------
+Record details (person)
+------------------------
 
 View the `Person record details JSON schema <../_static/person-statement.json>`_ or explore it using the viewer below.
 
@@ -51,8 +52,8 @@ View the `Person record details JSON schema <../_static/person-statement.json>`_
 
 .. _schema-browser-relationship:
 
-Relationship record details
----------------------------
+Record details (relationship)
+------------------------------
 
 View the `Relationship record details JSON schema <../_static/relationship-record.json>`_ or explore it using the viewer below.
 

docs/standard/system/serialisation.rst

@@ -1,4 +1,4 @@
-.. _guidance-serialization:
+.. _guidance-serialisation:
 
 Serialisation
 =============
@@ -19,7 +19,6 @@ A JSON BODS file MUST consist of a series of ordered Statement objects within a
 
 Specifically, the ``interestedParty`` and ``subject`` values of a Relationship statement, when they are a ``recordId`` value, MUST match the ``recordId`` value of at least one other *prior* Statement in the array.
 
-
 Alternative tabular form
 ------------------------
 

requirements.txt

@@ -96,7 +96,7 @@ sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-opendataservices==0.5.0
     # via -r requirements.in
-sphinxcontrib-opendataservices-jsonschema==0.6.1
+sphinxcontrib-opendataservices-jsonschema==0.7.0
     # via
     #   -r requirements.in
     #   sphinxcontrib-opendataservices

requirements_test.txt

@@ -174,7 +174,7 @@ sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-opendataservices==0.5.0
     # via -r requirements.in
-sphinxcontrib-opendataservices-jsonschema==0.6.1
+sphinxcontrib-opendataservices-jsonschema==0.7.0
     # via
     #   -r requirements.in
     #   sphinxcontrib-opendataservices

schema/codelists/addressType.csv

@@ -1,7 +1,7 @@
-code,title,description,technical note
-placeOfBirth,Place of birth,"The place where a person was born. A town (in the `address` field) and `country` may be sufficient information. This MUST only apply to the `placeOfBirth` field for natural persons.",
-residence,Residential address,"An address where someone lives. This MUST only apply to natural persons.",
-registered,Registered address,"An official address for delivering statutory mail and legal notices which must be provided to company registers. This MUST only apply to entities.",
-service,Service address,"An address which can be used as an alternative to a residential address for the purpose of receiving post. This MUST only apply to natural persons.",
-alternative,Alternative address,"An address provided in addition to the primary address for this entity or person that is neither a service nor a registered address.",
-business,Business address,"A place where the entity conducts its business.",
+code,title,description
+placeOfBirth,Place of birth,The place where a person was born. A town (in the `address` field) and `country` may be sufficient information. This MUST only apply to the `placeOfBirth` field for natural persons.
+residence,Residential address,An address where someone lives. This MUST only apply to natural persons.
+registered,Registered address,An official address for delivering statutory mail and legal notices which must be provided to company registers. This MUST only apply to entities.
+service,Service address,An address which can be used as an alternative to a residential address for the purpose of receiving post. This MUST only apply to natural persons.
+alternative,Alternative address,An address provided in addition to the primary address for this entity or person that is neither a service nor a registered address.
+business,Business address,A place where the entity conducts its business.

schema/codelists/annotationMotivation.csv

@@ -1,6 +1,6 @@
-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 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 explains how linked material relates to the field, object or statement. A URL to linked material MUST 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.",
+code,title,description
+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 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 explains how linked material relates to the field, object or statement. A URL to linked material MUST 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."

schema/codelists/directOrIndirect.csv

@@ -1,4 +1,4 @@
-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.",
+code,title,description
+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.

schema/codelists/entitySubtype.csv

@@ -1,6 +1,6 @@
-code,title,description,technical note
-governmentDepartment,Government department,"An element of government with executive responsibilities. These terms are often used to designate such a body: ministry, department, bureau or office. This MUST be used with `entityType.type` 'stateBody'.",
-stateAgency,State Agency,"A body overseeing or administering elements of public policy. State agencies may have responsibilities which are devolved from government departments or from the state's legislative body. This MUST be used with `entityType.type` 'stateBody.",
-other,Other,"Any other type of entity.",
-trust,Trust,"A trust or trust like arrangement. An arrangement where a settlor transfers ownership of assets to trustees to control for the benefit of beneficiaries. This MUST be used with `entityType.type` 'arrangement' or 'legalEntity'.",
-nomination,Nomination,"An agreement where a nominator instructs a nominee to act on their behalf in a specified capacity. This MUST be used with `entityType.type` 'arrangement'.",
+code,title,description
+governmentDepartment,Government department,"An element of government with executive responsibilities. These terms are often used to designate such a body: ministry, department, bureau or office. This MUST be used with `entityType.type` 'stateBody'."
+stateAgency,State Agency,A body overseeing or administering elements of public policy. State agencies may have responsibilities which are devolved from government departments or from the state's legislative body. This MUST be used with `entityType.type` 'stateBody.
+other,Other,Any other type of entity.
+trust,Trust,A trust or trust like arrangement. An arrangement where a settlor transfers ownership of assets to trustees to control for the benefit of beneficiaries. This MUST be used with `entityType.type` 'arrangement' or 'legalEntity'.
+nomination,Nomination,An agreement where a nominator instructs a nominee to act on their behalf in a specified capacity. This MUST be used with `entityType.type` 'arrangement'.

schema/codelists/entityType.csv

@@ -1,8 +1,8 @@
-code,title,description,technical note
-registeredEntity,Registered Entity,"A legal entity created through an act of official registration. In most cases, registered entities have an officially issued identifier.",
-legalEntity,Legal entity,"A body with distinct legal personality, such as an international institution or statutory corporation, but which is not otherwise uniquely identified in some official register.",
-arrangement,Arrangement,"A legal arrangement, agreement, contract or other mechanism via which one or more natural or legal persons can associate to exert ownership or control over an entity. Parties to an arrangement have no other form of collective legal identity.",
-anonymousEntity,Anonymous entity,"An entity that has been identified, but for which identifying information is being withheld. The reason for non-disclosure should be given in the accompanying `unspecifiedEntityDetails` field.",
-unknownEntity,Unknown entity,"An entity that has not been identified.",
-state,State,"A country, nation or community with legal sovereignty within a territory.",
-stateBody,State body,"A core administrative or legislative unit within a state's apparatus.",
+code,title,description
+registeredEntity,Registered Entity,"A legal entity created through an act of official registration. In most cases, registered entities have an officially issued identifier."
+legalEntity,Legal entity,"A body with distinct legal personality, such as an international institution or statutory corporation, but which is not otherwise uniquely identified in some official register."
+arrangement,Arrangement,"A legal arrangement, agreement, contract or other mechanism via which one or more natural or legal persons can associate to exert ownership or control over an entity. Parties to an arrangement have no other form of collective legal identity."
+anonymousEntity,Anonymous entity,"An entity that has been identified, but for which identifying information is being withheld. The reason for non-disclosure should be given in the accompanying `unspecifiedEntityDetails` field."
+unknownEntity,Unknown entity,An entity that has not been identified.
+state,State,"A country, nation or community with legal sovereignty within a territory."
+stateBody,State body,A core administrative or legislative unit within a state's apparatus.

schema/codelists/interestType.csv

@@ -1,24 +1,24 @@
-code,title,description,technical note
-shareholding,Shareholding,An economic interest in an entity gained by holding shares.,
-votingRights,Voting rights,"A controlling interest in an entity gained by holding shares. Defined as the right of shareholders to vote on matters of corporate policy, including decisions on the makeup of the board of directors, issuing securities, initiating corporate actions and making substantial changes in the corporation's operations.",
-appointmentOfBoard,Appointment of board,A controlling interest in an entity. Defined as the absolute right to appoint members of the board of directors.,
-otherInfluenceOrControl,Other influence or control,"Any influence or control in an entity that is distinct from being a shareholder, having voting rights or having the absolute right to appoint to the board.",
-seniorManagingOfficial,Senior managing official,A controlling interest in an entity gained by employment. Defined as the person who exercises control over the management of the entity.,
-settlor,Settlor,"A person who, either actually or by operation of law, creates a trust. They may be referred to by other names such as a trustor, a grantor or a donor. This should also be used for a person with a settlor-equivalent role in any legal arrangement that is similar to a trust.",
-trustee,Trustee,A person who administers a trust for the benefit of a third party and in whom the legal title of the trust property is vested either by declaration of the settlor or by operation of law. This should also be used for a person with a trustee-equivalent role in any legal arrangement that is similar to a trust.,
-protector,Protector,"A person appointed to protect the interests or wishes of the settlor, providing influence and guidance to the trustee who administers the trust. This should also be used for a person with a protector-equivalent role in any legal arrangement that is similar to a trust.",
-beneficiaryOfLegalArrangement,Beneficiary of a legal arrangement,A person who benefits from a trust or other legal arrangement's holdings or activities.,
-rightsToSurplusAssetsOnDissolution,Rights to surplus assets on dissolution,The right to a share in the amount of an asset or resource that exceeds the portion that is utilized upon the winding up of an entity.,
-rightsToProfitOrIncome,Rights to receive profits or income,An economic interest in an entity. Defined as beneficial ownership rights beyond those otherwise implied by ownership structures that are granted by contract.,
-rightsGrantedByContract,Rights granted by contract,An interest that is granted by contract.,
-conditionalRightsGrantedByContract,Conditional rights granted by contract,An interest that exists only if some contractual condition is met.,
-controlViaCompanyRulesOrArticles,Control via company rules or articles,Control of an entity gained through a provision in company articles or by shareholder agreement.,
-controlByLegalFramework,Control by legal framework,"Control of an entity gained through a legal framework, such as a combination of legislation (primary and secondary). This type of interest is created by governments and legislators in order to establish and guide agencies and entities linked to the state.",
-boardMember,Board member,One of a group of people constituted as the strategic decision-making body of an organization.,
-boardChair,Board chair,The person holding the most power and authority on the board of directors.,
-unknownInterest,Unknown interest,"The interestedParty is known to have an interest in the subject of this Relationship Statement, but the nature of the interest is unknown.",
-unpublishedInterest,Unpublished interest,The nature of this interest is known but is not published.,
-enjoymentAndUseOfAssets,Enjoyment and use of assets,The use of assets belonging to an entity.,
-rightToProfitOrIncomeFromAssets,Right to profit or income from assets,"The right to derive profits, income or both from assets belonging to an entity.",
-nominee,Nominee,A person who agrees to act on behalf of the nominator in a specified capacity.,
-nominator,Nominator,A person who instructs a nominee to act on their behalf in a specified capacity.,
+code,title,description
+shareholding,Shareholding,An economic interest in an entity gained by holding shares.
+votingRights,Voting rights,"A controlling interest in an entity gained by holding shares. Defined as the right of shareholders to vote on matters of corporate policy, including decisions on the makeup of the board of directors, issuing securities, initiating corporate actions and making substantial changes in the corporation's operations."
+appointmentOfBoard,Appointment of board,A controlling interest in an entity. Defined as the absolute right to appoint members of the board of directors.
+otherInfluenceOrControl,Other influence or control,"Any influence or control in an entity that is distinct from being a shareholder, having voting rights or having the absolute right to appoint to the board."
+seniorManagingOfficial,Senior managing official,A controlling interest in an entity gained by employment. Defined as the person who exercises control over the management of the entity.
+settlor,Settlor,"A person who, either actually or by operation of law, creates a trust. They may be referred to by other names such as a trustor, a grantor or a donor. This should also be used for a person with a settlor-equivalent role in any legal arrangement that is similar to a trust."
+trustee,Trustee,A person who administers a trust for the benefit of a third party and in whom the legal title of the trust property is vested either by declaration of the settlor or by operation of law. This should also be used for a person with a trustee-equivalent role in any legal arrangement that is similar to a trust.
+protector,Protector,"A person appointed to protect the interests or wishes of the settlor, providing influence and guidance to the trustee who administers the trust. This should also be used for a person with a protector-equivalent role in any legal arrangement that is similar to a trust."
+beneficiaryOfLegalArrangement,Beneficiary of a legal arrangement,A person who benefits from a trust or other legal arrangement's holdings or activities.
+rightsToSurplusAssetsOnDissolution,Rights to surplus assets on dissolution,The right to a share in the amount of an asset or resource that exceeds the portion that is utilized upon the winding up of an entity.
+rightsToProfitOrIncome,Rights to receive profits or income,An economic interest in an entity. Defined as beneficial ownership rights beyond those otherwise implied by ownership structures that are granted by contract.
+rightsGrantedByContract,Rights granted by contract,An interest that is granted by contract.
+conditionalRightsGrantedByContract,Conditional rights granted by contract,An interest that exists only if some contractual condition is met.
+controlViaCompanyRulesOrArticles,Control via company rules or articles,Control of an entity gained through a provision in company articles or by shareholder agreement.
+controlByLegalFramework,Control by legal framework,"Control of an entity gained through a legal framework, such as a combination of legislation (primary and secondary). This type of interest is created by governments and legislators in order to establish and guide agencies and entities linked to the state."
+boardMember,Board member,One of a group of people constituted as the strategic decision-making body of an organization.
+boardChair,Board chair,The person holding the most power and authority on the board of directors.
+unknownInterest,Unknown interest,"The interestedParty is known to have an interest in the subject of this Relationship Statement, but the nature of the interest is unknown."
+unpublishedInterest,Unpublished interest,The nature of this interest is known but is not published.
+enjoymentAndUseOfAssets,Enjoyment and use of assets,The use of assets belonging to an entity.
+rightToProfitOrIncomeFromAssets,Right to profit or income from assets,"The right to derive profits, income or both from assets belonging to an entity."
+nominee,Nominee,A person who agrees to act on behalf of the nominator in a specified capacity.
+nominator,Nominator,A person who instructs a nominee to act on their behalf in a specified capacity.