What should deprecation look like in the schema.

[kindly]

This is related to #367 but this more how to technically mark parts of the JSON schema as deprecated.

We need to consider how the validator reports these warnings.

A simple boolean field "deprecated" could be added to any JSON Schema field description, however this may not provide enough information to both the future schema maintainers and the user who has used a deprecated property.
I would recommend something like discussed here but with a deprecatedVersion key instead. So we make a deprecated object with a description and deprecatedVersion keys.

i.e say we are deprecating initiation type

{
   "initiationType": {
   "title": "Initiation type",
   "description": "...",
   "type": "string",
   "enum": ["tender"],
   "deprecated" : {
       "deprecatedVersion" : "1.1",
       "description" : "Not a useful field as always has to be tender, perhaps you need an extension instead"
   }
}

Deprecated version is useful as it tells the user and the schema maintainers when it was deprecated, so that it will be easier to remember to remove it at some point.
Description will be good for feedback in the validator and can also provide alternatives, or suggestions on what the best approach is now.
Having it as an object also means some future proofing if we want to add more structured information as to why the deprecation has happened.

[timgdavies]

Sorry for delay in reviewing this. This looks like a good approach.

The one other thing we might have to consider is how to deprecate codelist entries.

[timgdavies]

I've just been working on the parties extension - and wanted to check at what level deprecation needs to be applied.

Essentially:

• We are replacing the detailed Organization block with an OrganizationReference block at most point in the schema.
• The property names (buyer, supplier etc. stay the same, but just now reference a different block of schema)
• Publishers of 1.0 data are likely to have addresses, contact points etc. in these objects, but that behaviour is now deprecated

In the schema merge patch here I've included the properties that were in Organization in OrganizationReference but have marked them as deprecated. I've done this just at the top-level for the array of additional identifiers, and the address and contactPoint objects (which are actually $refs - so this is, strictly, against JSON Schema).

Is this the correct way to do this? How will CoVE report this deprecation?

[Bjwebb]

Currently CoVE doesn't handle this.

We use jsonref. It looks like it would be fairly straightfoward to get at this info - http://jsonref.readthedocs.io/en/latest/#jsonref.JsonRef.__reference__

[timgdavies]

@Bjwebb Could you add handling this to the next CoVE sprint?

[robredpath]

I've added this @timgdavies and we can discuss details when we speak later

[duncandewhurst]

In the current version of the schema viewer, deprecation is only visible where the description of the deprecated field has been updated, e.g. you can't see that organizationReference/identifier has been deprecated even though it has the deprecated property in the schema:

[Bjwebb]

CoVE now supports the deprecation key on the referencing object.

For the schema viewer, it seems we have two options:

• Update the descriptions of all deprecated fields to state they're deprecated. (This could also be useful for other users of the schema whose tools don't support our custom deprecated key).
• Update the schema viewer javascript to do something with our custom javascript key.

[duncandewhurst]

I think we should do both, since the updated descriptions don't 'leap out' in the schema viewer.

[timgdavies]

The deprecation policy has been updated and included in the validator.

We'll continue to work on documentation improvement for the display of deprecation information.