Representing verification as data

[siwhitehouse]

Here's an example of a 'verified' statement about a natural person in BODS.

  {
    "statementID": "655a867e-6ecb-42a9-8e71-e7f1aa237c2f",
    "statementType": "personStatement",
    "statementDate": "2018-12-18",
    "entityType": "knownPerson",
    "names": [
      {
        "type": "individual",
        "fullName": "Ірина Яковенко"
      }
    ],
    "nationalities": [
      {
        "name": "Україна",
        "code": "UA"
      }
    ],
    "birthDate": "1965-11",
    "addresses": [
      {
        "type": "service",
        "address": "1 Шевченка, Киев",
        "postCode": "12345",
        "country": "UA"
      }
    ],
   "source": {
      "type": ["officialRegister", "verified"],
      "assertedBy": [
        {
          "name": "Ірина Яковенко"
        },
        {
          "name": "ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ ЯКОВЕНКО"
        }
      ]
    }
  }

We represent this statement as 'verified' simply by having verified in the sourceType array. An unverified version of the same statement would look identical except for the content of that array ("example":https://github.com/openownership/data-standard/blob/578278bab42828e4d1b70f78bb8cdc0e475fd2ce/examples/ua/sc-1-entity-natural-person-direct-domestic-bp.json#L27-L64).

The verified status is statement-level when statements are composed of different bits of information that may require their own verification checks. So, depending on the business processes in place, what is happening in real life may be much more complex than our verified flag allows. And the user needs for due diligence may not be met if we are not getting this right.

For example:

• only parts of the statement may be verified (e.g., name is checked against ID document, but address isn't);
• different parts of the statement are checked by different/multiple agents; the statement is rechecked on an annual basis;
• when checking a statement, the details of the asserting parties in the company and the registration agency are also recorded.

There are a couple of options that we might want to look at, after understanding the verification landscape a bit more:

• attaching a role to the agent object, to let us see who is doing what, why: BO providing details; company representative checking; third-party assurance; registration authority checker etc etc.
• allowing more flexible use of source objects. This could be be similar to annotations 'use any valid JSON path' or we could restrict to a set of relevant fields.

[siwhitehouse]

This has been transferred from the (internal) Open Data Services issue http://bods.opendataservices.coop/redmine/issues/389 that was raised by @ScatteredInk - it looks like it is related to #16 so may merit being merged with that issue.

[ScatteredInk]

Moving comment from @siwhitehouse over from another repo:

I raised this at a round table meeting at Transparency International.

We discussed the process of entering data on the Companies House register. As I understood it this can either be done by a 'subscriber', who is someone directly attached to the business or it can be done on their behalf by a 'producer'. This means that up to three agents are recorded as having updated a record:

The 'subscriber', who is the person directly attached the business (a beneficial owner, company secretary etc.) The 'producer', who is the person updating Companies House on their behalf The "producer software" which is the platform or application that is used by the 'producer' At the moment anyone can be a 'producer' - this is not limited by their location/nationality etc.. The example that was given was of someone in Moscow applying and being sent a 'producer' id/login. Turnaround by post being about one week. This may change and Richard is keen to see 'producers' becoming a regulated profession. This gives us some additional agent roles that we might want to be able to record.

There was a general response of "it's good to have fine-grained source data". From a regulatory/legal point of view this is required within banking (in general, not just wrt BODS). Companies House will have a record of who has updated specific data points within company records.

[kd-ods]

Noting for the record that Open Ownership's briefing on verification is here and will be useful when revisiting this issue in the schema.

[kd-ods]

ID info for agents is also something that we need to consider.

[kathryn-ods]

When unflattening test data for 0.4 this threw up an error as the source/type is an array of strings which I could represent in the sheet in a way that flatten tool would parse.

Is this the only case in bods we expect an array of strings? All other similar data seems to be an array of objects.

This allows for the combination of a source type and the verified tag under source/type. I think it would be more consistent to have a separate field for verification and source/type as a string.

Are the types - selfDeclaration, officialRegister, thirdParty and primaryResearch mutually exclusive? I think they are.

[kathryn-ods]

Just discussed with Emma and she pointed out some other fields formatted like this - replacesStatements, componentStatements, alternateNames. When unflattening the strings need to be separated by semi-colons. This isn't supported by flatten tool generally but works if a schema is passed in. https://flatten-tool.readthedocs.io/en/latest/unflatten/?highlight=semi%20colon#plain-lists-unsupported

[kathryn-ods]

Not sure where best to note this - in our mapping of GLEIF data to BODS data we are using the 'verified' tag when GLEIF data has Corroboration Level - FULLY_CORROBORATED. GLEIF also has a code - PARTIALLY_CORROBORATED. Our current system has no way to represent this level of detail.