Skip to content

Commit 5f8e6ef

Browse files
committed
conformance_and_extensions.md:update extension guidance
1 parent 0871878 commit 5f8e6ef

File tree

1 file changed

+32
-3
lines changed

1 file changed

+32
-3
lines changed

docs/schema/conformance_and_extensions.md

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
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.
44

5-
## Conformance
5+
## Conformance
66

77
### Publication conformance
88

@@ -13,14 +13,43 @@ To maximize the interoperability of data published using the Open Contracting Da
1313
1. It *may* use terms from outside this specification's terms where this specification's terms are insufficient.
1414
1. If an implementation serializes to JSON, its serializations *must* [validate](https://review.standard.open-contracting.org/) against this specification's JSON Schema.
1515

16-
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.
16+
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.
1717

1818
(Our publication conformance section is [based on the Popolo Project](https://www.popoloproject.com/specs/#conformance) approach.)
1919

2020
## Extensions
2121

2222
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.
2323

24-
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).
24+
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).
2525

2626
The schema for the standard by default allows for new fields, and does not fail validation of a file which contains unknown fields.
27+
28+
Conformant extensions should respect the following guidelines:
29+
30+
### Core fields
31+
32+
* Extensions *should not* delete fields from the core schema
33+
* 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.
34+
35+
### Structure
36+
37+
* 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
38+
* If a field's `type` is "array", `items` *must* be set
39+
* If using `items`, its `type` *must* only include "array", "number" and/or "string"
40+
* 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
41+
42+
### Codelists
43+
44+
* If `openCodelist` is `true`, `enum` *must not* be set
45+
* If `openCodelist` is `false`, `enum` *must* be set
46+
* If a field has an `enum`, this *must* be expressed as a csv codelist
47+
* If a field has an `enum`, `codelist` and `openCodelist` *must* be set
48+
* If adding codes to an existing codelist the codelist filename *must* append `+` to the start of the core codelist filename, for example `+documentType.csv`
49+
50+
### Field and code names
51+
52+
* Definition names *must* be UpperCamelCase
53+
* Field names *must* be lowerCamelCase
54+
* Definition and field names *must* contain only ASCII alphabetical letters
55+
* 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.

0 commit comments

Comments
 (0)