diff --git a/docs/schema/conformance_and_extensions.md b/docs/schema/conformance_and_extensions.md index f414f2a54..e837362fc 100644 --- a/docs/schema/conformance_and_extensions.md +++ b/docs/schema/conformance_and_extensions.md @@ -2,7 +2,7 @@ To maximize the interoperability of data published using the Open Contracting Data Standard we have set out key principles for **conforming** to the standard. These also create space for **extensions** of the standard to respond to particular publisher or user needs. -## Conformance +## Conformance ### Publication conformance @@ -13,7 +13,7 @@ To maximize the interoperability of data published using the Open Contracting Da 1. It *may* use terms from outside this specification's terms where this specification's terms are insufficient. 1. If an implementation serializes to JSON, its serializations *must* [validate](https://review.standard.open-contracting.org/) against this specification's JSON Schema. -Whenever using terms from outside the OCDS standard, we encourage the publisher or user responsible to consult with the community on the best approach to adopt. +Whenever using terms from outside the OCDS standard, we encourage the publisher or user responsible to consult with the community on the best approach to adopt. (Our publication conformance section is [based on the Popolo Project](https://www.popoloproject.com/specs/#conformance) approach.) @@ -21,6 +21,54 @@ Whenever using terms from outside the OCDS standard, we encourage the publisher If you have additional fields which cannot be mapped to the OCDS schema or an existing extension, you should include these in your OCDS data and [create a new extension](../guidance/map/extensions) to document their structure and meaning. Extensions ought to be documented and shared so that other publishers and users can draw upon them, and so that extensions can be considered for inclusion in a future version of the standard. The [Extension Explorer](../guidance/map/extensions) publishes details of known extensions. -Extensions to the standard can add new objects and fields to accommodate specific local requirements. An extension must not be created if it is possible to use existing terms from the standard. It must be possible to access an extension's schema and codelist files by replacing `extension.json` in the extension's URL with a file's path, e.g. `release-schema.json` or `codelists/codelist.csv`. For more information, refer to the Extension Explorer's [guidance on documenting extensions](https://extensions.open-contracting.org/en/publishers/#document). +Extensions to the standard may add new objects and fields to accommodate specific local requirements. An extension must not be created if it is possible to use existing terms from the standard. It must be possible to access an extension's schema and codelist files by replacing `extension.json` in the extension's URL with a file's path, e.g. `release-schema.json` or `codelists/codelist.csv`. For more information, refer to the Extension Explorer's [guidance on documenting extensions](https://extensions.open-contracting.org/en/publishers/#document). The schema for the standard by default allows for new fields, and does not fail validation of a file which contains unknown fields. + +### Extension conformance + +This section documents the normative rules that OCDS extensions must conform to. It uses the following terms from JSON Schema to describe the rules for extension schemas: + +* [property](https://json-schema.org/understanding-json-schema/reference/object#properties): A key-value pair belonging to an object, defined using the `properties` keyword in the schema or subschema for the object, e.g. `ocid` is a property of an OCDS release and it is defined under the top-level `properties` keyword in the OCDS release schema. +* [definition](https://json-schema.org/understanding-json-schema/structuring#defs): A subschema defined using the top-level `definitions` keyword, e.g. the `Award` definition contains the subschema for an OCDS award and it is defined under the `definitions` keyword in the OCDS release schema. +* [keyword](https://json-schema.org/understanding-json-schema/keywords): A key within a JSON Schema used to define the structure of JSON data , e.g. the `type` keyword specifies the data type for a property. + + + + +#### Changes to existing fields + +A conformant extension *should not*: + +* Delete properties or definitions from the OCDS schema. +* Change the value of keywords in the OCDS schema. If an extension desires to document further usage of a field in the OCDS, it should do so through documentation, rather than changing the field's `description` keyword. + +#### New fields + +A conformant extension *must*: + +* Set the `title`, `description` and `type` keywords for all new definitions and properties +* Set `$ref` for fields that reuse a definition in the OCDS schema. +* Set the `items` keyword for properties of `type` "array" +* Not include types other than "array", "number" and/or "string" in the `types` keyword under an `items` keyword. +* Ensure that any definition referenced in a property of `type` array, whose `wholeListMerge` and `omitWhenMerged` keywords are unset or set to `false`, has a required `id` property. + +#### Codelists + +A conformant extension *must*: + +* Set `enum` for properties with `openCodelist` set to `false` +* Not set `enum` for properties with `openCodelist` set to `true` +* Set `codelist` and `openCodelist` for properties that set `enum`. +* Document titles and descriptions for `enum` values as a CSV codelist. +* Append "+" to the start of the codelist filename when adding codes to an existing codelist, e.g. `+documentType.csv`. + +#### Naming conventions + +A conformant extension *must*: + +* Use lowerCamelCase for property names, e.g. `tenderPeriod` +* Use UpperCamelCase for definition names, e.g. `RelatedProcess` +* Use only ASCII alphabetical letters for property and definition names + +A conformant extension *should* use UPPERCASE for acronyms within property or definition names, unless the acronym is at the beginning of the name, in which case it *should* be all lowercase.