Update identifier reference

docs/guidance/build.md

@@ -28,10 +28,6 @@ To ensure that your `ocid`s do not conflict with those of another publisher, you
 
 **Resource**: To learn more about the `ocid` and its prefixes, refer to the [identifiers](../../schema/identifiers) reference.
 
-```{note}
-All registered OCID prefixes are accessible as a [web page](https://docs.google.com/spreadsheets/d/1E5ZVhc8VhGOakCq4GegvkyFYT974QQb-sSjvOfaxH7s/pubhtml?gid=506986894&single=true&widget=true) or [CSV file](https://docs.google.com/spreadsheets/d/e/2PACX-1vQP8EwbUhsfxN7Fx7vX3mTA6Y8CXyGi04bHUepdcfxvM6VRVP9f5BWAYEG6MPbnJjWJp-La81DgG8wx/pub?gid=506986894&single=true&output=csv).
-```
-
 ## Determine your system architecture
 
 There are many ways to extract data from data sources, combine it, map it to OCDS, and publish it. The [system architectures](build/system_architectures) guidance page describes some possible approaches.

docs/guidance/map/organization_identifiers.md

@@ -26,7 +26,7 @@ The publisher collects an additional identifier, which is disclosed using the `a
 
 ## Local IDs
 
-Each of the organizations in the [parties section](../../schema/reference.md#parties) ought to have a [local ID](../../schema/identifiers.md#local-identifiers) (`id`), which is used to reference the organization from elsewhere in the data.
+Each of the organizations in the [parties section](../../schema/reference.md#parties) ought to have a [local ID](../../schema/identifiers.md#local-organization-ids) (`id`), which is used to reference the organization from elsewhere in the data.
 
 For organizations with an organization identifier, you ought to construct the local `id` following the pattern `{identifier.scheme}-{identifier.id}`.
 

docs/history/changelog.md

@@ -286,6 +286,7 @@ Per the [normative and non-normative content and changes policy](../governance/n
 * [#1618](https://github.com/open-contracting/standard/pull/1618) Remove validator and application conformance rules.
 * [#1618](https://github.com/open-contracting/standard/pull/1618) Move governance policies from Google Docs, updating references for OCDS 1.1.5 and OCDS 1.2.0, and removing references to GitHub issues.
 * [#1643](https://github.com/open-contracting/standard/pull/1643) Update identifier section in release reference.
+* [#1655](https://github.com/open-contracting/standard/pull/1655) Rewrite identifiers reference and examples.
 
 ## [1.1.5] - 2020-08-20
 

docs/schema/identifiers.md

@@ -6,105 +6,107 @@ Consistent identifiers are essential to help join up open contracting data.
 * Organization identifiers are important to know who is involved in each contract;
 * Release, award and contract identifiers are important to help cross-reference information.
 
-## Types of identifiers
-
-In OCDS there are two kinds of identifiers: globally unique and local.
-
-### Globally unique identifiers
-
-Across the whole universe of OCDS publishers these identifiers refer to one specific process or organization.
-
-We create globally unique process identifiers by adding a prefix to the internal identifiers held by publishers.
-
-```{admonition} Worked Example
-:class: hint
+## Open contracting process identifier (ocid)
 
-Two government publishers (Town A and Town B) number their contracting processes from 0 upwards.
+<img src="../../_static/svg/green_compilation.svg" width="150" align="right"/>
 
-Town A publishes information on a contracting process to build a new road. Internally they know this as contract 0005.
+OCDS defines a release's `ocid` field as:
 
-Town B publishes information on a contracting process to buy textbooks for a school. Internally they also know this as contract 0005.
+```{field-description} ../../build/current_lang/release-schema.json /properties/ocid
+```
 
