Deprecation policy

[timgdavies]

This issue is under consideration for the 1.1 milestone.

Building on discussions in #189

The issue

Our deprecation policy currently states (emphasis added)

“If a term (a class or field) is scheduled to be renamed or removed from the specification as a result of the revision process, the next major release of the specification must deprecate the term within the schema, and the following major release must rename or remove the term from the schema, making the term obsolete. Implementations may use deprecated terms, but will receive warnings from the OCDS validator described below. Implementations may not use obsolete terms, and will receive errors from the OCDS validator.”

This means we can currently only deprecate fields in version 2.0, and remove them in 3.0.

What we are proposing:

Updating the deprecation policy to replace the first mention of major release with minor release.

This will allow a minor/decimal update (e.g. 1.1) to deprecate a term, triggering validation warnings.

An integer/major version update would still be required to remove the term entirely, triggering validation errors if it was still included.

This is in line with the guidance in the Semantic Versioning document.

Engagement

Please indicate support or opposition for this proposal using the +1 / -1 buttons or a comment. If opposing the proposal, please give clear justifications, and where possible, make an alternative proposals.

[mireille-raad]

Team is discussing how renaming and removing fields actually impact country work... what is the workflow and communication that has to go with this... so we might get back to you with some questions on depreciation policy.

In the meantime, my immediate question is:
Will the validator for OCDS 1.0 stay online and another validator added? or there will be only one validator?

[timgdavies]

Thanks @DC-coder.

We will definitely need to have clear communication for any deprecations.

We will work to make the validator handle versioning. I've just updated #301 with the proposals around this.

[mireille-raad]

So here are some thoughts from the team.

General questions:

• Does data in existing countries need to be updated? (is it an optional best practice or required)
• When countries “want to be compliant with OCDS” – does that mean to latest version or can it be to different versions?
• If government has been using additional fields not included in OCDS, does that make the data non-compliant with validator?

Here are some case scenarios, how does the depreciation policy affect them?

Case 1:
A field is removed, but the government has been using it for analysis or they just think it is useful – does keeping the field break the validator? Will the data still be OCDS compliant?

Case 2:
A field is renamed, this would break the user interfaces that use it, is there any “backward compatibility” strategy? Or the only option is to update both schema and UI?

Case 3:
If the government decides to comply with half the field changes between 1.0 and 1.1, what happens?… for example, they agreed to rename their date or amount fields but refused to make any changes to how the organizations are created… where does this put us?

Thanks for taking the time to reply :)

[timgdavies]

Thanks @DC-coder for setting out these scenarios clearly. I'll try to respond to each point below from the perspective of a technical data specification - although these might be issues to discuss more widely with OCP.

Does data in existing countries need to be updated? (is it an optional best practice or required)

This is a policy decision for implementers. Ultimately, using the latest version of a technical standard is a good best-practice - but any required targets would come from policy advocacy - not from the technical specification itself.

When countries “want to be compliant with OCDS” – does that mean to latest version or can it be to different versions?

Using the language from our validation page both validation and conformance are assessed against a particular version of the standard.

We don't currently define 'compliant with OCDS' within the technical specification.

If government has been using additional fields not included in OCDS, does that make the data non-compliant with validator?

In version 1.0, additional fields are reported as such, by files pass the validator.

The behaviour of the validator for 1.1 is not yet set, but as we are introducing a field to explicitly declare extensions (#326), it could either:

1. Reject additional fields which are not explicitly covered by a declared extension
2. Permit additional fields as in version 1.0 validation

My preference would be to allow the user to choose between these by selecting 'strict' (1) validation, or 'permissive' (2) validation.

To address the cases:

Case 1
A field is removed, but the government has been using it for analysis or they just think it is useful – does keeping the field break the validator? Will the data still be OCDS compliant?

Fields will only be deprecated in 1.1, not removed.

The validator will report on deprecated fields (and should point to the replacement if it is down to a renaming etc.).

If the publisher wants to keep using deprecated fields, and to validate in a strict validation mode, they should declare an extension which re-introduces the fields that have been removed from core.

(The reason to deprecate/remove fields from core is to help simplify the standard - but not to stop people publishing information they find useful. Our philosophy is to welcome additional data and extensions!)

Case 2: A field is renamed, this would break the user interfaces that use it, is there any “backward compatibility” strategy? Or the only option is to update both schema and UI?

Publishers could choose to convert data from 1.1 to 1.0 to keep a 1.0 interface functional - but we would encourage all publishers to update interfaces and tools to the new version of the standard.

We are aiming to minimise backwards incompatible changes.

Case 3:
If the government decides to comply with half the field changes between 1.0 and 1.1, what happens?… for example, they agreed to rename their date or amount fields but refused to make any changes to how the organizations are created… where does this put us?

In this case they risk not publishing to any recognised version of the standard. (It wouldn't really be a standard if you could entirely pick and mix which bits you use between versions!)

[timgdavies]

The deprecation policy was discussed on our OCDS community call today.

No comments or objections relating to the proposed change were raised.