OCDS to OC4IDS mapping¶

This page provides guidance and documents a mapping from OCDS fields and codes to OC4IDS fields and codes. The organization of the mapping tables reflects the structure of the CoST IDS.

The CoST IDS sets out a number of disclosure requirements under the heading of "information for disclosure upon request," also known as "reactive disclosure." You can disclose these elements proactively using OC4IDS. Separate tables are provided for project-level and process-level reactive disclosures.

Guidance¶

Command-line tool and reference implementation¶

OC4IDS Kit's convert-from-ocds command is a command-line tool and reference implementation for converting OCDS data to OC4IDS format.

convert-from-ocds covers most mappings in the following categories:

project-level identification
project-level preparation
process-level procurement

However, convert-from-ocds does not cover all mappings, nor does it perform currency conversions. Mappings that convert-from-ocds does not cover are shown in italics.

Mapping codelists¶

Mappings that depend on the specific classification or codelist used in the OCDS data are not documented in detail, as they can differ by publisher. For example, mapping to the OC4IDS projectSector codelist.

Alternative mappings¶

Some mappings offer alternatives in case the primary mapping isn't available. For example, for OCDS data in which planning.project.title isn't available, you can set the project title based on the tender.title.

In order to provide analysts with additional context, some alternative mappings copy additional fields which don't appear in OC4IDS schema. You ought to remove these fields if you plan to publish your OC4IDS data.

OCDS extensions¶

Some mappings use fields from OCDS extensions. In these cases, the names of extensions are noted in parentheses; where possible, alternative mappings are provided that use only fields from the core OCDS schema.

Handling conflicts and duplicates¶

Implementations of the mapping ought to give consideration to:

OCDS data that contains fields that differ between contracting processes but map to a single field in OC4IDS: for example, where planning.project.title differs for two contracting processes that relate to the same project, but OC4IDS has a single title field at the project level.
OCDS data that contains multiple Organization objects with the same .role that map to a single field in OC4IDS: for example, where a contracting process has two Organizations with the 'procuringEntity' role, but OC4IDS has a single .summary.tender.procuringEntity field at the contract level.
Checking for duplicates when copying objects from OCDS. For example, checking whether an Organization object has already been copied before copying it again.
Handling identifier conflicts when copying objects from OCDS. For example, where two contracting processes both contain a Document with the same .id.

Read the convert-from-ocds transformation notes to learn about how OC4IDS Kit handles the above scenarios.

Handling multiple currencies¶

Some mappings involve converting values in OCDS, which can be in different currencies, to a base currency.

Implementations which include multiple currencies ought to give consideration to value dating. One approach is to use the compiled release's date.

Mapping¶

Project level¶

Identification¶

CoST IDS element	CoST IDS draft definition	Mapping from OCDS
Project owner	Name of the sponsoring Government department	Check the `/parties` array for `Organization` objects with 'buyer' in `/roles`. Copy each object to the `parties` array in OC4IDS and add 'publicAuthority' to its `.roles`. If there is more than one public authority, do not set `publicAuthority.name` and `publicAuthority.id`; otherwise, set them to the public authority's `.name` and `.id`.
Sector	Develop a list of sectors relevant to country e.g. housing, transport, energy, water etc.	Copy the `Classification` object from `/planning/project/sector` (Project extension) to the `additionalClassifications` array. Additionally, map the classification used in OCDS to the projectSector codelist and publish one or more values in `sector`.
Subsector	Develop a subset for each sector e.g. Transport could be subdivided into national highway, local road, railway, port, airport etc.	Copy each `Classification` object from the `/planning/project/additionalClassifications` array (Project extension) to the `additionalClassifications` array.
Project name	Specify the project name	Set `title` to the value of `/planning/project/title` (Project extension); if not available, optionally use `/tender/title`.
Project Location	Briefly specify location of the project	Copy each `Location` object from `/planning/project/locations` (Project extension) to the `locations` array; if not available, optionally use `/tender/items/deliveryLocation` or `/tender/items/deliveryAddress` (Location extension). Add an `.id` to each `Location` object.
Purpose	Specify the socio-economic purpose of the project	Set `purpose` to the value of `/planning/rationale`; if not available, optionally check the `/planning/documents` array for `Document` objects with `/type` set to 'needsAssessment' and copy each object to the `documents` array.
Project description	Concise description and details of the project	Set `description` to the value of `/planning/project/description` (Project extension); if not available, optionally use `/tender/description`.

