Merge pull request #438 from open-contracting/335_benefits

project-schema.json: add benefits array

docs/_static/i18n.csv

@@ -520,3 +520,29 @@ environment/abatementCost,Abatement cost,False,
 environment/abatementCost,Value,False,
 environment/abatementCost/amount,Amount,False,
 environment/abatementCost/currency,Currency,False,
+benefits,Benefits,False,
+benefits,Benefit,False,
+benefits/title,Title,True,
+benefits/description,Description,True,
+benefits/beneficiaries,Beneficiaries,False,
+benefits/beneficiaries,Beneficiary,False,
+benefits/beneficiaries/location,Location,False,
+benefits/beneficiaries/location,Delivery Location,False,
+benefits/beneficiaries/location/id,Identifier,True,
+benefits/beneficiaries/location/description,Description,True,
+benefits/beneficiaries/location/geometry,Geometry,False,
+benefits/beneficiaries/location/geometry/type,Type,False,
+benefits/beneficiaries/location/geometry/coordinates,Coordinates,False,
+benefits/beneficiaries/location/gazetteer,Gazetteer,False,
+benefits/beneficiaries/location/gazetteer/scheme,Gazetteer scheme,False,
+benefits/beneficiaries/location/gazetteer/identifiers,Identifiers,False,
+benefits/beneficiaries/location/uri,URI,True,
+benefits/beneficiaries/location/address,Address,False,
+benefits/beneficiaries/location/address,Address,False,
+benefits/beneficiaries/location/address/streetAddress,Street address,True,
+benefits/beneficiaries/location/address/locality,Locality,True,
+benefits/beneficiaries/location/address/region,Region,True,
+benefits/beneficiaries/location/address/postalCode,Postal code,True,
+benefits/beneficiaries/location/address/countryName,Country name,True,
+benefits/beneficiaries/description,Description,True,
+benefits/beneficiaries/numberOfPeople,Number of people,False,

docs/cost/ids/sustainability.md

@@ -1032,7 +1032,7 @@ Indirect\]
 :columns: 8
 OC4IDS mapping
 ^^^