-When they publish their OCDS data, each government adds a unique prefix onto their internal identifiers.
+(The definition of a record's `ocid` field replaces "release" with "record".)
 
-Now Town A's contracting process has the `ocid` of 'ocds-fh349f-0005' and Town B's contracting process has the `ocid` of 'ocds-twb234-0005'.
+Since the `ocid` field is a required field and is globally unique, it can be used to join up data that is published at different times or from different systems.
 
-There is now no chance of these getting mixed up in a system which imports data from both towns.
+An `ocid` is composed of two parts:
 
-And, if an independent civil society contract monitoring group want to publish a report about implementation of Town A's road project, or Town B's text-book procurement, they have distinct identifiers they can use in their own data to refer to these.
-```
+1. An [OCID prefix](#ocid-prefix), which identifies the series of identifiers to which the `ocid` belongs
+1. An internal identifier for the contracting (or planning) process, which is unique within the series
 
-You can read more about the OCDS approach to identify organizations below.
+It is encouraged to separate the OCID prefix and the internal identifier with a hyphen (`-`).
 
-### Local identifiers
+The `ocid` is case-sensitive; in other words, the letter case of an ocid must be consistent.
 
-Not all the identifiers in OCDS need to be globally unique. Most only need to be unique among the identifiers used for the same type of object within the same scope. For example:
+To assign an `ocid` to a contracting (or planning) process, you need to register an OCID prefix and choose an internal identifier.
 
-* A release ID must be unique within the scope of the process of which it is a part;
-* Award and contract identifiers must be unique within the scope of the process of which they are a part;
-* An item, milestone or document ID must be unique within the array it is part of.
+````{admonition} Worked Example
+:class: hint
 
-Local identifiers must be used consistently. For example, if the `id` of an award is "22" in one release, then the `id` of the same award in another release must also be "22".
+Two publishers, the UK Atomic Energy Authority and Health Canada, use sequential numbers as internal identifiers for their contracting processes.
 
-## Open contracting process identifier (ocid)
+The UK Atomic Energy Authority initiates a contracting process to purchase productivity software and assigns it the internal identifier '0005'. Health Canada initiates a contracting process to purchase office furniture and also assigns it the internal identifier '0005'.
 
-<img src="../../_static/svg/green_compilation.svg" width="150" align="right"/>
+To create a globally unique `ocid`, each publisher prepends their internal identifier with their OCID prefix: 'ocds-fh349f' for the UK Atomic Energy Authority and 'ocds-twb234 for Health Canada.
 
-An open contracting process identifier (ocid) is a **globally unique identifier**. Every release has an `ocid`. OCDS defines an `ocid` as:
+The UK Atomic Energy Authority assigns the `ocid` 'ocds-fh349f-0005'.
 
-```{field-description} ../../build/current_lang/release-schema.json /properties/ocid
+```json
+{
+ "ocid": "ocds-fh349f-0005",
+ "publisher": {
+ "name": "UK Atomic Energy Authority"
+ },
+ "tender": {
+ "id": "0005",
+ "title": "Productivity software"
+ }
+}
 ```
 
-It can be used to join up information published at different times and in different places.
-
-Setting the `ocid` is usually a simple two step process:
-
-1. Identify the best **internal identifier** recorded against the processes being disclosed;
-2. Register an `ocid` prefix to prepend to this internal identifier.
+Health Canada assigns the `ocid` 'ocds-twb234-0005'.
 
-In some cases, you might need to consider changes to existing systems to ensure that different systems handling information about your contracting and planning processes have a common internal identifier to draw upon.
-
-```{admonition} Worked Example
-:class: hint
+```json
+{
+ "ocid": "ocds-twb234-0005",
+ "publisher": {
+ "name": "Health Canada"
+ },
+ "tender": {
+ "id": "0005",
+ "title": "Office furniture"
+ }
+}
+```
 
-In Mexico City, each time a tender or direct contract award process is initiated, the department responsible assigns an identifier.
+As a result, users and tools that work with data from both publishers are less likely to confuse the two contracting processes. If another publisher, such as an independent monitor, wants to publish more data about one of the contracting processes, they can reference it using its unique `ocid`.
 
-These are made up of an identifier for the department responsible for the procurement, a tender number, and the year.
+````
 
-For example:
+### OCID prefix
 
-> OM-DGRMSG-004-13
+The only purpose of the OCID prefix is to turn *locally* unique identifiers into *globally* unique identifiers, without coordination between publishers.
 
-This internal identifier can be exchanged with, and recorded in, any other systems which process information about this contracting process. For example, systems for reporting or recording spending transactions to suppliers.
+To ensure that your `ocid`s do not conflict with those of another publisher, you must [register an OCID prefix](../guidance/build.md#register-an-ocid-prefix).
 
-Mexico City then registered a prefix with the Data Support Team. They have been given the prefix ‘ocds-87sd3t’ which can be added to their unique process identifiers to give a globally unique `ocid`. E.g.
+Only the publisher that registered an OCID prefix is authorized to assign new `ocid`s with that OCID prefix, or to delegate this responsibility.
 
-> ocds-87sd3t-OM-DGRMSG-004-13
+```{note}
+All registered OCID prefixes are accessible as a [web page](https://docs.google.com/spreadsheets/d/1E5ZVhc8VhGOakCq4GegvkyFYT974QQb-sSjvOfaxH7s/pubhtml?gid=506986894&single=true&widget=true) or [CSV file](https://docs.google.com/spreadsheets/d/e/2PACX-1vQP8EwbUhsfxN7Fx7vX3mTA6Y8CXyGi04bHUepdcfxvM6VRVP9f5BWAYEG6MPbnJjWJp-La81DgG8wx/pub?gid=506986894&single=true&output=csv).
 ```
 
-The ocid prefix itself is made up of two parts: a prefix agency identifier (currently only 'ocds' is used), and a random six-character alphanumeric string generated for each publisher of data.
-
-The ocid is case-sensitive; in other words, the letter case of an ocid must be consistent.
-
-It is encouraged to separate the ocds prefix and the internal identifier with a hyphen (`-`).
-
-### Registered prefixes
+An *OCID prefix* is composed of two parts, separated by a hyphen (`-`):
 
-Publishers must register an ocid prefix. See the [registration pages](../guidance/build) for details of how to obtain your ocid prefix.
+1. The identifier of the issuer of the OCID prefix
+2. Six randomly generated lowercase alphanumeric characters
 
-Prefix are randomly generated lowercase alphanumeric strings. A prefix is assigned to each organization that holds the existing internal identifier for a Contracting Processes.
+OCID prefixes have no meaning, deliberately (they are "dumb" identifiers).
 
-Currently, only the Open Contracting Partnership issues valid prefixes. In future, other organizations might be able to issue prefixes, each with their own prefix agency identifiers.
+```{admonition} Who can issue OCID prefixes?
+:class: hint
 
-You can find a [list of registered prefixes here along with a registration form for creating new prefixes](../guidance/build).
+Currently, only the [Open Contracting Partnership](https://www.open-contracting.org) can issue OCID prefixes, with the `ocds` issuer identifier. In the future, other organizations might be able to issue OCID prefixes, with their own issuer identifier.
+```
 
-The registered prefixes are dumb identifiers. They are not intended to carry any semantics, and their sole purpose is to turn internal identifiers into globally unique identifiers which can be cross-referenced between systems.
+### Internal identifier
 
-### Publisher namespace
+You must choose a single, unique internal identifier for each contracting (or planning) process.
 
-Earlier versions of this documentation imposed a stricter pattern on how internal identifiers ought to be combined with the ocid prefix, including a requirement for local namespaces. This requirement has been relaxed in practice and can be considered deprecated.
+If such an identifier doesn't already exist, you need to develop a method to create one. You might need to:
 
-However, publishers are encouraged to consider whether there are any risks of clashes in local identifiers (e.g. the possibility that two parts of the publishing body might use the same identifier for different contracting or planning processes) and to plan to mitigate this when establishing their own patterns to generate their `ocid`
+* Reconcile different identifiers across different systems (for example, across tender management and contract management)
+* Concatenate non-unique values to construct a unique identifier (for example, the year, the buyer, and a sequential number)
+* Change existing systems to use a common, unique identifier
 
 ## Organization identifiers
 
@@ -119,23 +121,29 @@ There are two parts to expressing an **organization identifier** in open contrac
 * A prefix for the organization list (also known as registry or register) from which the identifier is drawn: for example, a company register.
 * The existing identifier for the organization within that list.
 
+In OCDS, the list's prefix is disclosed via the `scheme` field of an identifier object, with the existing identifier in the `id` field. If there is a recognized public URL that uniquely identifies the organization, this can be disclosed via the `uri` field.
+
 ````{admonition} Worked Example
 :class: hint
 
-The prefix for the UK's Companies House is "GB-COH". The organization Development Initiatives has been assigned the company number ‘06368740’ by Companies House. The globally unique organization identifier for Development Initiatives can be expressed as below:
+Companies in the UK are assigned identifiers by [Companies House](https://www.gov.uk/government/organisations/companies-house). MICROSOFT LIMITED's identifier is '01624297' and the prefix for Companies House is "GB-COH". Therefore, MICROSOFT LIMITED's organization identifier can be expressed as follows:
 
 ```json
 {
- "scheme": "GB-COH",
- "id": "06368740",
- "uri": "http://data.companieshouse.gov.uk/doc/company/06368740",
- "legalName": "Development Initiatives Poverty Research Limited"
+ "parties": [
+ {
+ "identifier": {
+ "scheme": "GB-COH",
+ "id": "01624297",
+ "legalName": "MICROSOFT LIMITED",
+ "uri": "http://data.companieshouse.gov.uk/doc/company/01624297"
+ } 
+ }
+ ]
 }
 ```
 ````
 
-In OCDS, the list's prefix is disclosed via the `scheme` field of an identifier object, with the existing identifier in the `id` field. If there is a recognized public URL that uniquely identifies the organization (like in the above example), this can be disclosed via the `uri` field.
-
 ### Organization lists
 
 There are many kinds of organization lists: