search

open-contracting / standard

Documentation of the Open Contracting Data Standard (OCDS)
http://standard.open-contracting.org/
Other
139 stars 46 forks source link

Amendment handling - confusing and inconsistent #106

Closed birdsarah closed 10 years ago

birdsarah commented 10 years ago

"I'm not clear on when a contract would be an amendment. Shouldn't amendments be a property on the contract being amended? It doesn't seem possible right now to answer the question, "What amendments exist, if any, for this contract?" Putting the property on the contract being amended would make this much easier."

From @jpmckinney #61

birdsarah commented 10 years ago

Also relates to #82 & #57.

birdsarah commented 10 years ago

Hi, this is a really interesting question. Let me explain the intention and then it would be great if @jpmckinney could comment on whether this is a documentation problem or a field problem.

Let's say contracts 1 and 2 are issued under a unique process. For the releases you may just see a release on Jan 1 (paraphrasing) for contract :

{
    "ocid": "ABC",
     "contracts": [ 
        {
             "contractID": 1, 
             "contractValue": 12
        } 
     ]
}

on Jan 2, for contract 2

{
    "ocid": "ABC",
     "contracts": [ 
        {
             "contractID": 2, 
             "contractValue": 24
        } 
     ]
}

At this point, if a record was made with a compiledRelease, it would look like this (contracts match on contractID:

{
    "ocid": "ABC",
     "contracts": [ 
        {
             "contractID": 1, 
             "contractValue": 12
        } ,
        {
             "contractID": 2, 
             "contractValue": 24
        }
     ]
}

Now, on January 4th contract 1 gets amended, its value gets increased. The release is:

{
    "ocid": "ABC",
     "contracts": [ 
        {
             "contractID": 1, 
             "contractValue": 102,
             "isAmendment": true,
             "amendment": {"amendmentDate": "2014-01-04", "amendedFields": "contractValue", "justification": "typo."}
        } 
     ]
}

At this point, the compiledRelease in the record looks like this:

{
    "ocid": "ABC",
     "contracts": [ 
        {
             "contractID": 1, 
             "contractValue": 102,
             "isAmendment": true,
             "amendment": {"amendmentDate": "2014-01-04", "amendedFields": "contractValue", "justification": "typo."}
        } ,
        {
             "contractID": 2, 
             "contractValue": 24
        }
     ]
}

Here's what's really interesting now I'm typing this out. In a release, the "isAmendment" makes perfect sense because its a snapshot point. In the record, in the compiledRelease it makes no sense, and in the versionedRelease it will make even less sense! In the compiledRelease, the statement isAmended would make sense, but the data that's under amendment would only be for the latest change and is pretty confusing.

I'm actually thinking that:

birdsarah commented 10 years ago

I'm closing #82 as its closely related and bringing the discussion here:

notice: Is this notice ever expected to be an amendment? Since a formation/tender has a single notice, I suspect not. However, the current schema allows it.

jpmckinney commented 10 years ago

Thanks, I can see how the fields are meant to be used now. I assume amendment is meant for official amendments – not "oops, we exported our data badly," but when the procuring entity publishes an official document amending an original tender, for example. Is that correct?

It seems like right now, you can only amend a contract/notice once. But there can be multiple amendments, each modifying the same field. I propose eliminating isAmendment and changing amendment to a list of amendments. To make it possible to actually track the change in values (especially when changed multiple times), the Amendment class should have the properties:

Otherwise former values are lost, but they are relevant.

birdsarah commented 10 years ago

Hi, well the interesting thing is that the versionedRelease will already build that list of amended fields for you, so there isn't really a need to be overly burdensome and ask that each release list all the amendments that have been made.

Have you looked at http://nbviewer.ipython.org/github/open-contracting/sample-data/blob/master/buyandsell/processing/Demonstrate%20merging%20a%20release.ipynb

You can see, for example at In [12]: that the versionedRelease has all the value history for you. What we want to know is just the rationale :) on the release.

jpmckinney commented 10 years ago

It's possible for a record to be published with a full list of amendments without there having been any earlier versions, though.

birdsarah commented 10 years ago

?

jpmckinney commented 10 years ago

Scenario 1: A publisher publishes a new tender, then the same tender after amendment 1, then the same tender after amendment 2. 3 versions.

Scenario 2: A publisher is preparing historical data in OCDS format. Instead of doing 3 versions, it just does a single version which includes details about all the amendments.

I think Scenario 2 should be possible without loss of information. It seems weird to have to author artificial versions just to preserve the former values.

birdsarah commented 10 years ago

iiiinnnteresting!

myroslav commented 10 years ago

That changes thing from https://github.com/open-contracting/standard/issues/106#issuecomment-57866900 above is wonderful! It solves the issue I had (and wanted to solve by generating the contents of justification/rationale field).

practicalparticipation commented 10 years ago

In looking at this further, it seems to me that:

Where Update is a change to the details due to corrections to the data. And Amendment is a legal amendment.

The releaseTag already gets carried into the versioned release, and so this would let a user easily filter out all the contractAmendments from a version history etc.

