1 of 42

Creating an OCDS Extension

2020, remote

2 of 42

Introduction

3 of 42

Introduction: Welcome

Welcome everyone

Introduce yourselves via Zoom chat
Notes doc (link)

4 of 42

Introduction: Expectations and Target Audiences

This webinar has been designed with the following people in mind:

Intermediate or above knowledge of OCDS
Understand how the OCDS extension mechanism works
Comfortable with Github and JSON

5 of 42

Introduction: Aims and Objectives

Aim: Provide an overview of developing a OCDS extension

Participants understand the resources and support available to them when they are developing an extension
Participants know an overview of the steps involved in developing an extension
Participants are introduced to how developing an extension looks in practice (through a demonstration)

6 of 42

Introduction: Agenda

Target Length: 45 hour

Extensions recap
Introduction to creating an extension

Step 1: Discuss
Step 2: Development
Step 3: Documentation
Step 4: Demonstration and Testing

Extension creation live demonstration
Summary and Q&A

7 of 42

Extensions recap

8 of 42

Extensions

OCDS implementation involves mapping your data to OCDS.

Some of your data might not match any field or code in OCDS. To cover such cases, you can use extensions to add extra fields and codes.

Extensions provide a way to document these extra fields and codes and define validation for them as well as declaring them as available for data users and tools.

OCDS�fields and codes

Your�data

Data that maps

Unused�fields and codes

Extensions

9 of 42

Do I need to use extensions?

Use the field level mapping template to identify data which:

Maps to the core OCDS schema�Extensions are not required to publish this data.

Maps to fields in a recommended extension�Use the extensions explorer to find out how to use the extension.

Doesn’t map to either of the above�Use the extension explorer to check if another extension exists which could be used to disclose your data.

Contact the helpdesk (data@open-contracting.org) if you have data that doesn’t map to the core OCDS schema or any existing extensions.

The way you determine whether you need to use an OCDS extension is by engaging with the OCDS Field Level Mapping process, which is supported by our field level mapping template. First identify data that maps to the core OCDS schema as you don’t need to think about extensions here. Next you should see which of the fields in your data map to fields in a recommended extension and determine how to use it via the extensions explorer. Finally if you’ve got data that doesn’t map to either of those, use the extensions explorer to discover other extensions that may apply.

If you have data that doesn’t map to any existing OCDS field or extension then get in touch with the helpdesk and we’ll support you with what to do going forward. This webinar is a first step in that support; but you should still get in touch with us anyway so we’re aware of what you’re trying to do adn we can help.

10 of 42

Declaring an extension

Extensions are declared in the package metadata for releases and records

11 of 42

Creating an extension

12 of 42

When to create an extension

Before you begin developing an extension; check that you definitely need to. Develop an extension when you are certain that:

✔ You have checked that your data does not map to an existing OCDS field or extension

✔ You have searched the OCDS Standard repo for open/closed issues

✔ Nobody else is working on a similar problem

The first big question to ask when developng an extension is whether you actually need to do it at all? Creating Extensions comes into play when you are sure that you can’t model your data using core OCDS or an existing extension

If data cannot be mapped to an existing extension, then publishers are encouraged to collaborate with others who might need to represent the same information, such as those of a similar scale, locality or specialism. For example if you’re a local authority within a particular nation you might want to work with other local authorities in your country.

Before deciding to create your own extension search open and closed issues in the OCDS Standard issue tracker to make sure no one is already working on a related extension. If they are, consider getting in touch with them to collaborate; the helpdesk is happy to facilitate this for you if you’re unsure how to get in touch. If you can’t find anyone, consider sending a message to the OCDS mailing list to solicit interest.

13 of 42

Check your knowledge

Developing an extension requires an understanding of the following:

You can use the standard extension template to support you

JSON Schema

14 of 42

Creating an extension: 4Ds

Step 1: Discuss�
Step 2: Development�
Step 3: Documentation�
Step 4: Demonstration & testing

