Make JSON examples minimal

[duncandewhurst]

Following on from the discussion started in #1661 (comment):

To ease comprehension, we should have minimal (but coherent) examples. That is, the JSON files in docs/examples should contain only the fields needed to illustrate the specific documentation pages that they feature in. Minimal examples are also easier to maintain, for example, to reflect a schema change.

The purpose of this issue differs from the purpose of #1449, which is to avoid examples that are incoherent, or that are too abstract (e.g. Anytown buys widgets).

I'll review the examples to identify those whose clarity would be improved by removing fields. I'll do that after #1661 is done to avoid any duplication of effort.

[duncandewhurst]

Moving relevant comments from #1449:

@duncandewhurst in #1449 (comment):

@jpmckinney to check that we are on the same page when it comes to making examples minimal, please could you review the changes I've made to the tender updates and amendments example (original, minimal version).

In addition to the changes proposed in my previous update, since the notes which previously appeared at the end of the example each relate to a single JSON snippet, I integrated them into the paragraphs introducing each snippet.

@jpmckinney in #1449 (comment):

Looks good! It would be nice to be able to emphasize the lines that changed. I opened OpenDataServices/sphinxcontrib-opendataservices#47

I think to go along with #1639 there are a few places where we would replace "tender" with "opportunity" (mainly where tender isn't followed by a word like "release" or "update release"). Or rewording like:

The buyer adds a main procurement category to the tender

The buyer now indicates the opportunity's main procurement category.

[duncandewhurst]

@jpmckinney I've made your suggested changes.

Regarding the second example on that page, it feels unnecessary to me. Given that the purpose of the page is to explain the differences in modelling new information, updates, and amendments, I think it would be sufficient to add a sentence at the end of the first example along the lines of:

Contract updates and amendments are modelled in the same way: the 'contract', 'contractUpdate' and 'contractAmendment' release tags distinguish the type of change and contract amendments are listed in the contract.amendments field.

Regarding the third example on that page, we can decide what to do with it as a part of #1531 (which removes the easy releases terminology).

[jpmckinney]

Yes, happy to remove the 2nd example. We can put the new sentence in an admonition titled "Contract updates and amendments"

[duncandewhurst]

Noting that as part of going through all the examples for this issue, I think it'll be useful to use a consistent approach to setting ocid and id. I suggest the following:

• ocid: Set to 'ocds-213czf-0000' for the first contracting process in each subfolder of examples. If there's more than one contracting process in the subfolder, set the ocid of the subsequent processes to 'ocds-213czf-0001', 'ocds-213czf-0002' etc.
• id: Set incrementally within the scope of the contracting process the release relates to, e.g. '1', '2' etc.

[jpmckinney]

Sounds good to me re: ocid and id.

[duncandewhurst]

I reviewed the examples not already touched by #1680, #1661 and #1531. The following examples would be improved by removing fields. I'll check these off as I work through them:

• Unsuccessful processes (see suggestions below)
• Framework agreements
• Processes with pre-qualification and pre-selection
• Contract suspension (Removed in release-schema: Add finalStatus to tender, award and contract. Clarify tender.datePublished. #1648)
• Organization identifiers
• Personal identifiers
• Organizational units (Done apart from second example, see question below)
• Organization classifications
• Beneficial ownership information

I also noticed a couple of other opportunities for improvements and fixes:

Unsuccessful processes

I think this example is trying to do too much: it illustrates linking planning and contracting processes, linking unsuccessful and restarted processes, and how to assign different ocids to unsuccessful and restarted process when they share an identifier in a publisher's system.

Suggested actions:

• Move the content and example related to linking planning and contracting processes to contracting and planning processes
• Draft a minimal example to illustrate how to link unsuccessful and restarted processes in the common case where they are treated as separate contracting processes in the publisher's system
• Address the Paraguay case (shared identifiers) in an admonition, e.g.

Unsuccessful and restarted processes with a shared identifier
In some jurisdictions, such as Paraguay, if a first attempt is unsuccessful in procuring items, the second attempt is considered to be part of the same contracting process and shares the same identifier. However, in OCDS, the two attempts need to be modelled as separate contracting processes with different ocids. To create an ocid for the second process in the absence of a unique identifier in your data sources, you can append an incrementing number to the ocid of the first process, e.g. {first process ocid}-1.

Framework agreements

Whilst updating the examples, I noticed a couple of conflicts with guidance:

tender.procurementMethod

The guidance states:

[set] tender.procurementMethod according to the competitive conditions of the first stage of the framework agreement. Since framework agreements typically involve qualification, this is most often 'selective'.

However, both examples have the following:

Since any supplier is able to submit a response to the invitation to participate, tender.procurementMethod is set to 'selective'.

In both cases, I've updated it to match the guidance:

Only qualified suppliers can respond to the invitation so tender.procurementMethod is set to 'selective'

award.suppliers

The guidance states:

A single award notice can be used to disclose many award decisions; however [...] such notices ought to be split into multiple awards in OCDS.

However, the second example has a single award with two suppliers (not in a consortia).

I've updated the example to split the award into two, one for each supplier.

[duncandewhurst]

Organizational units

I don't understand why an extension is needed in the second example. Couldn't the division code be disclosed in .additionalIdentifiers?

[jpmckinney]

In both cases, I've updated it to match the guidance:

Only qualified suppliers can respond to the invitation so tender.procurementMethod is set to 'selective'

Hmm, I think any supplier can indeed request to participate, but only qualified suppliers will then be able to submit a bid .

I don't understand why an extension is needed in the second example. Couldn't the division code be disclosed in .additionalIdentifiers?

You're right. It's not needed. This was clarified in #1510 Maybe we do something like https://github.com/sdd1982/branch which indicates the branch of government (executive, legislative, judicial).

[jpmckinney]

The other suggestions look good!