Financing arrangements

docs/_static/i18n.csv

@@ -119,6 +119,47 @@ budget/budgetBreakdown/sourceParty,Organization reference,False,
 budget/budgetBreakdown/sourceParty/name,Organization name,True,
 budget/budgetBreakdown/sourceParty/id,Organization ID,True,
 budget/budgetBreakdown/approvalDate,Approval date,False,
+budget/finance,Finance,False,
+budget/finance,Financing arrangement,False,
+budget/finance/id,ID,True,
+budget/finance/title,Title,True,
+budget/finance/description,Description,True,
+budget/finance/value,Value,False,
+budget/finance/value,Value,False,
+budget/finance/value/amount,Amount,False,
+budget/finance/value/currency,Currency,False,
+budget/finance/financingParty,Financing organization,False,
+budget/finance/financingParty,Organization reference,False,
+budget/finance/financingParty/name,Organization name,True,
+budget/finance/financingParty/id,Organization ID,True,
+budget/finance/financingPartyType,Financing organization type,False,
+budget/finance/source,Funding source,True,
+budget/finance/assetClass,Asset class,False,
+budget/finance/type,Type,False,
+budget/finance/repaymentPriority,Repayment priority,False,
+budget/finance/concessional,Concessional,False,
+budget/finance/resultsBased,Results based,False,
+budget/finance/period,Finance period,False,
+budget/finance/period,Period,False,
+budget/finance/period/startDate,Start date,False,
+budget/finance/period/endDate,End date,False,
+budget/finance/period/maxExtentDate,Maximum extent,False,
+budget/finance/period/durationInDays,Duration (days),False,
+budget/finance/paymentPeriod,Payment period,False,
+budget/finance/paymentPeriod,Period,False,
+budget/finance/paymentPeriod/startDate,Start date,False,
+budget/finance/paymentPeriod/endDate,End date,False,
+budget/finance/paymentPeriod/maxExtentDate,Maximum extent,False,
+budget/finance/paymentPeriod/durationInDays,Duration (days),False,
+budget/finance/paymentFrequency,Payment frequency (days),False,
+budget/finance/interestRate,Interest rate,False,
+budget/finance/interestRate/base,Base,False,
+budget/finance/interestRate/margin,Margin,False,
+budget/finance/interestRate/fixed,Fixed rate,False,
+budget/finance/interestRate/notes,Notes,True,
+budget/finance/exchangeRateGuarantee,Exchange rate guarantees,False,
+budget/finance/stepInRights,Step in rights,False,
+budget/finance/relatedLots,Related lot(s),False,
 forecasts,Forecasts,False,
 forecasts,Metric,False,
 forecasts/id,Identifier,False,
@@ -365,6 +406,47 @@ contractingProcesses/summary/milestones/dueDate,Due date,False,
 contractingProcesses/summary/milestones/dateMet,Date met,False,
 contractingProcesses/summary/milestones/dateModified,Date modified,False,
 contractingProcesses/summary/milestones/status,Status,False,
