Value: Exchange rate - Githubissues

timgdavies commented 8 years ago

This issue is under consideration for an extension in OCDS 1.1

It builds on discussions in #277

The issue

We have encountered a range of situations where publishers or data users may wish to provide/access multiple currency values. These include where:

Two currencies are reported for a given contract. For example, a document might give values in both USD and a local currency.
A contract agrees a fixed exchange rate for payments. For example, a contract is agreed in USD, but with a fixed exchange rate to convert this into MXN when payments are made. Sometimes the second value is declared. Sometimes only the rate is declared (as this will be the rate used
Values in the dataset are in multiple currencies, but users want to access the values in a single currency. For example, an application may want to sum up total contract values in USD, even if original contracts were in a range of other values.
The proposal

Creating an extension for value to provide optional properties for altAmount, altCurrency, exchangeRate, and exchangeRateDate.

amount should be the value in the currency in which the contract was signed
altAmount is the value in a secondary currency specified in altCurrency.
exchangeRate is the conversion between amount and altAmount on `exchangeRateDate.
When the extension is used, altCurrency must always be provided, and either altAmount or exchangeRate must be provided.

Worked example

"value": {
   "amount": 6563700,
   "currency":"MXN",
   "altAmount":429000,
   "altCurrency":"USD",
   "exchangeRate":0.065,
   "exchangeRateDate":"2015-11-04T00:00:00-05:00"
}

Engagement

Please indicate support or opposition for this proposal using the +1 / -1 buttons or a comment. If opposing the proposal, please give clear justifications, and where possible, make an alternative proposals.

davidmegginson commented 8 years ago

(deleted previous comment — posting too early in the day)

I think this makes sense, and we can look into something similar for IATI if the need arises.

patxiworks commented 7 years ago

The instability of exchange rates in some countries may increase the relevance of this. In Nigeria, we've been experiencing a constant fluctuation for the past year or so. Capturing the exchange rate adopted for a contract at the time of award could provide better (and historical) context – and prevent potential fraud through fiscal leakages.

I propose that this be included as a community extension.

timgdavies commented 7 years ago

Thanks @patxiworks - we will try and get this developed shortly.

timgdavies commented 7 years ago

I believe @juanpane has suggested a reworking of the model so that we collect exchange rate properties in their own object, such as below:

"value": {
   "amount": 6563700,
   "currency":"MXN",
   "exchangeRate": {
       "currency":"USD",
       "rate":0.065,
       "date":"2015-11-04T00:00:00-05:00"
   }
}

In this version I've dropped the suggestion of altAmount as this does not fit well under 'exchangeRate'.

I still prefer the flat modelling, as I think it copes better with the case where 'Two currencies are reported for a given contract' but without specifying the exchange rate.

Thoughts welcome.

siemvaessen commented 7 years ago

This has been adressed on IATI discuss as well. I am wondering what type of conversion rate needs to be used, market on non-market based.

timgdavies commented 7 years ago

I've been reviewing the valuable IATI discussion (and examples of real data) and thinking through two main use-cases:

(1) Asserting the exchange rate that was agreed at the time of a contract/aid project being signed off;

(2) Explaining any changes that an application has made in order to normalise currency values in it's dataset;

This leads me towards the following modelling:

"value": {
   "amount": 6563700,
   "currency":"MXN",
   "exchangeRates": [
       {
          "currency":"USD",
           "rate":0.065,
           "date":"2015-11-04T00:00:00-05:00",
           "source":"contract"
       }
   ]
}

where this adds:

exchangeRates is an array, allowing either specification of conversion rates to more than one currency, conversion rates at different points in time (for contracts that may agree a single multi-year contract value, but model a different change rate for each year), and different sources
source as a codelist-defined field which can indicate where this exchange rate is from. Possible values may be contract (the rate is agreed in the terms of the contract); market (the rate was taken from the market on the date given), application (the rate has been selected by the application producing/displaying this data)

This appears to cover most of the cases we might encounter with (1).

What it does not do is given the value in different currencies, which is what we see in the examples of real data in https://discuss.iatistandard.org/t/currency-conversion/413/11

We would then need guidance for an application on whether, if converting data to a common currency (e.g. converting data which is coming in using MXN, EUR and GBP into only USD for display in a front-end interface), it should:

(a) Update the currency and amount for each amount to USD and the converted value, and indicate the exchange rate that was used for this; or
(b) Put the normalised currency values in some additional field, such as amount_USD

(a) would go against the definition of amount as "the value in the currency in which the contract was signed", so my leaning is towards making (b) the guidance we give.

markbrough commented 7 years ago

I think this looks pretty good @timgdavies, I reckon the examples of real data from the IATI thread should be covered by this pretty well as I imagine the exact value amount will almost always be calculable through the exchange rate. Does it matter if it is very slightly off (through rounding errors)? Perhaps it does, so adding an additional amount field might also be helpful.

Is the plan also to be able to provide this at implementation/transactions? The rate agreed at the time of the contract will still change depending on market fluctuations and perhaps according to non-public sources, so would probably make sense to include it there as well?

timgdavies commented 7 years ago

Is the plan also to be able to provide this at implementation/transactions? The rate agreed at the time of the contract will still change depending on market fluctuations and perhaps according to non-public sources, so would probably make sense to include it there as well?

@markbrough Yes - this would be done as an extension to the value object, so would be available anywhere a financial value is given.

antonioherrera commented 6 years ago

Hello everyone!

We'll be using this extension and I'm wondering if you have already developed it. We are looking forward to see the complete extension (with the final descriptions and codelists).

timgdavies commented 6 years ago

This is not yet worked up into formal extension - but we can prioritise over the next two weeks.

timgdavies commented 6 years ago

The first draft of this extension is now staged at https://github.com/open-contracting/ocds_exchangeRate_extension

There is some more work to do testing and finalising this - but feedback on the docs and schema is welcome.

Tim0th1 commented 6 years ago

Looking at the issue, I think there are four questions that are relevant but not easy to combine to form for the extension:

What determines the transaction time? (we need to know if it is an event trigger or an agreed time-stamp)
What is the transaction time? (time-stamp)
Is the exchange rate predetermined?(contractually agreed, or contingent on the transaction time, above)
What is the exchange rate? (rate)

The area where I have questions is in the codelist for the source 'exchangeRateSource'.

We offer three open codelist options: contract, market and application.

I am not sure how much they add value (yet) - if we have the currency, rate and time-stamp an investigator can check how far the transaction diverges from average exchange rates at the time. Is that actually enough information?

'Contract' appears strong for transparency as it implies that the contract should explain the agreed exchange rate. However, the codelist it is not directly linking to the contract url. Within the contract, the exchange rate might be pre-determined, or it might be agreed that the exchange transaction will be triggered by an event. So, one possible point of confusion is that the contract could lead you to use 'market' rates.
For 'market', is this really just saying that the exchange transaction is not agreed in the contract? If it is not in the contract, we don't know why that particular time-stamp and value are quoted. It will be impossible to say if that transaction if good value for money because it could depend on the transaction volume, different brokers provide different exchange rates and there might be significant transaction costs. So, I think here, that transparency and accountability are difficult to test. A url linking to the contract note for the exchange transaction might be valid but a good financial manager would pool transactions so there might not be a contract note for an individual transaction. So, in conclusion, 'market' might be a natural default that adds little in the way of value to an OCDS dataset.
Probably, the same for 'application' as 'market', but I am not sure. That needs clarification for me.

jpmckinney commented 4 years ago

There has not been further engagement on this issue for two years.

I am not confident in the model, in particular the use of amount_ALT fields (like amount_USD) to describe values in other currencies. The obvious alternative is to separate amount and currency into two fields (e.g. an array of Value objects). The consequence of encoding the currency in the field name is that a user who wants to get all amounts in all currencies (without knowledge of which currencies might exist beforehand) needs to loop over all fields starting with amount_ and in effect reconstruct an array of Value objects – which is unnecessary work.

Happy to re-open to address any outstanding issues pending new demand.

duncandewhurst commented 2 years ago

This issue came up again in relation to modelling a bidder's turnover, which can be provided in multiple currencies (see CRM-7727 for details):

The obvious alternative is to separate amount and currency into two fields (e.g. an array of Value objects).

Do you envisage a sibling to existing .value fields, e.g. contracts.altValues, or a property of the Value object, e.g. contracts.value.altValues?

jpmckinney commented 2 years ago

In general, this seems to be a rare need, and not one that is clearly the responsibility of OCDS.

In CRM-7727, exchange rates come up in the context of selection criteria (yearly turnover). Presumably, local suppliers would evaluate themselves against the local currency. The buyer, I suppose, includes USD conversions because it is the world's reserve currency, so that foreign suppliers can more easily evaluate themselves.

I think the partner's solution to describe the requirement as "yearly turnover in CUR1" and "yearly turnover in CUR2" is fine.

In this issue and #277, there seems to be more interest from IATI than from OCDS stakeholders.

Currency conversion requires methodological decisions (which date is used for the conversion, do you take the market rate or include some fee, etc.), but at any rate exchange rates are easy to look up over APIs. It's not clear that these need to be stored in OCDS. They are facts external to the contracting process.

jpmckinney commented 1 year ago

Closing per previous comment.

The drafted extension was https://github.com/open-contracting/ocds_exchangeRate_extension

open-contracting / standard

Value: Exchange rate #384

The issue

The proposal

Worked example

Engagement