Consider adding time-based fields to preserve the values of important fields in a compiled release

[duncandewhurst]

From the discussion in #914, we should consider whether to add time-based fields to preserve the values of important fields such as the dates and values of the main objects (tender, award, contract).

For example, we could add an explicit field to preserve the initial period in the signed contract. Otherwise, no option is perfect with respect to identifying changes to the contract period:

• Relying on individual releases - most publishers don't provide individual releases, most tools and methodologies are based on compiled releases.
• Comparing awards and contracts - if there is a difference between awards.contractPeriod and contracts.period in a compiled release, it's not possible to determine whether the difference is due to a delay to signing the contract, or a post-signature change to the period.
• Using the completion extension - if contracts.period.endDate and contracts.implementation.endDate are equal in a compiled release, it's not possible to determine whether the contract was completed according to the original period in the signed contract, or whether the contract was amended and contracts.period.endDate updated.

[duncandewhurst]

Looks like there's been no further demand for these extra fields since this issue was created. I think we have three options:

1. Do some further analysis of the potential need for time-based fields to preserve the initial dates and values of tenders, awards and contracts and add the necessary fields.
2. Only add a field to preserve the initial period in the signed contract, per the example in the issue description.
3. Close the issue pending further demand.

I'm leaning towards 3. @jpmckinney what do you think?

[jpmckinney]

@yolile Since you added a thumbs up, what do you think?

Values

Changes in contract values are a common concern, but I think we can trust that the awarded value is almost always the initial contract value (or sum of the initial contracts' values). Unless the publisher made an error in their modelling, I don't think it's allowed to award a contract for one value and sign a contract for another value (especially a higher value).

For award values, I don't know how frequently these are updated. Unless there was an error, I don't think these change.

For tender values, I think these can be updated if e.g. the estimated value was corrected. I'm not aware of any use cases for tracking such changes – if a corrupt buyer wanted to overpay a friendly business, they would just set a high original estimate – they wouldn't amend it.

So, I think we're fine with existing fields for values.

Dates

Changes in dates are less important.

For tender dates, like tender values, I think these are largely expected to be corrections, and so the most recent value is the most (and, I think, only) relevant value.

For award dates, like award values, I don't think these are expected to change. Perhaps a very sophisticated implementation would change the contractPeriod if e.g. there were delays in signature due to complaints. In that case, the most recent value is the most relevant value, anyway.

For contract dates, this issue description covers the case where it's relevant to track the original. The main issue identified is when the contractPeriod at the time of the award is inaccurate. I think this scenario occurs infrequently enough that we don't need to add fields to cover it.

Since we haven't identified any other time-based fields, I'm fine to close this issue.

[yolile]

Sounds good. For contract values, a real example was discussed in #575 (comment), and we had already agreed that the award vs. contract value should work for that.

But I'm wondering if we should add a worked example or similar to the documentation to make this clearer (and maybe check our data use guidance around contracts overrun/budget indicators to ensure we are also suggesting to compare awards vs. contracts for calculating them)

[jpmckinney]

For this issue, we can review the field descriptions to be sure this point is clear.

We can create a new issue about an example in the guidance.

[duncandewhurst]

Great. Thanks, both!

[duncandewhurst]

@jpmckinney I've proposed a couple of options for clarifications to the field descriptions below (changes in italics). Let me know what you think.

Option 1

I'm unsure about the change to Award.value as it somewhat muddies the distinction between awards and contracts.

Award.value:

The value of this award, i.e. the initial value of a contract at the time of its award. There may be more than one award per procurement. A negative value indicates that the contract(s) resulting from this award may involve payments from the supplier to the buyer (commonly used in concession contracts). This field should not contain the value of a framework agreement; those should be given in estimatedValue or maximumValue instead.

Contract.value:

The value of this contract. A negative value indicates that the contract will involve payments from the supplier to the buyer (commonly used in concession contracts). The value may be updated during implementation, e.g. to reflect an amendment. This field should not contain the value of a framework agreement; those should be given in estimatedValue or maximumValue instead."

Option 2

This option perhaps overloads the description of Contract.value with a description of the use of Award.value.

Award.value (no change):

The value of this award. There may be more than one award per procurement. A negative value indicates that the contract(s) resulting from this award may involve payments from the supplier to the buyer (commonly used in concession contracts). This field should not contain the value of a framework agreement; those should be given in estimatedValue or maximumValue instead.

Contract.value:

The value of this contract. A negative value indicates that the contract will involve payments from the supplier to the buyer (commonly used in concession contracts). The value may be updated during implementation, e.g. to reflect an amendment. It can be compared to the original value of the contract in the related award. This field should not contain the value of a framework agreement; those should be given in estimatedValue or maximumValue instead."

[jpmckinney]

Hmm, good question.

I think the first Contract.value is fine, though we have started using the parenthesized "(for example, ...)" instead of the Latin acronym "e.g.".

For award, maybe after the first sentence:

Typically, this is the value of the bid being awarded.

[duncandewhurst]

For award, maybe after the first sentence:

Typically, this is the value of the bid being awarded.

That seems like a good solution to me.