+contractingProcesses/summary/finance,Finance,False,
+contractingProcesses/summary/finance,Financing arrangement,False,
+contractingProcesses/summary/finance/id,ID,True,
+contractingProcesses/summary/finance/title,Title,True,
+contractingProcesses/summary/finance/description,Description,True,
+contractingProcesses/summary/finance/value,Value,False,
+contractingProcesses/summary/finance/value,Value,False,
+contractingProcesses/summary/finance/value/amount,Amount,False,
+contractingProcesses/summary/finance/value/currency,Currency,False,
+contractingProcesses/summary/finance/financingParty,Financing organization,False,
+contractingProcesses/summary/finance/financingParty,Organization reference,False,
+contractingProcesses/summary/finance/financingParty/name,Organization name,True,
+contractingProcesses/summary/finance/financingParty/id,Organization ID,True,
+contractingProcesses/summary/finance/financingPartyType,Financing organization type,False,
+contractingProcesses/summary/finance/source,Funding source,True,
+contractingProcesses/summary/finance/assetClass,Asset class,False,
+contractingProcesses/summary/finance/type,Type,False,
+contractingProcesses/summary/finance/repaymentPriority,Repayment priority,False,
+contractingProcesses/summary/finance/concessional,Concessional,False,
+contractingProcesses/summary/finance/resultsBased,Results based,False,
+contractingProcesses/summary/finance/period,Finance period,False,
+contractingProcesses/summary/finance/period,Period,False,
+contractingProcesses/summary/finance/period/startDate,Start date,False,
+contractingProcesses/summary/finance/period/endDate,End date,False,
+contractingProcesses/summary/finance/period/maxExtentDate,Maximum extent,False,
+contractingProcesses/summary/finance/period/durationInDays,Duration (days),False,
+contractingProcesses/summary/finance/paymentPeriod,Payment period,False,
+contractingProcesses/summary/finance/paymentPeriod,Period,False,
+contractingProcesses/summary/finance/paymentPeriod/startDate,Start date,False,
+contractingProcesses/summary/finance/paymentPeriod/endDate,End date,False,
+contractingProcesses/summary/finance/paymentPeriod/maxExtentDate,Maximum extent,False,
+contractingProcesses/summary/finance/paymentPeriod/durationInDays,Duration (days),False,
+contractingProcesses/summary/finance/paymentFrequency,Payment frequency (days),False,
+contractingProcesses/summary/finance/interestRate,Interest rate,False,
+contractingProcesses/summary/finance/interestRate/base,Base,False,
+contractingProcesses/summary/finance/interestRate/margin,Margin,False,
+contractingProcesses/summary/finance/interestRate/fixed,Fixed rate,False,
+contractingProcesses/summary/finance/interestRate/notes,Notes,True,
+contractingProcesses/summary/finance/exchangeRateGuarantee,Exchange rate guarantees,False,
+contractingProcesses/summary/finance/stepInRights,Step in rights,False,
+contractingProcesses/summary/finance/relatedLots,Related lot(s),False,
 contractingProcesses/releases,Linked releases,False,
 contractingProcesses/releases,Release,False,
 contractingProcesses/releases/id,ID,True,

docs/cost/common.md

