From 5f8e6efc61c8d60a20a38c28549c1ca1c57a3acd Mon Sep 17 00:00:00 2001 From: odscjen Date: Thu, 7 Nov 2024 15:07:38 +0000 Subject: [PATCH 1/4] conformance_and_extensions.md:update extension guidance --- docs/schema/conformance_and_extensions.md | 35 +++++++++++++++++++++-- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/schema/conformance_and_extensions.md b/docs/schema/conformance_and_extensions.md index f414f2a54..1329fec16 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,35 @@ 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. + +Conformant extensions should respect the following guidelines: + +### Core fields + +* Extensions *should not* delete fields from the core schema +* Extensions *should not* change the properties of fields from the core schema. If an extension desires to document further usage of a core standard field, it should do so through documentation, rather than changing the field's `description` property. + +### Structure + +* All definitions and properties *must* set a `title`, `description` and `type`, unless they are originally defined in the core schema or in another extension in which case they *must* set a `$ref` to the existing object +* If a field's `type` is "array", `items` *must* be set +* If using `items`, its `type` *must* only include "array", "number" and/or "string" +* If an array field's `wholeListMerge` and `omitWhenMerged` properties are not used or are set to `false`, the object fields under it *must* have an `id` field and this `id` field *must* be required + +### Codelists + +* If `openCodelist` is `true`, `enum` *must not* be set +* If `openCodelist` is `false`, `enum` *must* be set +* If a field has an `enum`, this *must* be expressed as a csv codelist +* If a field has an `enum`, `codelist` and `openCodelist` *must* be set +* If adding codes to an existing codelist the codelist filename *must* append `+` to the start of the core codelist filename, for example `+documentType.csv` + +### Field and code names + +* Definition names *must* be UpperCamelCase +* Field names *must* be lowerCamelCase +* Definition and field names *must* contain only ASCII alphabetical letters +* If an acronym is used within a field or definition name, the acronym *should* be all UPPERCASE, unless it is at the beginning of the name, in which case it *should* be all lowercase. From f55e14802356eb97c1cc470700b5b5bbc0054759 Mon Sep 17 00:00:00 2001 From: Jen Harris <95221058+odscjen@users.noreply.github.com> Date: Tue, 19 Nov 2024 16:37:00 +0000 Subject: [PATCH 2/4] Update docs/schema/conformance_and_extensions.md Co-authored-by: Duncan Dewhurst --- docs/schema/conformance_and_extensions.md | 46 ++++++++++++++--------- 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/docs/schema/conformance_and_extensions.md b/docs/schema/conformance_and_extensions.md index 1329fec16..8cdbe04ce 100644 --- a/docs/schema/conformance_and_extensions.md +++ b/docs/schema/conformance_and_extensions.md @@ -27,29 +27,39 @@ The schema for the standard by default allows for new fields, and does not fail Conformant extensions should respect the following guidelines: -### Core fields +### Changes to existing fields -* Extensions *should not* delete fields from the core schema -* Extensions *should not* change the properties of fields from the core schema. If an extension desires to document further usage of a core standard field, it should do so through documentation, rather than changing the field's `description` property. +A conformant extension *should not*: -### Structure +* 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. -* All definitions and properties *must* set a `title`, `description` and `type`, unless they are originally defined in the core schema or in another extension in which case they *must* set a `$ref` to the existing object -* If a field's `type` is "array", `items` *must* be set -* If using `items`, its `type` *must* only include "array", "number" and/or "string" -* If an array field's `wholeListMerge` and `omitWhenMerged` properties are not used or are set to `false`, the object fields under it *must* have an `id` field and this `id` field *must* be required +### 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 -* If `openCodelist` is `true`, `enum` *must not* be set -* If `openCodelist` is `false`, `enum` *must* be set -* If a field has an `enum`, this *must* be expressed as a csv codelist -* If a field has an `enum`, `codelist` and `openCodelist` *must* be set -* If adding codes to an existing codelist the codelist filename *must* append `+` to the start of the core codelist filename, for example `+documentType.csv` +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*: -### Field and code names +* 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 -* Definition names *must* be UpperCamelCase -* Field names *must* be lowerCamelCase -* Definition and field names *must* contain only ASCII alphabetical letters -* If an acronym is used within a field or definition name, the acronym *should* be all UPPERCASE, unless it is at the beginning of the name, in which case it *should* be all lowercase. +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. From 59ee5c83cd095d9c7ee879190cda803aa25c6e5d Mon Sep 17 00:00:00 2001 From: odscjen Date: Tue, 19 Nov 2024 16:43:13 +0000 Subject: [PATCH 3/4] update docs/schema/conformance_and_extensions.md --- docs/schema/conformance_and_extensions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/schema/conformance_and_extensions.md b/docs/schema/conformance_and_extensions.md index 8cdbe04ce..1d287f49b 100644 --- a/docs/schema/conformance_and_extensions.md +++ b/docs/schema/conformance_and_extensions.md @@ -25,16 +25,16 @@ Extensions to the standard may add new objects and fields to accommodate specifi The schema for the standard by default allows for new fields, and does not fail validation of a file which contains unknown fields. -Conformant extensions should respect the following guidelines: +### Extension conformance guidelines -### Changes to existing fields +#### 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 +#### New fields A conformant extension *must*: @@ -44,7 +44,7 @@ A conformant extension *must*: * 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 +#### Codelists A conformant extension *must*: @@ -54,7 +54,7 @@ A conformant extension *must*: * 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 +#### Naming conventions A conformant extension *must*: From 0dc39da197d51ed4c683791edb4066c810e441e0 Mon Sep 17 00:00:00 2001 From: Jen Harris <95221058+odscjen@users.noreply.github.com> Date: Thu, 21 Nov 2024 09:50:32 +0000 Subject: [PATCH 4/4] Update docs/schema/conformance_and_extensions.md Co-authored-by: Duncan Dewhurst --- docs/schema/conformance_and_extensions.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/schema/conformance_and_extensions.md b/docs/schema/conformance_and_extensions.md index 1d287f49b..e837362fc 100644 --- a/docs/schema/conformance_and_extensions.md +++ b/docs/schema/conformance_and_extensions.md @@ -25,7 +25,16 @@ Extensions to the standard may add new objects and fields to accommodate specifi 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 guidelines +### 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