Preparation¶

CoST IDS element	CoST IDS draft definition	Mapping from OCDS
Project Scope (main output)	Main outputs from the project that are being taken forward into construction (type, quantity, unit)	Check the `/planning/documents` array for `Document` objects with `/type` set to 'projectScope' and copy each object to the `documents` array; if not available, optionally copy `Item` objects from `/tender/items` to `contractingProcesses.summary.tender.items` and copy `Milestone` objects from `/tender/milestones` to `contractingProcesses.summary.tender.milestones`.
Environmental impact	Briefly describe the environmental impacts and mitigation measures for this project e.g. impacts on flora, fauna & woodlands, areas of natural beauty, carbon emissions etc. and mitigation measures e.g. pollution control, low carbon solutions, sustainable timber etc.	Check the `/planning/documents` array for `Document` objects with `/type` set to 'environmentalImpact'. Copy each object to the `documents` array.
Land and settlement impact	State the amount of land and property that was acquired for the project e.g. 25km2 land, and related impacts e.g. archaeological issues (moved Saxon burial site), local/indigenous settlements (relocated 5 indigenous villages of 500 villagers each), impacts on local businesses e.g. (30 business properties purchased).	Check the `/planning/documents` array for `Document` objects with `/type` set to 'landAndSettlementImpact'. Copy each object to the `documents`.
Contact details	Postal and electronic address of the Project Owner	Check the `/parties` array for `Organization` objects with `/role` set to 'buyer'. Copy each object to the `parties` array in OC4IDS and add 'publicAuthority' to its `.roles`.
Funding sources	Name the funding organization(s)/sources of funding	Check the `/parties` array for `Organization` objects referenced in `/planning/budgetBreakdown/sourceParty` (Budget breakdown extension), copy each object to the `parties` array in OC4IDS and add 'funder' to its `.roles`; if not available, check the `/parties` array for parties with 'funder' in `/roles` and copy each object to the `parties` array in OC4IDS.
Project Budget	Specify the projected costs/allocated budget for the project (currency and amount). The budget includes land / property acquisition, environmental mitigation measures, H&S provisions, client, consultant & contractor costs, VAT etc.	If the project has only one contracting process, set `budget.amount` and `budget.currency` in OC4IDS to the values of `/budget/amount` and `/budget/currency`. If the project has more than one contracting process and the value of `/budget/currency` is the same in all contracting processes, set `budget.amount` in OC4IDS to the sum of the value of `/budget/amount` in each contracting process and set `budget.currency` in OC4IDS to the value of `/budget/currency`. Otherwise, convert the values of `/budget/amount` in each contracting process to a base currency, set `budget.amount` in OC4IDS to the sum of the converted values and set `budget.currency` in OC4IDS to the base currency.
Project budget approval date	Date project budget was authorized	Check the `/planning/documents` array for `Document` objects with `/type` set to 'budgetApproval' and copy each object to the `documents` array; if not available, optionally check `/planning/milestones` for `Milestone` objects with `/type` set to 'approval' and set `budget/approvalDate` to the value of `/dateMet`.

Project completion¶