-
+See [number of beneficiaries (social module)](social-number-of-beneficiaries)
 ````
 
 `````
@@ -1435,12 +1435,11 @@ gender empowerment
 :columns: 8
 OC4IDS mapping
 ^^^
-Project level: For each impact identified add a `benefit` object to the `benefits` array and assign it a locally unique `id`. Set the `title` as the list code and add details explaining the benefit to `.description`.
+Project level: For each co-benefit, add a `Benefit` object to the `benefits` array, map the option from the list to its `.title` and map the explanation to its `.description`.
 ```json
 {
   "benefits": [
     {
-      "id": "1",
       "title": "environmental",
       "description": "The new water management plant will mean less water is removed from the delta meaning more is left in place for use by the local biome."
     }
@@ -2065,7 +2064,29 @@ Indicate the number of direct and indirect project beneficiaries (E.g. direct: \
 :columns: 8
 OC4IDS mapping
 ^^^
+Project level:
 
+1. Add a `Benefit` object to the `benefits` array.
+2. Add a `Beneficiary` object to the benefit's `.beneficiaries` array, set its `.description` to "Direct beneficiaries" and set its `.numberOfPeople` to the number of direct beneficiaries.
+3. Add a `Beneficiary` object to the benefit's `.beneficiaries` array, set its `.description` to "Indirect beneficiaries" and set its `.numberOfPeople` to the number of indirect beneficiaries.
+```json
+{
+  "benefits": [
+    {
+      "beneficiaries": [
+        {
+          "description": "Direct beneficiaries",
+          "numberOfPeople": 1000
+        },
+        {
+          "description": "Indirect beneficiaries",
+          "numberOfPeople": 2000
+        }
+      ]
+    }
+  ]
+}
+```
 ````
 
 `````

docs/examples/blank.json

@@ -573,5 +573,18 @@
       "amount": "number",
       "currency": "string from currency codelist"
     }
-  }
+  },
+  "benefits": [
+    {
+      "title": "string",
+      "description": "string",
+      "beneficiaries": [
+        {
+          "description": "string",
+          "location": {},
+          "numberOfPeople": "integer"
+        }
+      ]
+    }
+  ]
 }

docs/examples/example.json

@@ -1105,7 +1105,25 @@
           "amount": 12.29,
           "currency": "USD"
         }
-      }
+      },
+      "benefits": [
+        {
+          "title": "Environmental",
+          "description": "The new water management plant will mean less water is removed from the delta meaning more is left in place for use by the local biome.",
+          "beneficiaries": [
+            {
+              "description": "Local population of water plant.",
+              "numberOfPeople": 1000,
+              "location": {
+                "id": "1",
+                "address": {
+                  "countryName": "United Kingdom"
+                }
+              }
+            }
+          ]
+        }
+      ]
     }
   ]
 }

docs/reference/changelog.md

@@ -28,9 +28,10 @@
   * [#427](https://github.com/open-contracting/infrastructure/pull/427) - `parties.beneficialOwners`
   * [#426](https://github.com/open-contracting/infrastructure/pull/426) - `transactions`
   * [#426](https://github.com/open-contracting/infrastructure/pull/426) - `milestones`
+  * [#438](https://github.com/open-contracting/infrastructure/pull/438) - `benefits`
   * [#379](https://github.com/open-contracting/infrastructure/pull/379) - `contractingProcesses.summary.tender.datePublished`
   * [#426](https://github.com/open-contracting/infrastructure/pull/426) - `contractingProcesses.summary.milestones`
-  * [#433](https://github.com/open-contracting/infrastructure/pull/433) - `contractingProcesses.summary.social`.
+  * [#433](https://github.com/open-contracting/infrastructure/pull/433) - `contractingProcesses.summary.social`
   * [#432](https://github.com/open-contracting/infrastructure/pull/432):
     * `identificationPeriod`
     * `preparationPeriod`

docs/reference/schema.md

@@ -365,6 +365,7 @@ Each `Classification` has the following fields:
 
 This sub-schema is referenced by the following properties:
 * [`locations`](project-schema.json,,locations)
+* [`Beneficiary/location`](project-schema.json,/definitions/Beneficiary,location)
 
 Each `Location` has the following fields:
 
@@ -387,6 +388,11 @@ Each `Location` has the following fields:
 :title: locations
 ```
 
+```{jsoninclude} ../../docs/examples/example.json
+:jsonpointer: /projects/0/benefits/0/beneficiaries/0/location
+:title: benefits/0/beneficiaries/0/location
+```
+
 ````
 
 `````
@@ -679,6 +685,11 @@ Each `Address` has the following fields:
 :title: social/consultationMeetings/0/address
 ```
 
+```{jsoninclude} ../../docs/examples/example.json
+:jsonpointer: /projects/0/benefits/0/beneficiaries/0/location/address
+:title: benefits/0/beneficiaries/0/location/address
+```
+
 ````
 
 `````
@@ -1157,6 +1168,77 @@ Each `MilestoneReference` has the following fields:
 
 `````
 
+### Benefit
+
+`Benefit` is defined as:
+
+```{field-description} ../../build/current_lang/project-schema.json /definitions/Benefit
+```
+
+This sub-schema is referenced by the following properties:
+* [`benefits`](project-schema.json,,benefits)
+
+Each `Benefit` has the following fields:
+
+
+`````{tab-set}
+
+````{tab-item} Schema
+
+```{jsonschema} ../../build/current_lang/project-schema.json
+:pointer: /definitions/Benefit
+:collapse: title,description,beneficiaries
+:addtargets:
+```
+
+````
+
+````{tab-item} Examples
+
+```{jsoninclude} ../../docs/examples/example.json
+:jsonpointer: /projects/0/benefits
+:title: benefits
+```
+
+````
+
+`````
+
+### Beneficiary
+
+`Beneficiary` is defined as:
+
+```{field-description} ../../build/current_lang/project-schema.json /definitions/Beneficiary
+```
+
+This sub-schema is referenced by the following properties:
+* [`Benefit/beneficiaries`](project-schema.json,/definitions/Benefit,beneficiaries)
+
+Each `Beneficiary` has the following fields:
+
+`````{tab-set}
+
+````{tab-item} Schema
+
+```{jsonschema} ../../build/current_lang/project-schema.json
+:pointer: /definitions/Beneficiary
+:collapse: location,description,numberOfPeople
+:addtargets:
+```
+
+````
+
+````{tab-item} Examples
+
+```{jsoninclude} ../../docs/examples/example.json
+:jsonpointer: /projects/0/benefits/0/beneficiaries
+:title: benefits/0/beneficiaries
+```
+
+````
+
+`````
+
 ### LaborObligations
 
 `LaborObligations` is defined as:

mapping/sustainability.yaml

@@ -598,7 +598,7 @@
         Disclose who is the climate finance investment intended to benefit \[free text to explain the beneficiaries\] and number of beneficiaries. \[Select from the list:
         Direct
         Indirect\]
-    mapping: ''
+    mapping: See [number of beneficiaries (social module)](social-number-of-beneficiaries)
     example: ''
 -   id: '3.8'
     title: Amount of investment
@@ -841,12 +841,11 @@
         environmental
         gender empowerment
         \[add free text to explain the co-benefits\]
-    mapping: 'Project level: For each impact identified add a `benefit` object to the `benefits` array and assign it a locally unique `id`. Set the `title` as the list code and add details explaining the benefit to `.description`.'
+    mapping: 'Project level: For each co-benefit, add a `Benefit` object to the `benefits` array, map the option from the list to its `.title` and map the explanation to its `.description`.'
     example: |-
         {
           "benefits": [
             {
-              "id": "1",
               "title": "environmental",
               "description": "The new water management plant will mean less water is removed from the delta meaning more is left in place for use by the local biome."
             }
@@ -1229,8 +1228,29 @@
     module: Social
     indicator: Beneficiary population
     disclosure format: 'Indicate the number of direct and indirect project beneficiaries (E.g. direct: \[number\]; indirect: "number"). Beneficiaries are the individuals who benefit directly or indirectly from the project; they are the target group of the infrastructure project and their needs are addressed by the intervention.'
-    mapping: ''
-    example: ''
+    mapping: |-
+        Project level:
+
+        1. Add a `Benefit` object to the `benefits` array.
+        2. Add a `Beneficiary` object to the benefit's `.beneficiaries` array, set its `.description` to "Direct beneficiaries" and set its `.numberOfPeople` to the number of direct beneficiaries.
+        3. Add a `Beneficiary` object to the benefit's `.beneficiaries` array, set its `.description` to "Indirect beneficiaries" and set its `.numberOfPeople` to the number of indirect beneficiaries.
+    example: |-
+        {
+          "benefits": [
+            {
+              "beneficiaries": [
+                {
+                  "description": "Direct beneficiaries",
+                  "numberOfPeople": 1000
+                },
+                {
+                  "description": "Indirect beneficiaries",
+                  "numberOfPeople": 2000
+                }
+              ]
+            }
+          ]
+        }
 -   id: '4.2'
     title: Inclusive design and implementation
     module: Social

schema/project-level/project-schema.json

@@ -390,6 +390,16 @@
         }
       },
       "minProperties": 1
+    },
+    "benefits": {
+      "title": "Benefits",
+      "description": "The benefits and intended benefits of the project.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Benefit"
+      },
+      "uniqueItems": true,
+      "minItems": 1
     }
   },
   "definitions": {
@@ -2463,6 +2473,57 @@
       },
       "minProperties": 1
     },