15 of 42

Step 1: Discuss

16 of 42

1: Discuss

Check for existing extensions on the extensions explorer
Search for existing issues on the OCDS github (including closed issues)
Open a new issue to describe your needs and plans for the data: get the community engaged

The first stage of the process is to Discuss the idea for a new extension with others. OCDS benefits from a very active community and although every procurement cotnext is unique there are common problems that are faced by people across the board.

The first thing you should do to check our OCDS extensions explorer for extensions. Make sure you search thoroughly and search using synonyms to make sure you’ve covered the bases.

After this you should search our Github for issues, we can be found at github.com/open-contracting. What you’re trying to do here is unearth previous discussions around your problem. Determine whether the advice given there is applicable to you -- did they end up using an existing extension? Was an extension developed as a result of this? Could you use it? There’s a chance it’s in the extensions explorer already and you’ve missed it.

Finally, if you can’t find a discussion that covers your problem or if it’s ambiguous then you should create a new issue.

17 of 42

Discuss

When creating an issue, make sure that you communicate clearly and include the following:

A description of the process you’re trying to represent
Examples of existing data, to help with data modeling
What belongs in OCDS vs secondary datasets
A description of the use-cases

When you create a new issue it’s important to communicate clearly, this helps the OCDS team and the wider community engage. It also helps people find this issue more easily when they’re in your position searching github later!

A description of the process you are trying to represent.

Avoid too much detail about the data: describe the workflow and the information that people know at particular points in time. A diagram can help here.

Examples of existing data.

Ideally, find two or three different examples of how this data is currently represented, to help with data modeling.

What belongs in OCDS,

and what could belong in secondary datasets. For example, some budget and corporate information is better represented in separate datasets, as they are independent of individual contracting processes.

A description of the use cases for this data.

In particular: Is there a strong use case for comparing between countries? Is the main use case creating common interfaces? This will inform the balance between interoperable abstraction versus direct representation of a publisher’s data.

18 of 42

Discuss

“I need an extension to represent multiple buyers”

This discussion lead to the multiple buyers - contract level extension

19 of 42

Discuss

Practical tips for this step:

Always check the extensions explorer and OCDS Standard Github issues first
When opening a new issue be clear about your use-cases and needs and how you’re proposing to model them
Get the community engaged by contacting the OCDS mailing list and helpdesk teams
Be prepared to collaborate

20 of 42

Step 2: Development

21 of 42

2. Development: The structure of an extension

Documentation explaining the use-cases for fields and codes (README.md)
JSON merge-patch against the schema introducing the schema definitions of new fields and codes (release-schema.json)
Extension definition that describes the extension (extension.json)

22 of 42

2. Development: Getting started

Or using extension creator

Based on template repository

23 of 42

2. Development

1. design your field names and structures

String: procurementManager, Array (Cost Centre): costCentres

2. Mock up the data

24 of 42

2. Development

3. Consider the OCDS Schema conventions

Visit the style guide to check you’re meeting the style

4. Produce the JSON Schema merge patch

25 of 42

2. Development

Practical tips for this step:

Use either the Github template or the Extensions Creator to get started
Follow good practice by consulting the OCDS style guide
Check in often with the OCDS Helpdesk <data@open-contracting.org>

26 of 42

Step 3: Documentation

27 of 42

3. Documentation

You should provide clear and concise documentation in the README file so that implementers and data users know how your extension works. Good documentation consists of:

An introduction providing a short description of the motivation for the extension
Definitions of each of the field, matching the definitions provided in the schema itself
Examples of data that could be provided using the extension.

If you’re familiar with writing technical documentation then the same rules apply here as well. All documentation should be clear and concise; th goal is to make sure that implementors of your extension and users of the data know how the extension works.

Introduce the extension by providing a short description of what it does and what the motivation is for it. What problem does it solve?
Make sure you give clear definitions of each field you’ve added in the extension. These should align with the definitions provided in the actual extension schema you’ve created as well.
It’s often best to see an extension in action in order to get an understanding of how to work with it. You should include an appropriate amoint of examples of data using the extension, ideally which are situated in a use-case.