CoST IDS element	CoST IDS draft definition	Mapping from OCDS
Project status (current)	The current stage of the project. Select from identification, preparation, construction, completion, completed or cancelled.	Infer from `/tag` of most recent release.
Project completion cost	State projected or actual completion cost (currency and amount)	Infer projected cost from `/contracts/value` and infer actual cost from `/contracts/implementation/finalValue` (Contract completion extension); if not available, infer from total of `/contracts/implementation/transactions/value`.
Completion date	State projected or actual completion date	Infer from `/contracts/implementation/endDate` (Contract completion extension); if not available, infer from `/contracts/period/endDate`.
Project Scope at completion (projected)	Indicate projected or actual scope of project. Aim is to show if the completed project scope differs from the original project scope. Specify main outputs (type, quantity, unit)	Check `/planning/documents` for documents with `/type` set to `projectScope` or infer from `/contracts/items` or `/contracts/implementation/milestones`.
Reasons for project changes	Summary of primary reasons for any changes in scope, time and cost	Infer from `/contracts/implementation/endDateDetails` and `/contracts/implementation/finalValueDetails` (Contract completion extension); if not available, infer from `/contracts/amendments`.
Reference to audit and evaluation reports	Reference to publicly available technical and financial audits	Check the `/contracts/implementation/documents` array for `Document` objects with `/type` set to 'finalAudit'. Copy each such object to the `documents` array.

Reactive disclosures¶

Identification and preparation¶

CoST IDS element	Description	Mapping from OCDS
Multi-year programme & Budget	A detailed breakdown of the budget by period and/or participating funders.	Copy the contents of `/planning/budget/budgetBreakdown` in each contracting process to `budget.BudgetBreakdown`.
Project brief or Feasibility study	Documentation of feasibility studies carried out for this contracting process or project, providing information on net benefits or costs of the proposed goods, works or services.	Check the `/planning/documents` array for `Document` objects with `.documentType` set to ‘feasibilityStudy’ and copy each object to the `documents` array.
Environmental and social impact assessment	Environmental impact assessment Documentation of assessments of the environmental impacts (e.g. impacts on flora, fauna & woodlands, areas of natural beauty, carbon emissions etc.) and mitigation measures (e.g. pollution control, low carbon solutions, sustainable timber etc.) for this contracting process or project. Social impact assessment Documentation of assessments of the intended and unintended social consequences of this project, and documentation of mitigation measures for those social consequences. Social impacts are changes that affect people, directly or indirectly (e.g. changes to people’s way of life, culture, community, health and well-being etc.).	Check the `/planning/documents` array for `Document` objects with `.documentType` set to ‘environmentalImpact’ or ‘socialImpact’ and copy each object to the `documents` array.
Resettlement and compensation plan	Documentation of the procedures and actions to mitigate adverse effects, compensate losses, and provide development benefits to people and communities affected by the contracting process or project.	Check the `/planning/documents` array for `Document` objects with `.documentType` set to ‘resettlementPlan’ and copy each object to the `documents` array.
Project officials and roles	Name and position of the highest authority in the procuring entity where the budget for this project is allocated (project owner)	Check the `/parties` array for `Organization` objects with 'procuringEntity' in `/roles`. Copy each object to the `parties` array in OC4IDS. If there is more than one procuring entity, do not set `.summary.tender.procuringEntity.name` and `.summary.tender.procuringEntity.id`; otherwise, set them to the procuring entity's `.name` and `.id`.
Financial agreement	Loan or donation agreement with financing conditions.	Check the `/planning/documents` array for `Document` objects with `.documentType` set to ‘financialAgreement’ and copy each object to the `documents` array.
Procurement plan	Documentation that sets out the basis for this particular contracting process.	Check the `/planning/documents` array for `Document` objects with `.documentType` set to ‘procurementPlan’ and copy each object to the `documents` array.
Project approval decision	Additional details about the approval of the budget.	Check the `/planning/documents` array for `Document` objects with `.documentType` set to ‘budgetApproval’ and copy each object to the `documents` array.

Completion¶