The only thing I'm left wondering is whether we do need some mechanism to state explicitly the ID/URI of the release that is being updated / amended. Although the merge strategies that generate a record do not rely on this, making explicit what is being amended/updated, rather than relying on date order, might be helpful.

Update

I realise that the proposal above lost the justification field.

Based on #101 this could be re-introduced as a free-text top-level optional property named:

practicalparticipation commented 10 years ago

@LindseyAM can you provide us with a list of all the things that could get amended in the legal sense (e.g. is there a meaningful notion of legally amending a tender or award, or do amendments only really apply to contracts?)

jpmckinney commented 10 years ago

Canada (at least its provinces and municipalities where I've seen it happen) has legal amendments to calls for tender.

LindseyAM commented 10 years ago

@jpmckinney in french or english? My understanding is that in french/spanish the word is the same, maybe its a specifically english language issue that while tender/awards can be modified and revised, the binding legal change to the obligations of the parties that occurs to the contract would be what would be called an amendment (although it could be called a modification as well). At the core, this is a semantics issue and not really a substantive issue. The main thing that I think is important is to capture changes to the data both before the contract is signed and especially after the contract is signed.

jpmckinney commented 10 years ago

In English.

myroslav commented 10 years ago

BTW, there is RFC 6902 that describes the JSON Patch notation that would fit for changes mentioned in https://github.com/open-contracting/standard/issues/106#issuecomment-57866900 - is there reason to reuse it? BTW, there is https://github.com/stefankoegl/python-json-patch library that can be used to generate and apply the patches to recreate older revisions of the objects.

practicalparticipation commented 10 years ago

At the moment our approach is closer to the JSON-Merge-Patch draft, in which a subsequent release amends a previous release, but our merge tools/merge strategies propose a way of keeping this version history in the compiled record.

There are some outstanding issues with #42 however to still resolve I think.

myroslav commented 10 years ago

It look like jsonmerge tool can merge documents, but in changes we need a list of items changed, and in case of JSON Patch there was python-json-patch tool that helped generate the patches. Is there an equivalent tool for generating JSON Merge Patch documents?

In fact we do not need a full patch document, but only the diff (python-json-patch lib is just ok for that). But we also need the way to store the list of changes (as @jpmckinney suggested in https://github.com/open-contracting/standard/issues/106#issuecomment-57866900):

Alternatively we can have "reverse Merge patch" in changes to be able to generate older revision of document from latest one. Please let us know the proposed approach to recording the changes.

practicalparticipation commented 10 years ago

Ok, would the following be an accurate statement of the issue:

I can see the case for this, and your proposed use of JSON Patch does seem to be a reasonably good way of approaching this.

The issue I can see here is that we would either (a) need JSONPath if people wanted to update, for .e.g, a specific item within an itemsContracted array etc. or (b) in these cases for formerValue to contain the complete old array - and both of these start getting hard to serialise in other formats.

I wonder if our best option here is to prototype the JSON Patch changes approach as an extension, and stick with (1) for the majority of initial use cases?

myroslav commented 10 years ago

I'm representing here Publisher, and we are trying to conform our Tender Management Database to Open Contracting Standard as much as possible.

We have requirement to track changes, and https://github.com/open-contracting/standard/issues/106#issuecomment-57866900 fits that requirement quite well. We'd need suggestion of what tools to use for generating diffs between versions (we lean to python-json-patch, since it does produce information to produce changes list), and suggestion of what format to choose for property value, and our current options are JSON Pointer and JSON Path (and it look like the former is more standard choice).

Since we'll do it as extension, it would be good to be as compatible with Open Contracting as possible.

birdsarah commented 10 years ago

@LindseyAM @marcelarozo - I am working up a new proposal to this, but I just want to clarify something.

At the moment, the amendment fields are on: Notice and Contract. Notice is in turn, attached to Tender and Award.

So we have:

I think that the Amendment information should apply to the whole tender and award (not just the notice), e.g. should include changes to value to selection criteria.

Please confirm / comment on the following.

1 - Amendment information should be available on Contract, Tender, Award.

2 - This is the only amendment information that is needed.

@jpmckinney @practicalparticipation I think my proposal is the following.

We have a mechanism for publishing information a series of changes. It is publishing a series of releases. @jpmckinney's proposal, to my mind, adds a parallel way of providing versioning information. This seems: 1) Confusing 2) It is not very compatible with the release -> record model (because trying to compile / version the versioned info could easily get incomprehensible)

I would like to keep @jpmckinney changes list but otherwise maintain the current method of documenting version changes - a separate release per version (these could all be in one package, one after each other). Where each release contains the new field values and the amendment reasoning.

Each release would just contain one set of amendment info, the compiled record would contain the list of amendments. But the changes list on each amendment provides a nice cross check on any updates.

So the changes are:

Having said all that, I do understand @jpmckinney's point about a quicker way to publish historical data, but I'd like to come up with a solution to that in collaboration with publishers if they raise this model as too problematic.

myroslav commented 10 years ago

In our Tender management system we need both to have very detailed history record of what had changed in the Tender object itself (field-wise, altogether with actor information) and also let people have amendments to documentation attached to tender.

The changes we decided to go with reverse json-patch (i.e. each changes entry specifies how to come to previous version from newer one).

In documents we have document versioning and additional documentType for amendments to highlight documents that contain legally actionable description of changes to tender documentation.

changes are tracked automatically, amendments is something to be prepered in advance and attached to Tender like any other document.

jpmckinney commented 10 years ago

Sounds good. Why rename amendment to amendmentInformation?

marcelarozo commented 10 years ago

To my mind, during the tender period the only amendments possible would be to the tender notice, because the tender Boyce is the one that establishes the "rules of the game" for the tender so there is where the changes are made.

Myroslav raises the documents that the bidders might change or add to their bid at the request if the procuring entity but I don't think that has the character of an amendment (legally speaking). @LindseyAMhttps://github.com/LindseyAM?

Sent from my iPhone

On Nov 4, 2014, at 2:23 AM, "Sarah Bird" notifications@github.com<mailto:notifications@github.com> wrote:

@LindseyAMhttps://github.com/LindseyAM @marcelarozohttps://github.com/marcelarozo - I am working up a new proposal to this, but I just want to clarify something.

At the moment, the amendment fields are on: Notice and Contract. Notice is in turn, attached to Tender and Award.

So we have:

I think that the Amendment information should apply to the whole tender and award (not just the notice), e.g. should include changes to value to selection criteria.

Please confirm / comment on the following.

1 - Amendment information should be available on Contract, Tender, Award.

2 - This is the only amendment information that is needed.

@jpmckinneyhttps://github.com/jpmckinney @practicalparticipationhttps://github.com/practicalparticipation I think my proposal is the following.

We have a mechanism for publishing information a series of changes. It is publishing a series of releases. @jpmckinneyhttps://github.com/jpmckinney's proposal, to my mind, adds a parallel way of providing versioning information. This seems: 1) Confusing 2) It is not very compatible with the release -> record model (because trying to compile / version the versioned info could easily get incomprehensible)

I would like to keep @jpmckinneyhttps://github.com/jpmckinney changes list but otherwise maintain the current method of documenting version changes - a separate release per version (these could all be in one package, one after each other). Where each release contains the new field values and the amendment reasoning.

Each release would just contain one set of amendment info, the compiled record would contain the list of amendments. But the changes list on each amendment provides a nice cross check on any updates.

So the changes are:

Having said all that, I do understand @jpmckinneyhttps://github.com/jpmckinney's point about a quicker way to publish historical data, but I'd like to come up with a solution to that in collaboration with publishers if they raise this model as too problematic.

— Reply to this email directly or view it on GitHubhttps://github.com/open-contracting/standard/issues/106#issuecomment-61602321.

marcelarozo commented 10 years ago

I meant Notice not Boyce (phone auto correct :)). Another call for Lindsey to give her opinion @LindseyAM

myroslav commented 10 years ago

We do have separate places to store Tender documents and Bid documents (i.e. we do not mix them, at least while Tender is being run). And we tend to keep Bid documentation quite similar to Tender documentation, this would be especially important if bidder is willing/going to change/update documentation after contact has been awarded. We need to be able to track that changes/amendments too since they can be significant and corruptive actions.

birdsarah commented 10 years ago

@marcelarozo @LindseyAM "To my mind, during the tender period the only amendments possible would be to the tender notice" - that was always my understanding. But, on reflection, sometimes things get entered / published wrong and the fields that are on notice are only a small section of those about Tender, so I think it's best to make the ability to document changes less restrictive.

birdsarah commented 10 years ago

(of course by that logic, we could just have one amendments blob at the uppermost level)

LindseyAM commented 10 years ago

Hi All -- this conversation chain seems to be getting complicated but what Sarah, Marcela and Myroslav have said all make sense. My attempt at a summary that answer's Sarah's original question: The notices and the contracts can be amended and the amendment would change something, so its important to capture (if possible) what changed (whether a field or an attachment) in addition to the fact that there was an amendment. Does that make sense?

On Tue, Nov 4, 2014 at 9:12 PM, Myroslav Opyr notifications@github.com wrote:

We do have separate places to store Tender documents and Bid documents (i.e. we do not mix them, at least while Tender is being run). And we tend to keep Bid documentation quite similar to Tender documentation, this would be especially important if bidder is willing/going to change/update documentation after contact has been awarded. We need to be able to track that changes/amendments too since they can be significant and corruptive actions.

— Reply to this email directly or view it on GitHub https://github.com/open-contracting/standard/issues/106#issuecomment-61696356 .

practicalparticipation commented 10 years ago

One of the ways I think we had looked at handling this was covering things at the top level, but making use of releaseTag to indicate whether a change is an amendment (legal status), or an update (a change, not legally significant).

See the releaseTag draft content in the codelists document

andrewlorien commented 7 years ago

I know this is a million years old, but to support Tim's last comment about legal significance above: in AusTender, only Contracts are amended. And they can either be a "material amendment", which is a change to a specific set of fields (eg the value), or a "non-material amendmend", which is a change to any other field (eg a phone number).