Review Extensions conformance section

[jpmckinney]

Possible new requirements for extensions:

• All definitions and properties must set a title, description and type, unless they are originally defined in the core schema or in another extension. https://github.com/open-contracting/standard/issues/603
• If openCodelist is true, enum must not be set.
• If openCodelist is false, enum must be set. https://github.com/open-contracting/ocds-extensions/issues/32
• If openCodelist is false and enum is set, enum must match the codes in the codelist.
• If a field has an enum, should we require that it be expressed as a codelist?

We can offer tool support for this: both for validating extensions, and for automatically putting the codes from the codelists into the enum. (Both tools now exist.)

http://standard.open-contracting.org/latest/en/schema/conformance_and_extensions/#extensions

[jpmckinney]

Possible new requirements (related to https://github.com/open-contracting/standard-maintenance-scripts/issues/48):

• Conformant extensions should not delete fields from the standard's schema.
• Conformant extensions should not change the properties of fields from the standard's schema. Note: api_extension changes required to [] and ocds_milestone_documents_extension changes deprecated to null.

This is to avoid an extension changing the semantics of the standard's schema and thereby breaking interoperability.

If an extension desires to further document the usage of a field, it should do so through documentation, rather than through changing a field's description property.

[jpmckinney]

Possible new requirements (related https://github.com/open-contracting/standard-maintenance-scripts/issues/45):

• Definition names should be UpperCamelCase.
• Field names should be lowerCamelCase.
• Both names should contain only ASCII alphabetical letters.
• If an acronym is used within a name, the acronym should be all uppercase, unless it is at the beginning of the name, in which case it should be all lowercase.

[duncandewhurst]

I'm in favour of all of the proposed requirements. However, there is some cross-over with parts of the schema style guide, so we should consider how to keep those in sync, or whether the style guide should defer to the extensions conformance section for some points.

If a field has an enum, should we require that it be expressed as a codelist?

I think so, so that titles and descriptions for the enum values can be translated.

[jpmckinney]

Yes, once this documentation exists, we can remove some content from the style guide and link to these docs.

This is quite an old issue. Some additional rules for extensions are expressed by the schema files for CSV codelists and extension.json files: https://github.com/open-contracting/standard-maintenance-scripts/tree/main/schema

These tests might also go beyond the above. (The jscc documentation might be easier to read.)

I'd consider this issue to be lower priority, as we have internal tools for checking extensions. For the rules to be really useful, we'd have to consider an online tool – but there are not a huge number of unregistered extensions.

[jpmckinney]

See also #1571 on rules for publishing extensions.

[jpmckinney]

Noting that normative.md mentions extension-schema.json and codelist-schema.json. If this issue mentions those, we should move them to this repository, and update normative.md.

[duncandewhurst]

@jpmckinney I know you said this was lower priority, but given that most other issues are blocked or pending review, shall @odscjen or I prepare a PR to update the extensions conformance documentation?

[jpmckinney]

Sure. Let's keep it succinct (e.g. bullet form, with subheadings to organize content as needed). Once the PR is approved, there can be a corresponding PR to delete content from the handbook and reference this page instead (it can link to the staging page until 1.2 is released).