Reorder fields so that they follow a consistent logic

[JachymHercher]

(This issue is similar to #1349, but while #1349 deals with consistency across stages, this one deals rather with the general ordering logic and it's relationship with procurement practice.)

Logically ordering fields should make working with a standard easier (both because it should be more intuitive and because it should be more aligned with other systems and templates OCDS users use). However, the problem is that there are so many logical ways of ordering fields to chose from. For example:

• Importance
• Subject (e.g. "information about items", "information about the process")
• Order of procurement steps (e.g. selection criteria before award criteria)
• Data type (e.g. all deadlines next to each other).

Do we have a conscious approach in OCDS to how we order fields? If not, I can try to come up with something and propose changes in field ordering.

Examples of changes we could make in Tender:

• Move procurementMethod so that procurement categories (mainProcurementCategory and additionalProcurementCategory) are next to values (value, maximumValue, etc.) so that all the information more concerning the "items" is together.
• Reorder exclusionGrounds, selectionCriteria and awardCriteria so that they are next to each other and their order corresponds to the order in which they are evaluated.

[jpmckinney]

@JachymHercher Yes, it'd be great to have a documented convention for field ordering. We can discuss that here, and then add it to the handbook. This will likely be one of the "final" PRs – to avoid conflicts – but we can decide on the convention already.

[odscjen]

Having some ordering conventions is a great idea. I suspect that they will need to be a mixture of high level conventions (e.g. order fields according to the flow of the contracting processes) and some more specifics for fields or objects that don't fit into that.

Building from Jachym's initial suggestions I've taken a first stab at coming up with some ordering guidelines:

1. group by subject and then within those groupings order by steps, first the point in the process the data would be available then the point in the process the data applies, e.g. all the periods that go into Tender may be available when the tender notice is published, but the awardPeriod applies before the contractPeriod. And while the numberOfTenderers will be known before the contractPeriod begins, the actual value will not be known until the conclusion of the tender stage, while the contractPeriod will likely have been defined at the start.
2. group by "identifying info and metadata" then "info on process" then "info on items"
3. within a group/object always start with the identifying data (e.g. id, title etc)
4. if there's no difference in step order, order by increasing level of detail, e.g. id then title then description
5. always put additional information fields immediately after the field they're supplying additional info about
6. if there's no clear step or level of detail difference order alphabetically, e.g. procurementMethod then procurementMethodDetails then procurementMethodRationale where the 2nd and 3rd are alphabetical as I don't see that there's a clear step or level of detail difference, they're just different additional informations.

Thinking these suggestions through the main problems I see are with fields and objects that can (and in some cases should be!) updated as the contracting process progresses, namely documents, milestones and status.

• status isn't so much of an issue as it's being deprecated so it can just go after finalStatus (and it's additional details fields) as the field that's replacing it.
• I'd expect a Milestone to be defined at the beginning of whichever stage it's attached to, e.g. the tender.milestones would be defined at the start of the tendering stage, but some of the fields within these would be updated later, potentially right up until the conclusion of this stage, and some new milestones could be added as the stage progresses. It probably makes sense to just focus on the first time a milestone might be included and put the array there. So that would be with the other "info on process" fields and objects, and possibly the first in this grouping as a potential milestone could related to the first thing that might happen, e.g. a public hearing prior to the enquiry period opening?
• For documents there are some documents that would be expected to be published at the start of the stage, e.g. 'tenderNotice', but other documents would only be published later in the stage, e.g. 'clarificationsor 'shortlistedFirms'. Similar to the thinking formilestones` I think the array belongs with the "info on process" fields/objects/arrays, and probably at the start as the tendering stage starts with the publication of the tender notice or equivalent documents?

So taking that all into account a suggestion (only going to the second level of a release) could be (only using the expansion of Tender)

{
  "ocid": "",
  "id": "",
  "date": "",
  "language": "",
  "publisher": "",
  "initiationType": "",
  "links": [],
  "tag": [],
  "buyer": {},
  "parties": [],
  "planning": {},
  "tender": {
    "id": "",
    "identifiers": [],
    "title": "",
    "description": "",
    "datePublished": "",
    "procuringEntity": {},
    "documents": [],
    "milestones": [],
    "procurementMethod": "",
    "procurementMethodDetails": "",
    "procurementMethodRationale": "",
    "enquiryPeriod": "",
    "submissionMethod": [],
    "submissionMethodDetails": "",
    "submissionTerms": "",
    "expressionOfInterestDeadline": "",
    "tenderDeadline": "",
    "eligibilityCriteria": "",
    "exclusionGrounds": {},
    "selectionCriteria": {},
    "awardCriteria": "",
    "awardCriteriaDetails": "",
    "awardPeriod": "",
    "standstillPeriod": "",
    "contractPeriod": "",
    "hasEnquiries": "",
    "numberOfTenderers": "",
    "tenderers": [],
    "finalStatus": "",
    "finalStatusDate": "",
    "finalStatusDetails": "",
    "status": "",
    "mainProcurementCategory": "",
    "additionalProcurementCategories": [],
    "items": [],
    "value": {},
    "maximumValue": "",
    "minValue": {},
    "deliveryAddresses": {},
    "deliveryLocations": {}
  },
  "awards": [],
  "contracts": [],
  "relatedProcesses": []
}

Here I've considered procuringEntity to be the end of the "identifying info" group, and put the "procurementMethod" at the start of the "info about process" after the documents and milestones as it's the broadest detail field in that group.