You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/schema/conformance_and_extensions.md
+32-3Lines changed: 32 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
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.
4
4
5
-
## Conformance
5
+
## Conformance
6
6
7
7
### Publication conformance
8
8
@@ -13,14 +13,43 @@ To maximize the interoperability of data published using the Open Contracting Da
13
13
1. It *may* use terms from outside this specification's terms where this specification's terms are insufficient.
14
14
1. If an implementation serializes to JSON, its serializations *must*[validate](https://review.standard.open-contracting.org/) against this specification's JSON Schema.
15
15
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.
17
17
18
18
(Our publication conformance section is [based on the Popolo Project](https://www.popoloproject.com/specs/#conformance) approach.)
19
19
20
20
## Extensions
21
21
22
22
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.
23
23
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).
25
25
26
26
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