28 of 42

3. Documentation

Example: Bid statistics and details extension

29 of 42

3. Documentation

Practical tips for this step:

Introduce and motivate the extension
Provide plain-english descriptions of fields
Provide examples of data using the extension
Write clearly and concisely; check your writing using a readability app
Read existing extension documentation to see good practice in action

30 of 42

Step 4: Demonstration & Testing

31 of 42

4. Demonstration & Testing

Before using your extension in an implementation it is important to test it out.

Host the extension using Github
Declare the extension in some sample data
Upload your sample data to the Data Review Tool

Hopefully if you’re a technical audience I don’t need to drive home the importance of testing an extension before you deploy it or release it. Following this process we’ve outlined will minimise the chance of errors but human being make mistakes. Testing means that you can catch these and reduce the risk of errors before deployment even further.

First you should host the extension so that the URL is publically accessible. The OCDS team has a preference for extensions hosted on github so that the community can engage with them and we can collaborate better. You should then declare the extension in some sample data and implement the changes it adds to the OCDS schema; making use of your new fields and codelists.

Finally, upload this sample to the Data review tool. What you’re looking for is a result where your extension is detected and applied correctly, and that the validation rules are applied properly.

32 of 42

4. Demonstration & Testing

You should be testing for two things during this step:

That you can apply your new fields and codes and that they’re valid and not “additional fields”
That your validation rules are applied correctly (ie break some data!)

33 of 42

4. Demonstration & Testing

Practical tips for this step:

Test with sample data first to make sure your extension is being applied properly
Test data that should validate and invalidate; use different data types to try and break validation
Consult the JSON Schema website for tips on writing JSON Schema
Get in touch with the helpdesk at data@open-contracting.org

34 of 42

Extension Creation Live demo

35 of 42

Extension Creation Live Demo

“I need an extension to model a tender with a predefined location”

36 of 42

Extension Creation Live Demo

Creating an extension is straightforward using our tools:

Use the extension creator to modify the schema and download your new extension
Upload to a public place, like a github repository
Review the sample data with the Data Review Tool

Sample files to try yourself:

37 of 42

Key Tools

38 of 42

Key Tools

Data Review Tool

E xtension creator

Template repository

You’ve just seen me demonstrate these tools but I want to drive the point home that you have an array of tools that work together to ensure that you can make your extension as great as possible. The template repository provides a good starting point and “checklist” for ensuring you’ve got all elements of the extension down: documentation; schema patch; extension file etc. Github also provides a simple way to develop and host your extension where you and your team and collaborate on it with the OCDS team.

The extensions creator makes it very simple to actually develop your extension. Using it you can develop patches to introduce new fields and re-use definitions of objects very simply. It can then generate your extension for you.

The data review tool should then be used to review data that you apply your extension to. You might want to start with sample data, as we did here, but after this you should apply the extension to a proper set of test data and review it thoroughly to make sure it’s behaving as you intend. This is particularly important if you’re developing new object definitions or you’re creating new validation rules.

39 of 42

Summary and Q&A

40 of 42

Summary

OCDS extensions document the structure, format and meaning of additional fields and codes.�
Create your own extension if you need to publish data which doesn’t map to either the core OCDS schema or any existing extensions.�
Remember the 4 D’s for creating an extension: Discuss, Develop, Document and Demonstrate.�
Use the Extension Template Repository and/or the Extension Creator to develop your extension.

41 of 42

Questions and Answers

We’ll answer some questions from the notes document now and also send out answers to all questions via the OCDS Standard Mailing list.

Join the mailing list: link
Contact the Helpdesk <data@open-contracting.org>

42 of 42

English OCP Post-event Survey

www.surveymonkey.com/r/ocp-post-event

Scan the QR code below to access the survey on your device.