CoST IDS element	Description	Mapping from OCDS
Implementation progress reports	Planned and actual physical and financial progress over time.	Optionally, check the `/contracts/implementation` array for `Document` objects with `.documentType` set to ‘physicalProgressReport’ or ‘financialProgressReport and copy each object to the `.summary.documents` array. Optionally, copy the contents of the `/planning/forecasts` array to `forecasts` and copy the contents of the `/contracts/implementation/metrics` array to `metrics`.
Budget amendment decision	Document accrediting the approval of budget expansion or extension for this project.	Check the `/planning/documents` array for `Document` objects with `.documentType` set to ‘budgetAmendmentApproval’ and copy each object to the `documents` array.
Project completion report	A completion certificate issued by a relevant authority providing evidence that works were completed to a certain level of quality. Completion certificates might only be relevant for particular kinds of contracting processes or projects.	Check the `/contracts/implementation` array for `Document` objects with `.documentType` set to ‘projectCompletionReport’ and copy each object to the `documents` array.
Project evaluation report	Generally published at the conclusion of a project, providing a technical and financial summary of delivery	Check the `/contracts/implementation` array for `Document` objects with `.documentType` set to ‘projectEvaluation’ and copy each object to the `documents` array.
Technical audit reports	Documentation of checks that construction work has been undertaken as specified.	Check the `/contracts/implementation` array for `Document` objects with `.documentType` set to ‘technicalAuditReport’ and copy each object to the `documents` array.
Financial audit reports	Documentation of checks that a project's financial statements are correct and complete.	Check the `/contracts/implementation` array for `Document` objects with `.documentType` set to ‘financialAuditReport’ and copy each object to the `documents` array.

Process level¶

The mappings in this section relate to the contractingProcesses section of the OC4IDS schema, unless otherwise specified.

Procurement¶

CoST IDS element	CoST IDS draft definition	Mapping from OCDS
Procuring entity	Enter name of the organization carrying out the procurement	Check the `/parties` array for `Organization` objects with 'procuringEntity' in `/roles`. Copy each object to the `parties` array in OC4IDS. If there is more than one procuring entity, do not set `.summary.tender.procuringEntity.name` and `.summary.tender.procuringEntity.id`; otherwise, set them to the procuring entity's `.name` and `.id`.
Procuring entity contact details	Postal and Electronic address	Check the `/parties` array for `Organization` objects with 'procuringEntity' in `/roles`. Copy each object to the `parties` array in OC4IDS. If there is more than one procuring entity, do not set `.summary.tender.procuringEntity.name` and `.summary.tender.procuringEntity.id`; otherwise, set them to the procuring entity's `.name` and `.id`.
Contract administrative entity	Enter name of the organization carrying out the contract administrative entity if different from the Procuring Entity	Check the `/parties` array for `Organization` objects with 'administrativeEntity' in `/roles`. Copy each object to the `parties` array in OC4IDS. If there is more than one procuring entity, do not set `.summary.tender.administrativeEntity.name` and `.summary.tender.administrativeEntity.id`; otherwise, set them to the procuring entity's `.name` and `.id`.
Contract status	Select from pre-award, active or closed	Set `.summary.status` to a value from the contractingProcessStatus codelist according to the business logic in the codelist.
Procurement process	Develop a list such as International Competitive Bidding, National Competitive Bidding, Donor Procurement Rules, Framework, Direct Award	Set `.summary.tender.procurementMethod` and `.summary.tender.procurementMethodDetails`to the values of `/tender/procurementMethod` and `/tender/procurementMethodDetails` respectively.
Contract type	Develop a list such as Design, Supervision, Design & Supervision, Design & Build, Construction	Map from `/tender/items/classification` or `/tender/items/additionalClassifications` or infer from `/tender/description`.
Number of firms tendering	Number of firms who submit a tender	Set `.summary.numberOfTenderers` to the value of `/tender/numberOfTenderers`.
Cost estimate	Currency and amount of the original pre-tender estimate of the contract	Check the individual releases for the contracting process and set `.summary.tender.costEstimate` to the value of `/tender/value` in the most recent release with `/tender/status` set to 'planning'.
Contract title	The formal name of the contract	If the contracting process has only one `Contract` object in `/contracts`, set `.summary.title` to the value of the contract's `/title`; if not available and the contracting process has only one `Award` object in `/awards`, use its `/title`. Otherwise, use `/tender/title`.
Contract firm(s)	Legal name of supplier	Check the `/parties` array for `Organization` objects with 'supplier' in `/roles`. For each such object, copy it to the `parties` array in OC4IDS, add an `OrganizationReference` object to `.summary.suppliers` and set the `.name` and `.id` of the `OrganizationReference` to the `.name` and `.id` of the `Organization`.
Contract price	Currency and price at contract award	If the value of `/value/currency` is the same for all `Award` objects in `/awards`, set `.summary.contractValue.amount` to the sum of `/value/amount` in each `Award` object and set `.summary.contractValue.currency` to the value of `/value/currency`. Otherwise, convert `/value/amount` in each `Award` object to a base currency, set `.summary.contractValue.amount` to the sum of the converted values and set `.summary.contractValue.currency` to the base currency.
Contract scope of work	Main outputs from the contract e.g. detailed design, supervision, project management and or type, quantity, unit for construction	If there is more than one `Contract` object in `/contracts` or more than one `Award` object in `/awards`, set `.summary.description` to the value of `/tender/description`; if unavailable and if there is only one `Item` object in `/tender/items`, then set `.summary.description` to the value of the item's `/description`. Otherwise, if there is only one `Award` or `Contract` object with a `/description` field, set `.summary.description` to the value of the object's `/description`. Otherwise, if there is only one `Item` with a `/description` field in `/awards/items` and `/contracts/items`, set `.summary.description` to the value of the item's `/description`.
Contract start date and contract period (duration)	Enter dates and Number of weeks from contract start date to (anticipated) completion date	Set `.summary.contractPeriod.startDate` to the earliest `/contractPeriod/startDate` of all `Award` objects in `/awards` and set `.summary.contractPeriod.endDate` to the latest `/contractPeriod/endDate` of all `Award` objects in `/awards`; if not available, set `.summary.contractPeriod` to the value of `/tender/contractPeriod`.

