Value object structural changes
Closed this issue · 9 comments
@JachymHercher wrote in #817:
In #896 (comment), we mention distinguishing
value
andmaximumValue
(for a framework agreement) as well as potentially anestimatedValue
(for a framework agreement). Combining it with the three tax-related fields, we have nine value fields (applicable inTender
,Award
andContract
), 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 thatValue
contains the nine values, each of which then contains anamount
andcurrency
.- Perhaps we should change
Value
into an array and add something liketax
within, which can contain 'gross', 'net' and 'unknown' (and probably clarifies that empty means 'unknown' as well); as well as adding something liketype
intoValue
, 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 forValue
, 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 changeValue
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)?
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?
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.)
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}
.
I'll optimistically close the issue, but happy to re-open if there are concerns with the current direction.
(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 thatValue
contains the nine values, each of which then contains anamount
andcurrency
.
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.
@JachymHercher Can you provide some JSON samples of your proposal(s)? I'm not sure I get it.
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"
Yes, though I don't remember where we discussed a minimum value.
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.