Implementation: Extension proposal for Contract Registers

[timgdavies]

This issue outlines a proposal for an extension. We are looking to introduce this as a community extension during early May, so welcome views and feedback.

Motivation

The contract registers encouraged by the European Commission must include, among other requirements:

• Total value of all payments for the completed contract.
• The date when the contract was completed.
• A justification for the completed contract's value being different than in the original contract.
• A justification for the contract's completion date being different than in the original contract.

Completion refers to the moment when all legal obligations of the contractual parties have been fulfilled (incl. obligations such as maintenance, warranty) or all parties are no longer bound by the contract for other reasons.

Discussion

In OCDS, these values are implicit rather than explicit.

On one hand, if you have complete data (ideal scenario), it is possible to calculate these. For example, within a Contract object:

• If the status is terminated, and if all transactions are disclosed in implementation/transactions, then the sum of implementation/transactions/*/amount/value is the total value of all payments for the completed contract (ignoring the case where multiple currencies are used).
• The two justifications can be calculated by finding the releases that change the value of value/amount and either: concatenating their amendments/*/rationale, or taking the rationale in the most recent release. (If a versionedRelease is provided, it is simpler to find the releases that change the value of value/amount.)

On the other hand:

• That's a lot of if's. There are use cases where transactions are not disclosed, but a final value is still desired. It should be possible to disclose a final value without having to disclose all transactions.
• It's not guaranteed which of the concatenated or most recent rationale is the correct justification. Furthermore, rationale is defined as "An explanation for the amendment", which may not have the desired (or sufficiently specific) semantics for this use case.

Therefore, new fields and guidance should be provided for these use cases.

There is relevant prior discussion in #395 (comment)

Regarding "The date when the contract was completed": A Contract object's period is defined as "The start and end date for the contract." and its endDate is defined as "The end date for the period. When known, a precise end date must always be provided." Whether a Contract object's period field can be used to satisfy this use case depends on whether "completion date" and "end date" are intended to mean the same thing. For example, a contract can end without completion (e.g. early termination).

Questions:

• Are the four values to be provided for each contract, or for the contracting process as a whole?
• For this use case, does "The date when the contract was completed" mean the same thing as "The date when the contract ended"? For example, Would "The date when the contract was completed" be blank if a contract was terminated early and not completed?

Proposal

Following the pattern explored in #395 we propose to extend contracts/implementation with properties for endDate, endDateDetails, finalValue and finalValueDetails as follows:

{
   "contracts":[
      {
        "id":"1",
        "awardID":"1",
        "period":{
          "startDate":"2018-03-01",
          "endDate":"2018-05-01"
        },
        "value":{
            "currency":"USD",
            "amount":1000
        },
        "implementation":{
           "endDate":"2018-05-26",
           "endDateDetails":"Contract was delayed because of strike action.",
           "finalValue":{
                "currency":"USD",
                "amount":1050
           },
           "finalValueDetails":"Value was higher due for foreign exchange fluctuations.",
           "transactions":[],
           "milestones":[],
           "documents":[]
        }
      }
   ]
}

Draft definitions for these properties are below:

• implementation/endDate - The date when contract implementation ended. This should only be provided when contract implementation is complete. Where implementation/endDate varies from the anticipated contract/period/endDate an explanation of the variance should be provided in implementation/endDateDetails.

• implementation/endDateDetails - Details related to the endDate. This may be a justification for the contract's completion date being different than in the original contract.

• implementation/finalValue - The total value of all payments for a completed contract. This should only be provided when the final payment has been recorded. If implementation/transactions are used for this contract, this field should equal the sum of the transaction/value/amount fields. Where finalValue/amount varies from contract/value/amount an explanation of the variance should be provided in finalValueDetails.

• implementation/finalValueDetails - Details related to the final value. This may be a justification for the completed contract's value being different than in the original contract.

Note that we are using 'details' fields rather than 'justification' fields to fit with OCDS idiom, and accomodate cases other than the EU, where these fields could be used for annotation of difference, without neccessarily providing a justification. EU uses would apply a stronger definition to these fields to say that they must include a justification where there is variance.

This modelling would also support the optional inclusion of properties for:

• implementation/startDate in cases where users wish to record the date on which work started on a project.
• implementation/status to apply the ideas from contractStatus: Add termination codes #395 (comment) around allowing the status of implementation to be recorded as cancelled (for example)

Unless there are strong views to the contrary, these to additional fields will not, however, be included in a draft extension.

[timgdavies]

Some additional information we may want to include in the extension in terms of definitions:

This extension provides for summary information about completed contracts. Completion refers to the moment when all legal obligations of the contractual parties have been fulfilled (incl. obligations such as maintenance, warranty) or all parties are no longer bound by the contract for other reasons.

In case of long-term contracts (e.g. large construction works with long-term warranties) it is important to use implementation/milestones to provide information about important moments (e.g. completion of the construction itself).

[JachymHercher]

Thanks for the proposal!

Concerning your two questions above:

• For each contract.
• The way we saw it, it means the same thing. However, it is indeed important to be able to distinguish between a contract which was "successful" and one that "failed". I think we assumed this could either be done via milestoneStatus (or, originally, contractStatus). However, I've read quickly through contractStatus: Add termination codes #395, and my impression is that this actually isn't currently possible, right?

[timgdavies]

Thanks @JachymHercher . I think you are right in the reading that we don't have a conclusive and single simple way to distinguish 'success' from 'failure' at the moment, although it would certainly be possible in some cases to use milestone/status to indicate whether all the deliverables for a contract have been met or not.

Looking back at #395 and working through the data we need to handle, I understand that:

---

A contract is signed, and is then active

The contract is implemented

During the implementation phase, a contract may:

• (1) Be ended:
  • (a) As a result of buyer action
  • (b) As a result of supplier action
  • (c) As a result of a contract term which triggers termination
• (2) End as a result of successful delivery of all milestones or deliverables
• (3) End without successful delivery of all milestones and deliverables

---

Using the implementation/endDate property, and comparing this to contract/period/endDate it is possible to identify when a contract ended early. implementation/endDateDetails can be used to provide a free text justification for this end date, but this does not provide structured information on the reason for the early end (which could be any of (1a-c) or that (2) has happened ahead of schedule).

It may be possible to separate (2) from (1a-c) by the use of milestones such that a contract has a list of milestones, all of which are updated, and have milestone/status = 'met'.

It may be possible to then distinguish (3) from (2) by having milestones with milestone/status = 'notMet', although the definition of this is just that the milestone is not met yet rather than explicitly noting failure to meet the milestone.

All of this makes me wonder whether we do need something like contract/terminatedBy ['buyer','supplier'] and then contract/terminationDetails (though this requires us to sort out the terminology of terminated)?

One of the challenges here (as other research notes below show) is that we've not got many existing contracts registers systems to base a supply-side analysis of data from.

Other research

Oracle have a useful list of how they map different custom contract states to a common list of 'Pending', 'Active' and 'Closed' codes in their systems which illustrates the range of states that might exist in a contract mamangement system, and how these could map to higher level categories.

I couldn't find a contract status field in the Portugal Contracts Register.

[JachymHercher]

Thanks for the analysis. Concerning what happens during the implementation phase, I think it's useful to keep separate the "what", "when", "who". So, for example, I'd say your points (2) and (3) are "what"; you're point (1) is about "who", right? (With, arguably, 1(c) being relevant only to smart contracts, because otherwise it's always an action of a contractual party to interpret a particular provision of the contract as saying this or that, and thus deciding to end the contract.)

For our needs, we are very interested in the "what", while the "who" is definitely a lower priority. Two other considerations:

• I assume the "successful delivery of all milestones or deliverables" refer to the latest version of the contract (i.e. after amendments), which can be described using OCDS in other ways.
• Personally, I'm not sure whether "who" is an administrative detail or actually an important piece of information. Knowing who's fault a termination is would definitely be nice, but I'm doubtful that's linked to who actually terminates the contract.

[timgdavies]

A draft version of this extension is staged at https://github.com/open-contracting-extensions/ocds_contractRegister_extension

In the documentation I've included some signposting to how existing fields can be used as part of a contracts register, although this content may want to move into a separate guidance document in future.

Still to do are:

• Constructing an extended example that shows use of the new fields, amendments, and milestones
• Adding a flat serialization example
• Testing

Feedback on the current draft extension in this thread is welcome.

[timgdavies]

I've added examples and tested the extension. Final step now is to

• Add to the extensions registry

[jpmckinney]

It was added to the registry on September 4. https://github.com/open-contracting/extension_registry/blob/master/extension_versions.csv#L13

[JachymHercher]

1. I've only now noticed that the name of the extension is "contract register". While this extension indeed is for the purposes of contract registers, it makes only a small part of what a contract register should have. Could we perhaps use a "smaller" name, e.g. "contract completion"?

2. The extension is not yet listed at http://standard.open-contracting.org/latest/en/extensions/#community-extensions. Will you be adding it there in the near future?

3. Another piece of information that is relevant at the moment of completing a contract is information about subcontractors, because it might not have been known beforehand. In OCDS, I think this is covered by contract/relatedProcess, can you please confirm this is correct? (Otherwise it might be worth adding this information to the contract register extension.)

[jpmckinney]

1. Good idea regarding the name of the extension – I've reopened the issue to correct that.
2. Yes, though not in the near future. We are working on a new sub-site dedicated to extensions.
3. It depends on what information is to be disclosed about the subcontracts. The eForms consultation document, for example, seems to include only metadata about subcontracts (e.g. estimated value to be subcontracted in total), which would be disclosed as part of the parent process, instead of in separate processes.

[JachymHercher]

1. Thanks
2. If "near future" means more than two weeks, is there any chance you could add it to the current site still? This extension is part of the application process for Connecting Europe Facility grants, so it would be good to have it official, visible, easily findable.
3. More than eForms (since there is no contract completion notice, we stay quite minimalist). I would say who is the subcontractor and what was subcontracted...

[jpmckinney]

2: The community extensions on that page all link to GitHub, so I would recommend directly linking to https://github.com/open-contracting-extensions/ocds_contractRegister_extension

[jpmckinney]

I've made a note in #392 about subcontractors. I've renamed the contract register repository. The old link redirects without issue.