Value object structural changes

[jpmckinney]

@JachymHercher wrote in #817:

• 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.

Could you refresh my memory in what scenario both value and maximumValue are set? Also, is estimatedValue relevant anywhere except Tender (where both value and minValue are described as estimates already)?

[jpmckinney]

Sorry, I just re-read in #896:

When working with the word "estimated", we should take care to distinguish between "Estimated refers to estimation at the time of launching the call for competition" and "Estimated refers to estimation at the time of concluding the framework agreement." (eForms does not do that too well, see eForms/eForms#329 (comment).)

So, estimatedValue is relevant in Award in the case of a framework agreement, though as I understand there would just be a maximumValue and not a value on the award(s) for the setup of a framework agreement.

Update: In #896 (comment), it's suggested to use awards/value for that estimated value – but then I need to clarify: Is "estimation at the time of concluding the framework agreement" the estimated value of the FA as a whole, or just the specific supplier(s)' portion of the FA?

[JachymHercher]

So, estimatedValue is relevant in Award in the case of a framework agreement, though as I understand there would just be a maximumValue and not a value on the award(s) for the setup of a framework agreement.

My (and eForms) thinking: a framework agreement (FA) has EstimatedValue and/or MaximumValue (which of the two depends on jurisdiction/case by case), while non-FA has Value. Value does not appear together with the other ones.

Update: In #896 (comment), it's suggested to use awards/value for that estimated value – but then I need to clarify: Is "estimation at the time of concluding the framework agreement" the estimated value of the FA as a whole, or just the specific supplier(s)' portion of the FA?

Discussed in #896 (comment). (The two will usually be the same; if a publisher wants to distinguish them, he can publish both.)

[jpmckinney]

With respect to this issue, where the problem is having "nine value fields (applicable in Tender, Award and Contract)," it sounds like while the schema might define many fields (though as I understand each of Tender, Award and Contract will not need all 9), the data will often have one, sometimes two, in each of Tender, Award and Contract.

If the data is simple, and if publishers have clear guidance on when to use which field (and we've already established that the fields have distinct semantics and use cases), then I don't think there is an issue. Having an array of values tends to be harder on users, because the semantics of the value are stored in a separate field, rather than in the name of the field, i.e.

{"type": "estimated", "value": 100} rather than {"estimatedValue": 100}.

[jpmckinney]

I'll optimistically close the issue, but happy to re-open if there are concerns with the current direction.

[JachymHercher]

(though as I understand each of Tender, Award and Contract will not need all 9), the data will often have one,

I think each of those will need 9, but the data itself can never have 9 and usually will have just one.

• 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.

Just realized - this was not correct. If we added a layer into Value with the different value fields while keeping amount and currency, then this would be a backwards compatible change. Assuming it is not too messy, this might be a good direction to go - that way, we have a single Value block that contains all value fields and is used across Tender, Award and Contract.

I'll optimistically close the issue, but happy to re-open if there are concerns with the current direction.

Since, #896 (comment) reminds us to add the 2 framework-related fields and #817 reminds us to add 2 tax-related fields, then, as long as we don't forget that they interact and whether we put them in a new layer, we can close this issue.

[jpmckinney]

@JachymHercher Can you provide some JSON samples of your proposal(s)? I'm not sure I get it.

[JachymHercher]

Sorry, I think I misunderstood the discussion above (I was crossing values and amounts, ignoring that amounts are nested within the values).

To make sure that I understand it correctly now: we will add MaximumValue and EstimatedValue at the same level as the existing Value (and MinimumValue); while we will add amountGross and amountNet inside each of the value object. I.e. the schema will look something like this, right?

"Value"
    "amount"
    "amountGross"
    "amountNet"
    "currency"
"MaximumValue"
    "amount"
    "amountGross"
    "amountNet"
    "currency"
"Estimated Value"
    "amount"
    "amountGross"
    "amountNet"
    "currency"
"Minimum Value"
    "amount"
    "amountGross"
    "amountNet"
    "currency"

[jpmckinney]

Yes, though I don't remember where we discussed a minimum value.

[JachymHercher]

We didn't, I just now noticed it's already in OCDS and I've been ignoring it up till now, so I thought I'd haphazardly mention it above.