Publisher Guidance

This page is for publishers of OCDS data. It provides:

  • An introduction to extensions and the needs they satisfy
  • How-to guides for using and creating extensions
  • Reference documentation for extension creators

Introduction

To implement OCDS, you need to identify the fields and codes in OCDS that match the data elements in your data sources. Some data elements might not match any field or code in OCDS. To cover such cases, you can add fields and codes to OCDS using “extensions.”

Extensions serve to document the meaning and structure of additional fields and codes. The benefits are:

  • By reusing extensions, your data is consistent with other publishers' data, making it possible for you and others to reuse OCDS tools and methodologies.
  • Analysts can access the definitions of your additional fields and codes, to help interpret your data.
  • Developers can read the structure of your additional fields and codes, to help write software for processing it.

How to use an extension

  1. 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 Bids and expressions of interest 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.

How to 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 add new fields, add codes to open codelists, or add validation rules to existing fields. However, extensions cannot remove fields, change the titles or descriptions of fields, or add codes to closed codelists. To suggest such changes, open an issue on the standard issue tracker.

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 the beneficial owners of suppliers is usually tracked outside of procurement systems.

To create an extension that adds a new field or validation rule, you need to understand JSON Schema and the structure of the OCDS schema.

There are six steps to creating an extension:

1. Discuss

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

If you can't find any related discussions, open a GitHub issue to describe the extension you plan to create. Include in the issue's description:

  • The extension's use case(s). Describe your reason for adding fields and/or codes and what users will do with the data.
  • The concept or process that you want to represent. You can include legislative references or other documentation.
  • Examples of existing data. Provide examples from your data sources of the data elements to be covered by the extension.
  • To encourage collaboration, keep this issue up-to-date throughout the development of your extension.

2. Model

Once you are clear on your concepts and use cases, you need to decide on the name, structure and format of any additional fields in your extension, and on the name of any additional codes.

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

  • How would different data fit into this structure?
  • Are the names of fields and codes intuitive to users?
  • Is the structure easy for applications to consume?

You can also check other standards for potential models. The more you consider different examples of source data and different uses of the OCDS data, the better.

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

3. Author

Once you settle on a model, you need to author (as applicable) the metadata, documentation, schema and codelists. You can use the extension template. For details, see Reference.

4. Publish

You need to publish your extension online at a stable URL. Your extension's schema and codelist files need to be accessible 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, GitLab or Bitbucket 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

When naming your repository, follow the pattern for repository names.

5. Test

Test your extension by following steps 2-4 of How to use an extension. Check that the OCDS Data Review Tool reports no structural errors, additional fields or additional codes.

6. Register

We encourage you to register your extension, so that others can discover it on this website.

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

A registered extension needs to meet the following criteria:

  • The documentation is in English. According to the translation and localization policy, “the authoritative language for the standard is 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 a single publisher, then it is unlikely to be used by other publishers, even if its fields and codes are 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.

Reference

This section provides reference documentation for extension creators.

Extensions consist of:

To see the extension's structure visually, visit the extension template.

Metadata (required)

The extension's metadata is expressed as an extension.json file.

The file's contents must conform to the extension schema (schema viewer).

Guidance

Use the extension template's extension.json file as a starting point.

You can edit and validate your extension.json file, while reading the extension schema, by using the Atlassian JSON Schema Viewer.

To write a good description:

  • Describe the changes made by the extension, at a high level.
  • Although there's no maximum length, be concise. That said, do not sacrifice clarity for the sake of brevity.
  • Do not simply duplicate or paraphrase the extension's name.
  • Do not include the development status of the extension (like “draft”). If needed, describe the status in the documentation.

For example, for Performance failures, a bad description is:

An extension covering performance failures in OCDS.

A good description is:

Adds fields to the implementation section to allow disclosure of an array of contracting performance failures. Based on the performance failures reporting table defined in the World Bank Framework for Disclosure in PPPs.

The description field is displayed on this website.

Documentation (required)

The extension's documentation is expressed as a README.md file.

The README.md file must be in Markdown format.

The README.md file should include a description of the extension and its use cases, and examples of OCDS data that use the extension's fields and/or codes.

You may provide documentation in addition to the README.md file.

Schema (optional)

The extension's new fields and changed fields are expressed as a release-schema.json file. This file has the same structure as OCDS' release schema.

The file contains a fragment of JSON Schema, known as a JSON Merge Patch, that can be merged into OCDS' release schema, to produce an “extended schema.”

The file must describe only new fields or changed fields.

The file's contents must conform to JSON Schema Draft 4.

The file should follow the schema style guide.

Guidance

For example, this schema adds a statusDetails field to the Contract subschema: 

{
  "definitions": {
    "Contract": {
      "properties": {
        "statusDetails": {
          "title": "Status Details",
          "description": "Additional detail on the status of the contract. This field can be used to provide the local name of the status",
          "type": [
            "string",
            "null"
          ],
          "minLength": 1
        }
      }
    }
  }
}

If you are unfamiliar with JSON Schema, you can use Transform to generate an initial schema from a sample or mockup of your OCDS data. Then, add title and description properties, and follow the schema style guide, in particular the validation keywords section.

Codelists (optional)

The extension's new codelists and new codes are expressed as CSV files in a codelists directory. These files have the same structure as OCDS' codelists.

A codelist file must describe only new codelists or new codes.

A codelist file's name must be camel case, like tenderStatus.csv.

A codelist file's contents must conform to the codelist schema (in the schema viewer, expand the Root definitions accordion and click the Row item).

A codelist file should follow the style guides for code names, code titles and code descriptions.

Guidance

To add a new codelist, make sure that its filename is not the same as an existing codelist's filename. Add and fill in the Code, Title, and Description columns.

To add new codes to an open codelist, create a file that prefixes a plus sign (+) to the codelist's filename, and make sure that the new codes do not match any existing codes. Use the same columns as the original codelist.

For example, to add a 'subcontractor' code to the partyRole.csv codelist, create a +partyRole.csv file in your extension's codelists directory, and set its content to: 

Code,Title,Description
subcontractor,Subcontractor,An organization that will perform part of a contract on behalf of a supplier.

Repository name

Names of repositories should follow the pattern: ocds_{name}_extension. For example: ocds_bidOpening_extension

The name should indicate the domain (like medicine) or the field being added (like coveredBy). If the field being added is ambiguous, the parent object should prefix the field name (like document_publisher).