Clarify reference on identifiers and registered prefixes

[JachymHercher]

From #1409

@JachymHercher:

I don't understand the following sentence in https://standard.open-contracting.org/staging/1.2-dev/en/schema/identifiers/#registered-prefixes "A prefix is assigned to each organization that holds the existing internal identifier for a Contracting Processes.". Prefixes are assigned to publishers, not buyers, no? How is that linked to whether an organization "holds" (i.e. knows? sets?) an "internal identifier" (why not a public one?)

@jpmckinney

Gosh that section is badly worded. https://standard.open-contracting.org/staging/1.2-dev/en/guidance/build/#register-an-ocid-prefix is where we refer to the prefix in the guidance. The only complexity around prefixes is deciding whether a given publisher can use the same prefix as another. There is some public discussion in #364 (comment). In short, other publishers need to coordinate with the original registrant if they want to use the same prefix.

Let's reformulate. (We might want to wait for clarifications on purpose of the the whole page in #1523 though.)

[duncandewhurst]

We might want to wait for clarifications on purpose of the the whole page in #1523 though.

Is there anything left to clarify? Looks like the discussion in #1523 was mostly about the need for https://standard.open-contracting.org/staging/1.2-dev/en/schema/reference

[jpmckinney]

The sentence "A prefix is assigned to each organization that holds the existing internal identifier for a Contracting Processes" still occurs, and should be rewritten.

In general, that subsection can be redrafted to present information in a better order. For example, https://standard.open-contracting.org/latest/en/guidance/build/#register-an-ocid-prefix first reintroduces the familiar ocid concept, its relationship to the publisher, the function of the prefix, and finally the need to register a prefix. We can move the note about only OCP issuing prefixes into an admonition. We can then discuss the format and the lack of semantics.

When we do #364, we can append content about how to coordinate use of a same prefix.

[duncandewhurst]

I agree that the content of the page can be clarified. I was checking if there was some meta-clarification of the purpose of the page that still needed to happen in #1523 as suggested in the issue description, but I guess not, so your suggested actions all sound good!

[jpmckinney]

I'm not sure that we need to do part 1 of #1523, but we can check as part of that issue.

[duncandewhurst]

@jpmckinney - let me know what you think of the revised content below. Happy to prepare a PR if that would be easier to review. I've omitted the worked example as that is being revised in #1595

Open contracting process identifier (ocid)

An open contracting process identifier (ocid) is a globally unique identifier for a contracting process. Every contracting process in OCDS is assigned an ocid.

The contracting process to which an OCDS release or record relates is identified by the ocid field. Therefore, a contracting process's ocid be used to join up data that is published at different times or from different systems.

A release's ocid field is described as:

A record's ocid field is described as:

An ocid is composed of two parts:

1. An ocid prefix that establishes an identifier series, for which there is one publisher with the authority to mint ocids
2. An internal contracting process identifier that is unique within the scope of the identifier series

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 (-).

Before assigning an ocid to a contracting process, you need to register an ocid prefix and decide on a suitable internal contracting process identifier. You might need to consider changes to existing systems to ensure that different systems handling information about your contracting and planning processes share a common internal contracting process identifier.

ocid prefix

The purpose of the ocid prefix is to ensure that each ocid is globally unique. To ensure that your ocids do not conflict with those of another publisher, you must register an ocid prefix.

An ocid prefix is made up of two parts:

1. A prefix agency identifier that establishes a prefix series, for which there is one agency with the authority to mint prefixes
2. A randomly generated six character lowercase alphanumeric string

:class: hint

Currently, only the Open Contracting Partnership can mint ocid prefixes, under the 'ocds' prefix agency identifier. In the future, other organizations might be able to issue prefixes, each with their own prefix agency identifiers.

ocid 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.

All registered OCID prefixes are accessible as a web page or CSV file.

[jpmckinney]

I started making suggestions, but it became faster to edit directly. My motivations:

• Reduce repetition (e.g. between paragraphs and field description)
• Tell the reader the difference between the two descriptions (it's only one word)
• Describe the authority to create ocids as a paragraph, rather than in a clause in the description of the format
• Expand the section on internal identifiers

OCDS defines a release's `ocid` field as:

```{field-description} ../../build/current_lang/release-schema.json /properties/ocid
```

(The definition of a record's `ocid` field replaces "release" with "record".)

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.

An `ocid` is composed of two parts:

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

It is encouraged to separate the OCID prefix and the internal identifier with a hyphen (`-`).

The `ocid` is case-sensitive; in other words, the letter case of an ocid must be consistent.

To assign an `ocid` to a contracting (or planning) process, you need to register an OCID prefix and choose an internal identifier.

### OCID prefix

The only purpose of the OCID prefix is to turn *locally* unique identifiers into *globally* unique identifiers, without coordination between publishers.

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).

Only the publisher that registered an OCID prefix is authorized to assign new `ocid`s with that OCID prefix, or to delegate this responsibility.

```{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).
```

An *OCID prefix* is composed of two parts, separated by a hyphen (`-`):

1. The identifier of the issuer of the OCID prefix
2. Six randomly generated lowercase alphanumeric characters

OCID prefixes have no meaning, deliberately (they are "dumb" identifiers).

```{admonition} Who can issue OCID prefixes?
:class: hint

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.
```

### Internal identifier

You must choose a single, unique internal identifier for each contracting (or planning) process.

If such an identifier doesn't already exist, you need to develop a method to create one. You might need to:

* 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

[jpmckinney]

I'm not sure about the "you" language, but it was there before. We can change to "a publisher", etc. I forget whether we use "you" elsewhere in the Reference section.

[duncandewhurst]

Your updates look good to me. I'll check on the usage of "you" in the reference section and prepare a PR.

[duncandewhurst]

"you" language appears on codelists.md, conformance_and_extensions.md and merging.md so I haven't changed it.