Add Milestone.value field (related to payment schedules, planned transactions)

[timgdavies]

Summary

Motivation

Need to express planned transactions.

Proposal

Use milestones:

• Add a new code to milestoneType.csv
• Add a value field to Milestone

---

We've had a request to be able to support information on planned payment schedules:

There is a chance that altogether with the contract [ ] we'd have to
have so called payment schedule, it is something like Plan for Transactions
of a Contract. Since there is no Invoice in OCDS but only Transaction, I'm
thinking of extending it with state, like Tender has. Transaction in draft
state would represent element of payment schedule, in pending state - the
phase when Invoice is sent, and complete state when Transaction actually
happened already.

Current situation

At the moment we have the transactions block which, in 1.1, contains:

• id - ID: A unique identifier for this transaction. This identifier should be possible to cross-reference against the provided data source. For IATI this is the transaction reference.
• source - Data source: Used to point either to a corresponding Fiscal Data Package, IATI file, or machine or human-readable source where users can find further information on the budget line item identifiers, or project identifiers, provided here.
• date - Date: The date of the transaction
• value - Value: The value of the transaction. See Value Object
• payer - Payer: An organization reference for the organization from which the funds in this transaction originate. See OrganizationReference Object
• payee - Payee: An organization reference for the organization which receives the funds in this transaction. See OrganizationReference Object
• uri - Linked spending information: A URI pointing directly to a machine-readable record about this spending transaction.

We note that this is modelled on the IATI transaction model although we did not use the 'transaction-type' concept from IATI to allow a distinction between 'commitments', 'disbursements', 'expenditure' and so-on (similar to the idea of a transaction.status field).

Considerations

One of the advantages of our current model is that a user can simply sum up all the transactions to get total spend on a contract (something that gets quite complicated when there are status fields involved to be aware of). Our documentation states that transactions "can be used to represent actual flows of money between organisations in relation to this contract." suggesting that if we changed it to also include non-actual (i.e. planned) flows, this would not be in conformance with current use.

There has also been some work on an extension to relate transactions and milestones, such that milestones could be used to represent invoice deadlines.

Using the proposed budget breakdown extension it is also possible to model small payment periods that could be matched to invoice deadlines, and that allow for different sources of money to be specified.

Options

In response to the initial inquiry, I would suggest:

• First, looking to see whether using milestones to capture invoice deadlines could suffice, particularly with the milestoneType codelist introduced in 1.1 (and as an open codelist, so it could have invoice milestones added to it);

• Second, if this does not work, looking at creating an alternative property pointing to an array of Transaction objects - potentially paymentSchedule.

For really detailed post-award invoicing information, I wonder to what extend CEN-BII can provide models to link out to.

[myroslav]

It look like Milestone should cover majority of the cases with type: financing (or should we extend codelist with dedicated payment type) and status: scheduled.

The biggest missing part is value that is part of Payment. It can be added to Milestone as Extension. Are there are more elegant approaches?

[timgdavies]

As type is an open codelist, I suspect 'payment' would be good to add, with status of scheduled.

Extending these milestones with a value sounds like the best approach to me.

[jpmckinney]

'financing' typically refers to the funding of the procurement/contracting process.

At one point this code was only in the schema (without a description), and it was later moved to the codelist, where it was defined without any documented discussion in this commit related to #471.

The code was first added to the schema in this commit as part of #373, where neither the 'financing' code nor the alternative 'financial' code have any documented discussion – neither in linked issues (#227 open-contracting-extensions/public-private-partnerships#25 open-contracting-extensions/public-private-partnerships#37) nor in the draft update.

I finally found the originally proposed code description in this spreadsheet (created solely in the context of OCDS for PPPs) for the alternative 'financial' code.

So, my interpretation of the current code description is that both sides of the "or" are meant to be modified by "in public private partnership projects", and that the comma makes this ambiguous (similarly confusing commas have occurred elsewhere, and not all have been fixed).

For events such as planned payments, or equity transfers in public private partnership projects.

In short, the 'financing' code should not be used for payments to suppliers, which is not a form of "financing" in the usual use of the word in English.

I've created #937 to fix the code description.

[jpmckinney]

Adding to 1.1.5 milestone to add the 'payment' code (can go along with #937). This issue is ready to PR, as it just involves proposing a code title and description.

Once that is done, the milestone can be changed back to 1.2.0 to consider adding a value field to Milestone.

[duncandewhurst]

The original enquiry about planned payment schedules related to Moldova. Looking at the MTender front end and OCDS data, I don't see any evidence that data on planned payment schedules is actually collected or disclosed. Based on that, we might want to leave this issue until we see more demand.

@myroslav @PaulBoroday please correct me if I'm wrong. Thanks!

[yolile]

I'm not sure about the semantics but, in Argentina Vialidad they use a planning/milestones/value object, eg:

{
  "id": "4",
  "type": "assessment",
   "title": "Preadjudicación",
   "value": {
     "amount": 39953420.85,
     "currency": "ARS"
   },
  "status": "met",
  "dateMet": "2018-06-26T11:00:00Z"
}

From https://datosabiertos.vialidad.gob.ar/api/ocds/package/ocid/ocds-4jg6r3-0009120-2017

[duncandewhurst]

Thanks, @yolile. Good idea to check other publishers. For completeness, I checked all the fields in OCDS Downloads and Argentina Vialidad was the only one with a milestones/value field.

Can we ask the publisher about the semantics of their data? It's not clear to me either.

[yolile]

Ah, I remember it now, the value object in Milestone is also used in Chile (see internal discussions in the CRM-5334#note-2)

Their use case is indeed planned payment schedules.

(and they are using contracts/implementation/milestones/associatedValue (we had recommended them to use value but 🤷‍♀️ ) that is why you didn't find them in OCDS Downloads)

example

[duncandewhurst]

Great. That seems like enough demand to proceed. However, it would still be good to understand Argentina Vialidad's use of the field, so that we can define appropriate semantics.

[yolile]

Agree. I'm doing a little bit of research on the documents we have from them, and it seems that in Argentina Vialidad they have a pre awarding committee that must approve the "pre awarding" values before the actual award, and it seems they are mapping that amount as a planning milestone amount, for some reason (eg "title": "Preadjudicación" = pre award). It sounds like something not that well mapped. From the example, you can see that the milestone/amount (39953420.85) is indeed the same as the award/amount. I also found the document related to the committee decision here that also mentions the same amount as the amount bidded by the supplier. That amount is also in the bids array in the example. That said, I think the Argentina example is not a good/correct example for the Milestone.value use case after all.

[duncandewhurst]

Understood - thanks for the research! I'll go ahead with adding the field.

[jpmckinney]

I suppose it makes sense to have milestones (rather than just adding a Transaction.status field) in case the payments are known at, e.g., the tender stage, before a contract is signed. That said, such schedules are usually expressed as, e.g., "50% on signature, and 50% on delivery." So, I don't know that this use case is fully supported.

Another advantage is that, if we were to add Transaction.status, then existing systems will not be aware of that field, and would interpret, e.g., 'pending' transactions as having been realized. The semantics of other fields in the Transaction object would change with the addition of a status field, which I figure would be backwards-incompatible.

Based on the second advantage above (also noted under Considerations in the issue description), I think it's okay to proceed with the proposal.