Consider re-organizing Reference section

[jpmckinney]

• The Reference section doesn't offer a clear path for users. Its landing page doesn't sign-post to all sub-pages, so some readers might never read, e.g. the Identifiers page.
• Release Reference is very long and will get longer as more fields/objects are added. In a much larger schema like Schema.org, they split each object into its own page, for example: https://schema.org/docs/full.html
• The long tables are useful when you are looking up a term, but otherwise break up the page and make it hard to scan. It might be better to have at most one long table per page, and for that table to be at the end (like on Schema.org).

The documentation of APIs with a lot of methods and/or objects can also serve as inspiration: for example, Google's and GitHub's developer docs.

[jpmckinney]

Looking at the content, we have:

Thematic content

• https://standard.open-contracting.org/latest/en/schema/identifiers/
• https://standard.open-contracting.org/latest/en/schema/reference/#release-handling
• https://standard.open-contracting.org/latest/en/schema/reference/#language
• https://standard.open-contracting.org/latest/en/schema/merging/
• https://standard.open-contracting.org/latest/en/schema/conformance_and_extensions/

Schema/Codelist references

• https://standard.open-contracting.org/latest/en/schema/reference/#release-structure
• https://standard.open-contracting.org/latest/en/schema/reference/#building-block-reference
• https://standard.open-contracting.org/latest/en/schema/codelists/

Package-related content

• https://standard.open-contracting.org/latest/en/schema/records_reference/ (records can be seen as a way of packaging individual releases, compiled releases and versioned releases – they don't add new data)
• https://standard.open-contracting.org/latest/en/schema/release_package/
• https://standard.open-contracting.org/latest/en/schema/record_package/

JSON Schema browsers

• https://standard.open-contracting.org/latest/en/schema/release/
• https://standard.open-contracting.org/latest/en/schema/release_package/
• https://standard.open-contracting.org/latest/en/schema/record_package/

[jpmckinney]

In terms of re-architecture, we might consider:

• Lead with the thematic content, starting with one page per theme
• Provide the Schema/Codelist references, with one page per object/codelist, so that there is only one big table per page. Presently, I believe a lot of users haven't read the explanatory content above each table, because it's very easy to miss.
• Provide the schema browsers in one section, with three sub-pages.
• Provide the package-related content in one section, with sub-pages as needed.

[jpmckinney]

On each sub-schema page, we can implement a new directive to list where that sub-schema is referenced from (with a link to the relevant page), e.g. the Document sub-schema page would like to the Tender, Award and Contract pages.

[duncandewhurst]

Presently, I believe a lot of users haven't read the explanatory content above each table, because it's very easy to miss.

Strongly agree!

[stevieflow]

Hi @jpmckinney @duncandewhurst

Just wanted to offer in this mix the example of the IATI docs, whereby there's a specific / persistent URL for each and every "data field" of the standard - eg

https://iatistandard.org/en/iati-standard/203/activity-standard/iati-activities/iati-activity/transaction/sector/

This then included left-hand-side navigation that places you in situ / context

I have always found this very useful, both in terms of specificity and navigability, of the schema/standard

Thanks

[jpmckinney]

Thank you for sharing!

I can see the utility given that XML elements have attributes that require documentation.

Since OCDS is JSON, there is not much more to add beyond the field title, type and description, so pages for each field would be very short. I think there's more utility to seeing all an object's fields on one page.

[odscjen]

A few specific issues in this section:

• "Date" is included under the "Subschema reference" heading but it's not a subschema, it's a data format.
• "Document" refers only to the different stages the documents array can be attached, and "Milestone" refers only to the stage objects it can be included in, but these are the same type of subschema used in arrays so it might be clearer to a user to describe their use in the same way. "Item",
• "Implementation" has sub-headings for "Milestones" and "Documents" that reference the relevant sections under "Subschema reference" but none of the other high level stages include these sub-headings, despite them being available in those objects (i.e. tender, Award and Contract).
• "Amendment" is under the "Release structure" heading but would be better under the "Subschema reference" heading as its describing a subschema that is referenced in multiple places in the schema.
• "RelatedProcess" is under "Subschema reference" but would be better under "Release structure" as it only appears in the one place in the schema (outside of extensions).

[duncandewhurst]

I've been looking at the reference documentation while working on other issues and would like to propose a new content architecture based on the proposal in #1075 (comment), with the following changes:

• Add a thematic page for contracting and planning processes, (new in reference.md: add contracting and planning process definitions #1716)
• Move most content from identifiers to the page for the subschema to which it relates, i.e. move:
  • Organization identifiers and local organization IDs to the Organization subschema page
  • Release ID to the release page
  • The parts of Award and Contract IDs about awards to the Award subschema page and the parts about contracts to the Contract page
• Integrate content from Release handling and Merging into a single page
• Add a reference page describing the types and formats used in the schema

Navigation structure

I propose the following navigation structure:

• Reference (landing page)
  • Contracting and planning processes
  • Open Contracting Process Identifier (OCID)
  • Release handling and Merging (integrate content)
  • Language
  • Conformance and extensions
  • Schema and codelists
    • Release
    • Subschemas (One subschema per page, ordered alphabetically. See below for the ordering and grouping of links from the landing page to the pages for each subschema)
      • Address
      • Amendment
      • etc.
    • Codelists (One codelist per page, ordered alphabetically, with links from landing page ordered per Change order of codelists in Reference #1405)
      • awardCriteria
      • awardFinalStatus
      • etc.
    • Types and formats (See proposed content below)
  • Packaging
    • Record
    • Release package (Markdown content)
    • Record package (Markdown content)
  • Schema browsers
    • Release schema
    • Record schema
    • Release package schema (Schema browser)
    • Record package schema (Schema browser)

Ordering and grouping links on the subschema landing page

As in #1405, I think it makes sense to order the subschema pages alphabetically in the navigation. For the links to the individual pages from the subschema landing page, I propose the following grouping and ordering.

Process

• Planning
  • Budget
  • Project
• Tender
• Award
• Contract
• Implementation
• Amendment
• Milestone

Items

• Item
• ImmediateContainer

Organizations

• Organization
• OrganizationReference
• ContactPoint

References

• Document
• Classification
• Identifier
• SimpleIdentifier
• RelatedProcess
• Link

Quantitative

• Value
• Quantity
• Unit
• SimpleUnit

Spatial

• Address
• Location

Temporal

• Period

Type and format documentation

As Jen noted above, the reference documentation for Period includes a date subheading that describes OCDS's use of the date-time format. There are many date-time fields outside of the Period object, so I think it makes sense to describe the format elsewhere.

I think it would also be useful to describe the other types and string formats used in the schema in the reference documentation. That way support staff can link implementers to the documentation for a particular type to help them resolve errors in their publication. The documentation could also be linked from the release and subschema references pages. Ideally, the jsonschema directive could link to the documentation for each type and format from the type and format columns of the tables it generates. However, that would require an update to the directive.

I considered a more general reference page describing all the validation constraints used in the schema, but I think that would essentially mean reproducing the JSON Schema keyword documentation.

I propose a single page with a subheading, description and example for each type and format, e.g.

Types and formats

The OCDS schema specifies the data type of each field. The schema also specifies the format of some string (text) fields. This page describes each of the types and string formats used in the schema.

Array

A list of ordered elements of a specific type or types, e.g. tag is an array of strings:

{
	"tag": [
		"tender",
		"award"
	]
}

Boolean

A true or false value, e.g.

{
	"tender": {
		"hasEnquiries": false
	}
}

Integer

An integral (whole) number, e.g.

{
	"tender": {
		"numberOfTenderers": 3
	}
}

Null

A null value, e.g.

{
	"tender": {
		"title": null
	}
}

To learn about the use of null values in OCDS, see updates and deletions.

Number

An integral (whole) or floating point (decimal) number, e.g.

{
	"tender": {
		"value": {
			"amount": 12750.70
		}
	}
}

Object

A map of key-value pairs, e.g. tender is an object:

{
	"tender": {
		"title": "Office furniture",
		"description": "The ministry aims to purchase..."
	}
}

String

A string of text, e.g.

{
	"tender": {
		"title": "Office furniture"
	}
}

OCDS specifies a format for some string fields.

date-time

An ISO8601 date-time, following RFC3339 §5.6, e.g.

{
	"date": "2025-01-01T00:00:00Z"
}

(Content from Date)

uri

A universal resource identifier (URI), according to RFC3986, e.g.

{
	"planning": {
		"budget": {
			"uri": "https://example.com/budgets/1234"
		}
	}
}

Outstanding questions:

• What to do with https://standard.open-contracting.org/staging/1.2-dev/en/schema/identifiers/#item-document-and-milestone-ids? Everything else on that page is moved elsewhere. It would be too much to repeat it for each local identifier so maybe we have a thematic page for local identifiers.