Add links field

[jpmckinney]

Issue

A government might only publish OCDS data for new events in a contracting process. However, they would still want to have a link back to any earlier events (in non-OCDS format).

This might occur in cases of jurisdictional changes, like municipal mergers or EU withdrawal, where the cost and complexity of converting old events might be too high.

Proposal

Add a top-level field, similar to relatedProcesses, named links, e.g.:

{
  "properties": {
    "links": {
      "title": "",
      "description": "",
      "type": "array",
      "items": {
        "$ref": "#/definitions/Link",
      }
    }
  },
  "definitions": {
    "Link": {
      "title": "",
      "description": "",
      "type": "object",
      "properties": {
        "same fields as RelatedProcess, except `title`"
      }
    }
  }
}

The relationship field would have a different codelist than relatedProcess.csv, with codes for:

• prev, Previous publication, The linked resource is a previous publication about this contracting process, that is not in OCDS format or is using a different OCID. This code is intended for use when transitioning from an old system without converting its data, which might occur in cases of jurisdictional changes like municipal mergers.

We can propose other codes like:

• alternate, Alternate representation, The linked resource is an alternate representation of this contracting process. For example: a local XML format.

There probably aren't any others we want to include at first, but we can be inspired by https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types

The codes should all make sense in the context of a contracting process, not in the context of the individual release. If the field were used in the context of an individual release, then we'd have to make the field "omitWhenMerged": true. In most cases, a documents field can be used to make links to external resources related to an individual release.

[jpmckinney]

We should also look into merging in https://github.com/open-contracting-extensions/ocds_pagination_extension.

[jpmckinney]

Rather than re-using RelatedProcess, we should use JSON Hyper-Schema, e.g.:

{
  "links": [
    {
      "rel": "self",
      "href": "https//..."
    }
  ]
}

[portaledcahn]

Hello,

We need to use this extension for the issue 1228, an initial version in the repository that can be found at here: https://github.com/portaledcahn/ocds_Links_extension

Please feel free to comment.

Greetings

[jpmckinney]

The codes should all make sense in the context of a contracting process, not in the context of the individual release. If the field were used in the context of an individual release, then we'd have to make the field "omitWhenMerged": true. In most cases, a documents field can be used to make links to external resources related to an individual release.

More recently, we've been discussing the use case of one publication's release referring to another publication's release as canonical. This can be achieved with links, using "rel": "canonical". However, in this case, the link would be in the context of a release, not a contracting process. Also, merging all the canonical links in a compiled release would not make sense; if a compiled release has a canonical link, to respect the semantics of "canonical", it would need to point to another compiled release, not to multiple individual releases. As such, it might indeed make sense to set "omitWhenMerged": true, and to allow (in terms of semantics) links to work both in the context of individual releases and contracting processes. For example, if the previous system only has data representations for the entire process, then it should be allowed to use "rel": "prev" to refer to that contracting process.

[duncandewhurst]

Reopening because we forgot to add the Link object to the building block reference

[duncandewhurst]

Reopening again because we forgot to add LinkRelationType.csv to the codelist reference.

Ignore me, I was looking at the wrong version of the docs.

[yolile]

#1326 says

"Links to related resources. In a release, links relate to the individual release: for example, a link to a canonical version of the release in another OCDS publication. In a compiled release, links relate to the entire contracting process: for example, a link to a resource in a non-OCDS publication that represents the entire contracting process."

And

"Alternate: Refers to a substitute or alternative representation of a release or compiled release."

If a publisher is publishing releases only and wants to publish an alternate link to the contracting process, how should they publish this? Still with links, with rel: "alternate" in a release? Even though the link content will change over time?

Context: Dominican Republic wants to publish this type of link https://comunidad.comprasdominicana.gob.do//Public/Tendering/OpportunityDetail/Index?noticeUID=DO1.NTC.1031532 that contains the entire contracting process info in HTML format.

[jpmckinney]

I think that link can be modelled in documents?

The use case for links is fairly narrow (see issue description).

[yolile]

Do you mean documents at the top level?

As per #1228 (comment)

In #928, the idea would be that the linked document is an alternative representation of the entire procedure.
If that is not the correct semantics, then there should instead be a new top-level documents array.

But in this case, this link represents indeed an alternative representation (HTML) of the entire procedure.

[jpmckinney]

I would just link it in tender/documents.

The use case is more than just for alternative representations, but for alternative representations in cases where there is no OCDS data to link to (e.g. when the UK was transitioning from TED to OCDS).

documents is already used for alternative representations (e.g. the PDF or HTML version of an award, contract, etc.). #1228 already has a good reason for not introducing a top-level documents array. It's not so bad to put this in tender.