Implementation¶

Disclosures in the implementation section of the CoST IDS relate to changes to a contract's value, duration or scope that were made after the contract was awarded.

If OCDS data is available, these changes can be determined by comparing the most recent OCDS release to a compiled release created from all prior releases (to better understand these concepts, refer to the OCDS documentation). The specific fields to monitor for changes between releases are described in the mapping table below.

In some cases, OCDS data might include an explanation of changes in the relevant amendments block. In other cases, the reason might need to be manually entered.

CoST IDS element	CoST IDS draft definition	Mapping from OCDS
Variation to contract price	Difference between the price at contract award and the current projected price	Monitor `/contracts/value` for changes. Copy `/contracts/amendments/description` to `.description` and `/date` to `.date`.
Escalation of contract price	Escalation to date of the price of materials, labour, equipment etc. due to fluctuations in inflation, currency etc.	Monitor `/contracts/value` for changes. Copy `/contracts/amendments/description` to `.description` and `/date` to `.date`.
Variation to contract duration	Difference between original duration at contract award and the current projected duration in weeks.	Monitor `/contracts/period` for changes. Copy `/contracts/amendments/description` to `.description` and `/date` to `.date`.
Variation to contract scope	Any changes between original scope at contract award and the current scope	Monitor `/contracts/description`, `/contracts/items` and `/contracts/implementation/milestones` for changes. Copy `/contracts/amendments/description` to `.description` and `/date` to `.date`.
Reasons for price changes	Summary of reasons for primary changes (e.g. variations) that then lead to changes in contract price, major price fluctuations and accumulative increase or decrease in price.	Copy `contracts/amendments/rationale` to `.rationale`.
Reasons for scope and duration changes	Summary of reasons for primary changes (e.g. variations) that then lead to changes in the scope and duration.	Copy `contracts/amendments/rationale` to `.rationale`.

Reactive disclosures¶

Procurement¶

