Publisher Guidance

To implement OCDS, you must identify the fields and codes in OCDS that match the data elements that you want to publish. Some data elements might not match any field or code in OCDS. To cover such cases, you can add additional fields or codes to your OCDS data. Extensions provide a way to document these additional fields and codes.

Why use extensions?

We recommend using extensions to describe your additional fields and codes so that:

• Analysts can access definitions for fields and codes to help them interpret your data.
• Developers can access information about the structure of your data to help write software to process it.
• Your data is consistent with that of other publishers and compatible with reusable tools and methodologies.

Use an extension

To publish additional fields or codes using an extension:

1. Use the Extension Explorer to find an extension that describes the data element(s) you want to publish. If you can’t find a suitable extension, you might need to create an extension.
2. Structure your data according to the extension’s schema and documentation.
3. Declare the extension in your package’s `extensions` array using the URL from the extension’s documentation. For example, to declare the Bid statistics and details extension:
   {"extensions": ["https://raw.githubusercontent.com/open-contracting-extensions/ocds_bid_extension/master/extension.json"]}
4. Check your data using the OCDS Data Review Tool.

Create an extension

If you can’t find a suitable extension to describe the data elements you want to publish, you can create an extension.

Extensions can introduce new fields, add codes to open codelists and introduce additional validation rules to existing OCDS fields. However, extensions cannot remove fields, change the title or description of fields or add codes to closed codelists. To suggest such changes, open an issue on the standard issue tracker.

You should also consider whether the data you want to publish belongs to the contracting process or whether it exists independently. Data that exists independently of the contracting process is typically better published in a separate dataset. For example, data on changes to the beneficial ownership of suppliers, which is usually tracked outside of procurement systems.

To create an extension you need to understand JSON Schema and the structure of the OCDS schema. Extensions are fragments of JSON Schema that can be merged into the OCDS schema to create an extended schema.

The standard extension template describes the structure and components of an extension and the technical steps to document an extension.

There are five steps to creating an extension:

Discuss

Before creating an extension, search for related discussions on the standard issue tracker.

If you can’t find any related discussions, open an issue to describe the extension you plan to create. The issue’s description should include:

• The extension’s use case(s). Describe your reason for adding additional fields and/or codes and what users will do with the data.
• The concepts or process that you want to represent. Explain the underlying concepts described by the extension and the workflow for collecting the data. Include references to legislation and other documentation, and consider providing a diagram.
• Examples of existing data. Provide examples of how the data covered by the extension is represented in your data sources.
• To encourage collaboration, keep this issue up to date throughout the development of your extension.

Develop

You first need to decide on the name, structure and format of the fields in your extension.

You can start by mocking up an example of the data you are creating an extension for in JSON format. Consider:

• How would different data fit into this structure?
• Are the field names intuitive for users?
• Is the structure easy for applications to consume?
• You can also check other standards for potential models. The more different examples of source data, and different use cases for the data you can consider, the better.

Before continuing, you should invite feedback on your mockup using the Github issue you created in the previous step.

Once you have settled on a model, you should then document the schema for your extension. The following tools are available to help you:

• You can use the OCDS Extension Creator to edit the OCDS schema and generate a patch. For more information on using the extension creator, refer to its documentation.
• You can copy the standard extension template and use a text editor to edit the schema files.
• You can use JSONschema.net to generate a schema from your JSON mockup.

Your schema should follow the schema style guide.

Document

You will need to find somewhere to host your extension online at a stable URL. 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: for example, release-schema.json or codelists/codelist.csv. Creating a GitHub repository for your extension is a good option because it offers version control, issue tracking and appropriate URLs: for example, https://raw.githubusercontent.com/open-contracting-extensions/ocds_bid_extension/master/extension.json.

You also need to write a README file and/or other documentation for your extension.

Your documentation should include a description of the extension and its use cases, and examples of data structured according to the extension.

Test

Test your extension by following steps 2-4 in Use an extension.

Register

We encourage you to register your extension so that others can discover it using the Extension Explorer.

Extensions that are useful to only a single publisher do not need to be registered.

To register an extension, it must meet the following criteria:

• The documentation is in English. According to the translation and localization policy, “the authoritative language for the standard is English.” As such, all extensions in the Extension Explorer – as part of the standard’s documentation – must be in English.
• The documentation, excluding examples, is more than 200 characters long. Documentation of less than 200 characters cannot adequately describe an extension, its purpose and technical details.
• The extension.json and README.md files are not publisher-specific. If the extension’s name or description suggests it is relevant to only one publisher, then it is unlikely to be used by other publishers, even if the schema patch is relevant.
• No other extension expresses the same concepts. Having multiple ways to express the same concept would be counter-productive to standardization.
• The extension follows the schema style guide.

Versioning

OCDS extensions should use semantic versioning.