@@ -22,3 +22,8 @@ Add a `Document` object to the `contractingProcesses.summary.documents` array an
 
 * Add an `Organization` object to the `.parties` array and set its `.name` to the name of the organization.
 * If you collect organization identifiers, set `.identifier` according to the [identifier reference](../reference/schema.md#identifier) and set `.id` to {identifier.scheme}-{identifier.id}(-{department-identifier}). Otherwise, set `.id` incrementally.
+
+## Add a financing arrangement
+
+1. If the project is a public private partnership (PPP), get the `ContractingProcess` in `.contractingProcesses` that represents that contracting process for the PPP contract and add a `Finance` object to its `.summary.finance` array. Otherwise, add a `Finance` object to the `.budget.finance` array.
+2. Set the `Finance` object's `.id` incrementally.

docs/cost/ids/sustainability.md

@@ -873,14 +873,29 @@ guarantees
 :columns: 8
 OC4IDS mapping
 ^^^
-Project level: For each instrument, add a `finance` object to the `budget.finance` array. Set the `.id` appropriately. Set the `.financeCategory` to the matching code from the financeCategory codelist.
+1. Get the `Finance` object in `.budget.finance` or `.contractingProcesses.summary.finance` that represents the financing arrangement. If none exists yet, [add a financing arrangement](../common.md#add-a-financing-arrangement).
+2. Set the the financing arrangement's properties according to the instrument type:
+
+Instrument type | `.assetClass` | `.type`
+-- | -- | --
+loan | 'debt' | 'loan'
+grant | | 'grant'
+equity | 'equity' | 'shares.listed' or 'shares.unlisted'
+guarantee | | 'guarantee'
+
+3. If the instrument is a concessional loan, set `.concessional` to `true`.
+4. If the instrument is a non-concessional loan, set `.concessional` to `false`.
+5. If the instrument is results-based, set `.resultsBased` to `true`.
 ```json
 {
   "budget": {
     "finance": [
       {
         "id": "1",
-        "financeCategory": "seniorDebt",
+        "assetClass": [
+          "debt"
+        ],
+        "type": "loan",
         "concessional": false
       }
     ]
@@ -1065,15 +1080,16 @@ Disclose the quantum of the climate finance investment \[value, currency\].
 :columns: 8
 OC4IDS mapping
 ^^^
-Project level: For each financing instrument, add the value and currency to the`.value` in the `finance` object in `budget.finance`
+1. Get the `Finance` object in `.budget.finance` or `.contractingProcesses.summary.finance` that represents the financing arrangement. If none exists yet, [add a financing arrangement](../common.md#add-a-financing-arrangement).
+2. Map to the financing arrangement's `.value`.
 ```json
 {
   "budget": {
     "finance": [
       {
         "id": "1",
         "value": {
-          "amount": "3000000",
+          "amount": 3000000,
           "currency": "EUR"
         }
       }
@@ -1101,27 +1117,15 @@ Disclose who is providing the finance \[party/organization/role\]
 :columns: 8
 OC4IDS mapping
 ^^^
-Project level: Add the organization to the `parties` array and add 'funder' to their `.roles` array.
-Map the organization's `.id` from the party array to `financingParty.id` in the `budget.finance`
+1. Get the `Finance` object in `.budget.finance` or `.contractingProcesses.summary.finance` that represents the financing arrangement. If none exists yet, [add a financing arrangement](../common.md#add-a-financing-arrangement).
+2. Map to the financing arrangement's `.source`.
 ```json
 {
-  "parties": [
-    {
-      "id": "1",
-      "name": "African Development Bank",
-      "roles": [
-        "funder"
-      ]
-    }
-  ],
   "budget": {
     "finance": [
       {
         "id": "1",
-        "financingParty": {
-          "id": "1",
-          "name": "African Development Bank"
-        }
+        "source": "Green Climate Fund"
       }
     ]
   }
@@ -1147,17 +1151,28 @@ For projects financed by the Green Climate Fund, disclose the accredited entitie
 :columns: 8
 OC4IDS mapping
 ^^^
-Project level:
-
-Add each accredited entity organization to the `parties` array and add 'gcfAccreditedEntity' to its `.roles` array.
+1. Get the `Finance` object in `.budget.finance` or `.contractingProcesses.summary.finance` that represents the financing arrangement. If none exists yet, [add a financing arrangement](../common.md#add-a-financing-arrangement).
+2. Get the `Organization` object in `.parties` that represents the party providing the finance. If none exists yet, [add an organization](../common.md#add-an-organization) and add 'funder' to its `.roles`.
+3. Set the financing arrangement's `.financingParty` to the `.id` and `.name` of the organization.
 ```json
 {
+  "budget": {
+    "finance": [
+      {
+        "id": "1",
+        "financingParty": {
+          "id": "1",
+          "name": "Agency for Agricultural Development of Morocco"
+        }
+      }
+    ]
+  },
   "parties": [
     {
       "id": "1",
       "name": "Agency for Agricultural Development of Morocco",
       "roles": [
-        "gcfAccreditedEntity"
+        "funder"
       ]
     }
   ]
@@ -1314,48 +1329,24 @@ Private Finance \[value or NA\]
 :columns: 8
 OC4IDS mapping
 ^^^
-Project level:
-
-For each co-financing arrangement add a new `finance` object to the `budget.finance` array. Map the value and currency to the objects `.value`. Add the financing party to the parties array and add `funder` to their `roles` array. Map the funders `id` and `name` to the `.financingParty` object in the `finance` object.
+The OC4IDS data model provides the information needed to calculate co-finance ratios by modelling a project's individual financing arrangements. For more information, see the mappings for [amount of investment](climate-finance-amount-of-investment), [funding source](climate-finance-funding-source), [Green Climate Fund Accredited Entity](climate-finance-green-climate-fund-accredited-entity) and [Accredited Entity Type](climate-finance-accredited-entity-type).
 ```json
 {
-  "parties": [
-    {
-      "id": "1",
-      "name": "Green Climate Fund",
-      "roles": [
-        "funder"
-      ]
-    },
-    {
-      "id": "2",
-      "name": "Agency for Agricultural Development of Morocco",
-      "roles": [
-        "funder"
-      ]
-    }
-  ],
   "budget": {
     "finance": [
       {
         "id": "1",
-        "financingParty": {
-          "id": "1",
-          "name": "Green Climate Fund"
-        },
+        "source": "Green Climate Fund",
         "value": {
-          "amount": "3000000",
+          "amount": 3000000,
           "currency": "USD"
         }
       },
       {
         "id": "2",
-        "financingParty": {
-          "id": "2",
-          "name": "Agency for Agricultural Development of Morocco"
-        },
+        "source": "GEF Trust Fund",
         "value": {
-          "amount": "15000",
+          "amount": 150000,
           "currency": "USD"
         }
       }
@@ -1389,9 +1380,37 @@ Commitment fee (per annum)
 :columns: 8
 OC4IDS mapping
 ^^^
+1. Get the `Finance` object in `.budget.finance` or `.contractingProcesses.summary.finance` that represents the financing arrangement. If none exists yet, [add a financing arrangement](../common.md#add-a-financing-arrangement).
+2. Map the terms to the financing arrangement's properties:
 
+- Maturity: `.period`
+- Grace period: Map the period over which payments will be made to `.paymentPeriod`. The grace period is the difference between `.period` and `.paymentPeriod`.
+- Annual principal repayment years: `.description`
+- Interest: `.interestRate`
+- Service fee: `.description`
+- Commitment fee: `.description`
 ```json
-
+{
+  "budget": {
+    "finance": [
+      {
+        "id": "1",
+        "period": {
+          "startDate": "2024-01-01T00:00:00Z",
+          "endDate": "2043-12-31T00:00:00Z"
+        },
+        "paymentPeriod": {
+          "startDate": "2029-01-01T00:00:00Z",
+          "endDate": "2043-12-31T00:00:00Z"
+        },
+        "interestRate": {
+          "margin": 0.0075
+        },
+        "description": "Annual principal repayment years 11\u201320 (% of initial principal): 6.7%. Service fee (per annum): 0.50%. Commitment fee (per annum): Up to 0.75%."
+      }
+    ]
+  }
+}
 ```
 ````
 

docs/examples/blank.json

@@ -129,6 +129,35 @@
           "id": ""
         }
       }
+    ],
+    "finance": [
+      {
+        "id": "string",
+        "assetClass": "string from assetClass codelist",
+        "type": "string from financingArrangementType codelist",
+        "concessional": "boolean",
+        "value": {
+          "amount": "number",
+          "currency": "string"
+        },
+        "source": "string",
+        "financingParty": {
+          "id": "string",
+          "name": "string"
+        },
+        "period": {
+          "startDate": "string",
+          "endDate": "string"
+        },
+        "paymentPeriod": {
+          "startDate": "string",
+          "endDate": "string"
+        },
+        "interestRate": {
+          "margin": "number"
+        },
+        "description": "string"
+      }
     ]
   },
   "forecasts": [

docs/examples/example.json

@@ -188,6 +188,35 @@
               "id": "GB-GOR-XX1234"
             }
           }
+        ],
+        "finance": [
+          {
+            "id": "1",
+            "assetClass": "debt",
+            "type": "loan",
+            "concessional": true,
+            "value": {
+              "amount": 50000000,
+              "currency": "USD"
+            },
+            "source": "Green Climate Fund",
+            "financingParty": {
+              "id": "1",
+              "name": "United Nations Development Programme"
+            },
+            "period": {
+              "startDate": "2024-01-01T00:00:00Z",
+              "endDate": "2043-12-31T00:00:00Z"
+            },
+            "paymentPeriod": {
+              "startDate": "2029-01-01T00:00:00Z",
+              "endDate": "2043-12-31T00:00:00Z"
+            },
+            "interestRate": {
+              "margin": 0.0075
+            },
+            "description": "Annual principal repayment years 11–20 (% of initial principal): 6.7%. Service fee (per annum): 0.50%. Commitment fee (per annum): Up to 0.75%."
+          }
         ]
       },
       "parties": [
@@ -396,7 +425,10 @@
         {
           "id": "1",
           "name": "United Nations Development Programme",
-          "roles": "payer"
+          "roles": [
+            "payer",
+            "funder"
+          ]
         }
       ],
       "publicAuthority": {