CoST IDS element	Description	Mapping from OCDS
Contract officials and roles	Name and position of the public official in charge of administration of the contract(s).	Check the `/parties` array for `Organization` objects with 'administrativeEntity' in `/roles`. Copy each object to the `parties` array in OC4IDS. If there is more than one procuring entity, do not set `.summary.tender.procuringEntity.name` and `.summary.tender.procuringEntity.id`; otherwise, set them to the procuring entity's `.name` and `.id`.
Procurement method	Specify tendering method using the method codelist (open, selective, limited, direct).	Set `.summary.tender.procurementMethod` to the value of `/tender/procurementMethod`.
Tender documents	Documentation for potential suppliers, describing the goals of the contract (e.g. goods and services to be procured), and the bidding process.	Check the `/tender/documents` array for `Document` objects with `.documentType` set to ‘biddingDocuments’ and copy each object to the `.summary.documents` array.
Tender evaluation results	Documentation on the evaluation of the bids and the application of the evaluation criteria, including the justification for the award.	Check the `/tender/documents` array for `Document` objects with `.documentType` set to ‘evaluationReports’ and copy each object to the `.summary.documents` array.
Project design report	A record of the justification for the design approach adopted in the project, typically issued before the works start, by the consultant or firm that will supervise the works.	Check the `/planning/documents` array for `Document` objects with `.documentType` set to ‘projectDesignReport’ and copy each object to the `.summary.documents` array.

Contract¶

CoST IDS element

Description

Mapping from OCDS

Contract agreement and conditions

A copy of the signed contract. Consider providing both machine-readable (e.g. original PDF, Word or Open Document format files), and a separate document entry for scanned-signed pages where this is required.

Check the /contracts/documents array for Document objects with .documentType set to ‘contractSigned’ and copy each object to the .summary.documents array.

Registration and ownership of firms

A document issued by the relevant government registry as confirmation of the due incorporation and valid existence of the organization.

Check the /contracts/documents array for Document objects with /type set to ‘incorporationCertificate’ and copy each object to the .summary.documents array.

Check the /parties array for Organization objects with 'supplier' in /roles. For each such object, copy it to the parties array in OC4IDS, add an OrganizationReference object to .summary.suppliers and set the OrganizationReference's .name and .id to the Organization's .name and .id.

Specifications and drawings

Detailed technical information about goods or services to be provided.

Check the /contracts/documents array for Document objects with /type set to ‘technicalSpecifications’ and copy each object to the .summary.documents array.

Implementation¶

CoST IDS element	Description	Mapping from OCDS
List of variations, changes, amendments	Details of changes to the duration, price, scope or other significant features of the contracting process	Monitor the following fields for changes: `/contracts/value` `/contracts/period` `/contracts/description` `/contracts/items` `/contracts/implementation/milestones` Copy `/contracts/amendments/description` to `summary.modifications.description` and `/date` to `.summary.modifications.date`.
List of escalation approvals	Documentation of one or more approved escalations of the contract price during the project life-cycle.	Check the `/contracts/documents` and `/contracts/implementation/documents` arrays for `Document` objects with `.documentType` set to ‘escalationApprovals’ and copy each object to the `.summary.documents` array.
Quality assurance reports	Documentation identifying deficiencies in designs, specifications, standards, methods, procedures and practices, and identifying best practices.	Check the `/contracts/documents` and `/contracts/implementation/documents` arrays for `Document` objects with `.documentType` set to ‘qualityAssuranceReport’ and copy each object to the `.summary.documents` array.
Disbursement records or payment certificates	A list of the spending transactions made against this contract and/or a document certifying that the work specified on a supplier's estimate or invoice is complete and that payment to the supplier is approved	Copy the contents of the `/contracts/implementation/transactions` array to `.summary.transactions`. Check the `/contracts/implementation/documents` array for `Document` objects with `.documentType` set to ‘paymentCertificate’ and copy each object to the `.summary.documents` array.
Contract amendments	A legal document that changes or adds to the terms of an existing contract.	Check the `/contracts/documents` array for `Document` objects with `.documentType` set to ‘contractAmendment’ and copy each object to the `.summary.documents` array.