From 7439d1d463b8ef99483c0a9c150c1cca00d1342b Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Sun, 24 Mar 2024 23:57:29 -0400 Subject: [PATCH] guidance/map/connecting_publications: Copy-edit. Clarify heading. --- docs/guidance/map/connecting_publications.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/guidance/map/connecting_publications.md b/docs/guidance/map/connecting_publications.md index f503aabef..bb7178ce3 100644 --- a/docs/guidance/map/connecting_publications.md +++ b/docs/guidance/map/connecting_publications.md @@ -4,19 +4,19 @@ # Connecting releases from different publications -Different OCDS publications can contain releases describing the same contracting (or planning) process. In OCDS, each contracting (or planning) process is assigned a globally unique identifier, the [OCID](../../schema/identifiers.md#open-contracting-process-identifier-ocid). +Different publications can contain releases describing the same contracting (or planning) process. In OCDS, each contracting (or planning) process is assigned a globally unique identifier, the [OCID](../../schema/identifiers.md#open-contracting-process-identifier-ocid). Ideally, releases describing the same contracting (or planning) process in different publications would reuse the same OCID so that users can [merge releases](../../schema/merging.md). However, problems can occur. This page describes: the scenarios in which OCIDs can be reused, or not, across publications; how to connect releases from different publications without reusing OCIDs; and, in two scenarios, how to reuse OCIDs across publications. -The examples on this page are based on the Public Contracts Scotland (PCS) publication and the UK's Find a Tender Service (FTS) publication, both of which include releases about the same contracting (or planning) processes, covering the same contracting (or planning) process stages and having many fields in common. +The examples on this page are based on the Public Contracts Scotland (PCS) and Find a Tender Service (FTS) publications, which include releases about the same contracting (or planning) processes, covering the same contracting process stages and having many fields in common. ## Problems with reusing OCIDs across publications Unless publications have disjoint coverage of OCDS fields or implement a consistent mapping from source systems, then reusing OCIDs across publications can result in unpredictable and nonsensical results when releases are merged to create a compiled release. For example, unless publications use an identical approach to assigning local [identifiers](../../schema/identifiers.md) to objects in arrays, then awards, contracts and other [objects in arrays](../../schema/merging.md#array-values) can overwrite and/or duplicate each other in nonsensical ways. -### Example: Reusing OCIDs across Public Contracts Scotland and Find a Tender Service +### Example: Problems with reusing OCIDs across Public Contracts Scotland and Find a Tender Service The PCS and FTS publications have many overlapping fields, and implement slightly different mappings. For example, the publications implement inconsistent mappings for the `.id` of the buyer in the `.parties` array. As such, merging releases would result in duplicate buyers: @@ -104,7 +104,7 @@ The PCS and FTS publications have many overlapping fields, and implement slightl If publications have overlapping fields and inconsistent mappings, then you ought to use [links](../../schema/reference.md#link) to connect releases across the publications. -If, like FTS, a publication's releases *are derived from* another publication's releases, the derivative publication ought to use the 'canonical' [link relation type](../../schema/codelists.md#link-relation-type) to refer to the other publication's releases. If a publication's releases *follow* another publication's data, the subsequent publication ought to use the 'prev' link relation type to refer to the earlier data in the other publication. +If, like FTS, a publication's releases *are derived from* another publication's releases, the *derivative* publication ought to use the 'canonical' [link relation type](../../schema/codelists.md#link-relation-type) to refer to the other publication's releases. If a publication's releases *follow* another publication's data, the *subsequent* publication ought to use the 'prev' link relation type to refer to the earlier data in the other publication. ```{note} The 'prev' link relation type can also be used to refer to contracting data in a pre-existing, non-OCDS format. This might be relevant when transitioning from a system that will be retired and whose data will not be converted to OCDS. @@ -176,10 +176,10 @@ There are two scenarios in which reusing OCIDs across publications might be poss ### Publications with distinct coverage ```{note} -This scenario is unlikely to occur since most publications are likely to include some common fields, for example, the `parties` array. In this case, to avoid the risk of clashing identifiers, publishers would need to implement consistent mappings. For more information, see the next section, [publications with consistent OCDS mappings](#publications-with-consistent-ocds-mappings). +This scenario is unlikely to occur since most publications are likely to include some common fields: for example, the `parties` array. In this case, to avoid the risk of clashing identifiers, publishers would need to implement consistent mappings. For more information, see the next section, [publications with consistent OCDS mappings](#publications-with-consistent-ocds-mappings). ``` -If two publications cover disjoint sets of OCDS fields, with the exception of the release-level required fields (`ocid`, `id`, `date` and `tag`), then the publications can reuse OCIDs so that users can merge releases. +If two publications cover disjoint sets of OCDS fields, with the exception of the release-level required fields (`ocid`, `id`, `date` and `tag`), then the publications can reuse OCIDs. Building on the PCS and FTS example above, if PCS were to publish only the `parties` array and `tender` object and FTS were to publish only the `awards` array, then it would be possible for FTS to reuse the OCIDs assigned by PCS: @@ -279,12 +279,12 @@ Building on the PCS and FTS example above, if PCS were to publish only the `part ### Publications with consistent OCDS mappings -If two publications implement consistent mappings, in particular the approach to assigning local identifiers to objects in arrays, then the publications can reuse OCIDs so that users can merge releases. +If two publications implement consistent mappings – in particular, the approach to assigning local identifiers to objects in arrays – then the publications can reuse OCIDs so that users can merge releases. -As in the distinct coverage example, the publishers would need to agree on and implement the governance and technical aspects of assigning and sharing OCIDs. They would also need to: +As in the distinct coverage example, the publishers would need to agree on and implement the governance and technical aspects of assigning and sharing OCIDs. They would **also** need to: * agree on and implement consistent mappings for shared fields -* agree on and implement an integration of the systems (for example: whether a given system's data takes precedence over another's, the order of precedence, the direction in which the data flows, etc.) +* agree on and implement an integration of their systems (for example: whether one system's data takes precedence over another's, the direction in which the data flows, etc.) Given these governance and technical challenges, this scenario is unlikely to occur.