+    "Benefit": {
+      "title": "Benefit",
+      "description": "A benefit or intended benefit of the project.",
+      "type": "object",
+      "properties": {
+        "title": {
+          "title": "Title",
+          "description": "A title for the benefit.",
+          "type": "string"
+        },
+        "description": {
+          "title": "Description",
+          "description": "A short description of the benefit.",
+          "type": "string"
+        },
+        "beneficiaries": {
+          "title": "Beneficiaries",
+          "description": "Whom the benefit will aid.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Beneficiary"
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        }
+      },
+      "minProperties": 1
+    },
+    "Beneficiary": {
+      "title": "Beneficiary",
+      "description": "Information about a beneficiary of the project.",
+      "type": "object",
+      "properties": {
+        "location": {
+          "title": "Location",
+          "description": "The location of the beneficiary.",
+          "$ref": "#/definitions/Location"
+        },
+        "description": {
+          "title": "Description",
+          "description": "A short description of the beneficiary.",
+          "type": "string"
+        },
+        "numberOfPeople": {
+          "title": "Number of people",
+          "description": "The total size of the beneficiary population.",
+          "type": "integer"
+        }
+      },
+      "minProperties": 1
+    },
     "Sustainability": {
       "title": "Sustainability",
       "description": "Information about how the contracting process incorporates sustainable public procurement.",