Localising OCDS: translations, terminology and extensions

The latest post in our technical series looking at learning from implementing the OCDS.

The Open Contracting Data Standard was designed so that it can be used in many different settings around the world: from a local government procurement system in Canada, to national procurement systems in Zambia, or for the procurement around major projects in Mexico.

Whatever the context, the OCDS is designed to provide all the main building blocks for disclosure of the key contracting data users need, published in interoperable ways. However, the OCDS is not intended to be exhaustive. Local legislation, languages and user needs might require additional fields, or just additional documentation to explain how the OCDS applies.

When applying the OCDS in a single country it can be useful to:

1. Document the local definition of key terms;
2. Identify a mapping between disclosures required by law, and OCDS fields;
3. Propose extensions to the standard in order to capture additional national requirements;
4. Translate the whole standard into the local language;

In this blog post we address each of these steps in turn.

Local terminology

As the OCDS is a global standard, we have taken care to try and use generally applicable field titles and descriptions that make sense across different jurisdictions. These general titles and definitions are important for global data interoperability – but in some cases it is useful to maintain a mapping between the text found in the OCDS, and local terminology. This can help local users of the standard to understand exactly how a field should be interpreted in relation to local legal contexts.

For example, the current Spanish translation of the OCDS uses the title ‘Artículos que se adquirirán’ for tender/items (Line Items), whereas in Mexico, the term more commonly used is ‘Items de la licitación’.

To document local terminology

The best place to start is the latest version of the Mapping Spreadsheet which can be generated in each language for which an official OCDS translation exists.

Open it up and make a copy, and then go to the ‘OCDS Full Schema’ and ‘OCDS Document Codelist’ tabs. These drive all the titles and descriptions that appear throughout the rest of the mapping sheet.

If you need to propose a localised title or description of a field, or document type, these can be provided in Columns C and D of these tabs. We recommend that you keep the official translation in brackets after your localised terminology. For example, updating ‘Artículos que se adquirirán’ to ‘Items de la licitación (Artículos que se adquirirán)’. This will make it easier for a reviewer to check the localised translations have not changed the underlying meaning of any terms. You can use the comments feature of Google Docs to discuss the proposed localisation.

If you create your own alternative mapping spreadsheet, make sure to include these original field paths. By using these as the ‘keys’ for any localised translation – it is easier for us to compare translations and to manage any required updates as the standard develops in future.

If you create a localised mapping sheet – you can ask the OCDS helpdesk to review it before you start making further copies for local use.

Mapping against legal frameworks

When the legal framework of a country mandates specific contracting disclosures it is useful to:

1. Identify the legal requirements that relate to each OCDS field;
2. Identify any additional fields or documents that could be included within the OCDS publication to allow organisations to meet their legal obligations through their open data;
3. Identify any OCDS fields which cannot be provided for legal reasons.

To carry out a legal mapping

Again, we recommend starting with the latest version of the Mapping Spreadsheet, or the version you created with localised terminology as above.

You will also need a clear list of the disclosure requirements set out in law, ideally divided up to indicate which stage of the contracting process they apply to, and under which circumstances.

Working through the OCDS tabs (1 – 6) for general information, planning, tender, award, contract and implementation stages, you can either add information on the legal requirement a field relates to in column E (Mapping Notes), or by adding a new column to list the relevant legal requirement.

There may not be a one-to-one mapping between legal requirements and OCDS fields, as the OCDS often breaks down legal disclosure concepts (e.g. disclose the supplier) into a number of sub-fields to ensure the accurate description of the requirement in data terms. However, it should be possible to identify fields in the OCDS related to many legal disclosure requirements.

There are likely to be a few elements in any domestic legal framework which are not captured in the OCDS. For example, some countries ask for explicit disclosure of the type of organisation receiving funds, based on a particular national classification. For those requirements where no existing OCDS field exists, the mapping spreadsheet includes space at the bottom of each sheet to list these additional required fields.

Provide as much detail as you can on these additional requirements, and then get in touch with the OCDS helpdesk, who will be able to work with you to identify whether an extension to the standard is required, or whether these requirements can be captured using existing standard building blocks.

Proposing extensions

The OCDS supports extensions. If you include fields not covered by the core schema in your data, instead of raising an error, the OCDS validator will simply flag up as a warning the extra fields, to check you intentionally meant to include them.

However, when you intend that more than one publisher will use particular extra fields (for example, it is being introduced to meet a national legal requirement) then it is important that these fields are documented as part of an OCDS Extension.

An extension clearly describes:

• The use case for any additional field(s) (for example, the legal requirements);
• The schema for the additional field(s) (e.g. how should new fields be formatted);
• The definition of any key terms used (e.g. titles and descriptions for each field);

We have recently released a new approach to manage extensions which involves creating a small GitHub repository that combines documentation, and the required schema for the extension.

Technical users should be able to follow the template to build a full extension. If you are not comfortable working directly with JSON schema, you can write up a description of the extension you need, and get in touch with the OCDs helpdesk who will develop this with you.

We are also working on tooling for the creation of extensions and associated JSON merge patches.

The OCDS helpdesk works with data publishers to find commonalities between local extensions, and where relevant, to propose a ‘standard extension’ that can be used across different countries and contexts, and considered for inclusion in the core of the OCDS in the long-run.

Translating the whole standard

If the standard is not yet available in your language, it is possible to propose a new translation of the schema and documentation.

Simple get in touch with data@open-contracting.org to ask for a new language to be set-up on the Transifex platform used to manage translations.

This provides an online interface to step through translations, which can then be used to generate versions of the documentation, and mapping documents in your language.

We are currently exploring the best process for review of translations. There is a discussion thread on that issue here.

Documentation, documentation, documentation

Whatever you do to localise the OCDS – one of the most important things is to provide clear documentation. You might set-up a local page on your website with links to the main standard documentation, and details of the localisations that have taken place.

It’s also important to share updates with the wider community, through the Standard issue tracker, and the standard-discuss mailing list. Without this, there is a chance that you might be duplicating work that others have already undertaken, or missing out on insights from other projects around the world. We’re smarter together!