Update Value.amount description to suggest/recommend tax-free amounts

[jpmckinney]

Following discussion from #383 (comment) and following comments.

[jpmckinney]

In CRM-5172, we discussed the possibility of a publisher/aggregator having a tax-inclusive amount and not being able to determine the tax-free amount. The options would be:

1. Put the value after tax in amountGross, and don't set amount. This will produce a combined dataset in which either amount or amountGross is set depending on whether tax is included or not. Not every value will have an amount (tools or analyses that are unaware of amountGross, and that don't warn or error when amount is missing, will have incomplete data), but at least every field will have consistent semantics, independent of the values of other fields.
2. Use the boolean valueAddedTaxIncluded from this extension, and put the value after tax in amount. This will produce a combined dataset in which amount is either with or without tax depending on valueAddedTaxIncluded. This will make amounts harder to compare (tools or analyses that are unaware of valueAddedTaxIncluded will get incorrect answers), but at least every value will have an amount.

The first option is preferred, because inconsistent semantics (second option) seems very bad. And it is easier for a tool/analysis to error/warn if an expected field is missing, than for it to somehow know that another field is changing the semantics of amount.

[jpmckinney]

We should determine whether any publishers are in a scenario where they either (1) don't know which amounts are tax-free or (2) can't calculate the tax-free amount.

If so, we can clarify that amount is for the amount as stated on the tender notice / award notice / contract document. We would then recommend that, wherever possible, both amountNet and amountGross fields are filled in. That way, if a dataset has amountNet and amountGross, then users can have access to fields with consistent semantics; if the dataset lacks the fields, then users can know the caveats around amount.

[fmatzdorf]

Our scenario as a publisher is mentioned in #817 (comment). We have a dataset that is compiled from many different sources, all of them relating to contracts published by different agencies in the Mexican government. We know that some of the datasets have taxes included in the amount and some don't, but the exact percentage of tax has been impossible to determine.

On all of our datasets the exact percentage of tax varies from contract to contract, whether the amount provided includes tax or not. We have filed many requests for information to determine exact tax percentages by contract, but the responses have not helped us solve this, since they only include the possible values for tax percentage but not which contracts are associated with each tax value. So the best we can do is to express whether or not the amount includes taxes or not.

We agree with the last comment. The best solution would be to have all 3 fields present in the compiled dataset. This way all contracts provide at least one amount (in the amount field) and in the cases where we do know whether or not tax is included we can fill in either amountGross or amountNet.

[jpmckinney]

Thank you, @fmatzdorf, for sharing evidence supporting that option!

[JachymHercher]

If so, we can clarify that amount is for the amount as stated on the tender notice / award notice / contract document. We would then recommend that, wherever possible, both amountNet and amountGross fields are filled in. That way, if a dataset has amountNet and amountGross, then users can have access to fields with consistent semantics; if the dataset lacks the fields, then users can know the caveats around amount.

I quite like the approach above, but I have two doubts:

• Do I understand it correctly that the two new fields are either including / excluding all taxes, not just VAT? If yes, good. Knowing the exact values/percentages for different types of taxes is unnecessary for most users, I think.
• In #896 (comment), we mention distinguishing value and maximumValue (for a framework agreement) as well as potentially an estimatedValue (for a framework agreement). Combining it with the three tax-related fields, we have nine value fields (applicable in Tender, Award and Contract), which is a bit longwinded.

  • Perhaps that's not a problem.

  • Perhaps that's something we can live with in OCDS 1.2 and then we can do a backwards-incompatible change in OCDS 2.0 of adding a layer into Value, so that Value contains the nine values, each of which then contains an amount and currency.

  • Perhaps we should change Value into an array and add something like tax within, which can contain 'gross', 'net' and 'unknown' (and probably clarifies that empty means 'unknown' as well); as well as adding something like type into Value, which can contain 'maximum', 'estimated', 'actual/real/awarded/signed'. This would make it more compact (and probably more flexible for the future, e.g. for adding detailed tax information), but the meaning of one field would influence another. On the other hand, that's always been the case for Value, so I'm wondering whether it's a serious problem. Assuming that changing a normal field to an array is a backwards incompatible change, in OCDS 1.2, we could only add the classifying fields, but not change Value to an array, that would have to wait for OCDS 2.0.

    I find the third option slightly preferable.

[jpmckinney]

Do I understand it correctly that the two new fields are either including / excluding all taxes, not just VAT? If yes, good. Knowing the exact values/percentages for different types of taxes is unnecessary for most users, I think.

Yes, amountNet should be defined to exclude all taxes.

For the rest, I think we need a separate issue, as it's about changing the structure of the Value object, rather than adding/updating its fields. I created #1143

[ColinMaudry]

Does this issue (expanding the description of Value.amount) depend on the fate of #1143?

[jpmckinney]

#1143 is abandoned. This issue can proceed.

[odscjen]

Checking if this issue can move to PR and if so clarifying that what's required is 2 new fields value.amountNet and value.amountGross and an update to the description of value.amount to make clear it's the amount as stated in the tender/award/contract documentation?

[jpmckinney]

Yes, there seems to be consensus around #817 (comment)