Describe how to disclose structured data about beneficiaries

[duncandewhurst]

CoST Honduras collect structured data on the beneficiaries of PPP projects in SISOCS APP and they want to include this in their OCDS for PPPs data.

The closest element in OCDS for PPPs is I.4 Project economic and social benefits, defined in the World Bank framework as:

Project need: benefits provided, economic and social (including specific information on the public interest aspect)

However, OCDS for PPPs provides only for this information to be published as a document, rather than as structured data.

Example

The following example is machine translated (original version in Spanish):

Department	Municipality	Benefit
Comayagua	Comayagua	One of the fundamental objectives of this project is to promote the development of the country by building an alternative route to the current one between the departments of Comayagua - La Paz and Valle - Choluteca, with which the traffic from Choluteca and Valle is directed to the Comayagua area and to the North, would not necessarily have to go through Tegucigalpa...
Francisco Morazán	Tegucigalpa	One of the fundamental objectives of this project is to promote the development of the country by building an alternative route to the current one between the departments of Comayagua - La Paz and Valle - Choluteca, with which the traffic from Choluteca and Valle is directed to the Comayagua area and the North, would not necessarily have to go through Tegucigalpa...

Note that departments are administrative divisions of Honduras and the benefit column is truncated for brevity.

Other standards

I couldn't find any relevant models in linked open vocabularies.

360Giving uses beneficaryLocation, which differs from the OCDS location model, to describe the location of the beneficiaries of grants.

IATI uses results, which are closer in nature to the OCDS metrics extension, to describe the benefits or intended benefits of an activity.

Modelling options

I need to confirm what stage of the contracting process this information is from, but I think it's likely to be from the planning stage, so the following options could be properties of the planning object:

1. Local extension

The simplest option is to model the beneficiaries table as an array of objects with property names from the SISOCS data, however this does not serve the purpose of standardization:

{
  "beneficiaries": [
    {
      "id": "",
      "department": "",
      "municipality": "",
      "benefit": ""
    }
  ]
}

2. Generic model

Map benefit to 'description' and reuse the OCDS location extension to describe the location of the beneficiary:

{
  "beneficiaries": [
    {
      "id": "",
      "description": "",
      "location": {},
    }
  ]
}

3. Benefits array

It seems more semantically correct to model beneficiaries as a property of benefits and, in fact, this is reflected in the example shared by CoST Honduras, where the same text appears in the benefit column for all beneficiaries.

Map benefit to benefits/description and reuse the location extension to describe the location of the beneficiary:

{
  "benefits": [
    {
      "id": "",
      "description": "",
      "beneficiaries": [
        {
          "id": "",
          "location": {}
        }
      ]
    }
  ]
}

Other options

I considered listing beneficiaries in parties section and referencing them from a beneficiaries array, but I don't think that beneficiaries can be considered parties to the contracting process.

Discussion

I perfer option 3 for semantic accuracy and ease of reuse by other publishers who might structure their data differently.

@jpmckinney - what do you think?

cc @EvelynDinora

[jpmckinney]

Yes to 3, but why is location an array?

[duncandewhurst]

Yes to 3, but why is location an array?

I was misremembering the structure of the location extension, I've updated the issue description.

[jpmckinney]

Looks good!

[duncandewhurst]

I need to confirm what stage of the contracting process this information is from, but I think it's likely to be from the planning stage, so the following options could be properties of the planning object:

CoST Honduras confirmed the information is known at the planning stage.

[duncandewhurst]

Looking at Honduras' draft data, I think we need to add an address property to beneficiaries to structure the department and municipality of the beneficiaries. For example:

  "benefits": [
    {
      "id": "",
      "description": "Uno de los objetivos fundamentales de este proyecto...",
      "beneficiaries": [
        {
          "id": "10301",
          "address": {
            "region": "Francisco Morazán",
            "locality": "Tegucigalpa"
          }
        }

Alternatively, we could stick with using just location and either:

1. Concatenate department and municipality into location/description, e.g.

"location": {
  "description": "Tegucigalpa, Francisco Morazán"

2. Map department and municipality to a gazetteer, e.g.

"location": {
  "gazetteer": {
    "scheme": "GEONAMES",
    "identifiers": "3600949"

However, option 1 makes it harder for users to filter on departments/regions. Similarly, option 2 requires users to look up the identifier against an external list to get the name and also won't work if department and municipality are free-text fields.

So, practically, I think using address is a better option for Honduras. If we document a beneficiaries extension then we can still include location for publishers who have geometry or gazetteer data.

@jpmckinney what do you think?

[jpmckinney]

Sounds good to me. The location extension similarly has delivery address and location as sibling fields on the item object.

[yolile]

Note that a similar extension was drafted here for OCDS open-contracting/standard#1388 (comment)