Open Contracting for Infrastructure Data Standards Toolkit¶
The Open Contracting Data Standard (OCDS) is already used to describe millions of procurement processes around the world relating to goods, services and public works. The CoST Infrastructure Data Standard (CoST IDS) has been used to guide what data and information ought to be disclosed at each stage of the project cycle on over 25,000 infrastructure projects.
This site describes how to combine contract level disclosures using OCDS with project-level disclosure based on the CoST IDS, in order to support scalable disclosure and monitoring of infrastructure project identification, preparation, implementation and delivery.
Trillions of dollars are spent every year on infrastructure and estimates suggest between 10 and 30% of infrastructure investment is lost through inefficiency, mismanagement and corruption. Access to better and more joined up data is essential to drive better quality, more affordable and more accessible infrastructure for government, citizens and business.
This Open Contracting for Infrastructure Data Standards (OC4IDS) Toolkit will show you how to:
Publish standardized data on infrastructure projects and contracts using the CoST IDS and OCDS.
Extract infrastructure contracting data from existing procurement portals.
Connect contract and project-level information using OC4IDS.
Assess published data against the CoST IDS.
Make use of data when monitoring infrastructure projects.
Contents¶
About¶
The Open Contracting Partnership, CoST - the Infrastructure Transparency Initiative - and Open Data Services Co-operative are working together to document how the Open Contracting Data Standard, and additional standardized data models, can be used to represent, share and analyze all the information necessary under the CoST Infrastructure Data Standard.
You can get involved via the issue tracker, or for more information about this work, contact Bernadine Fernz, Head of Infrastructure at the Open Contracting Partnership and/or Evelyn Hernandez, Head of Members and Affiliate Programmes at CoST.
Read more about Open Contracting and Infrastructure on the Open Contracting Partnership Blog
Background¶
The Open Contracting Data Standard is already used to describe millions of procurement processes around the world relating to goods, services and public works.
CoST, the Infrastructure Transparency Initiative, has identified 67 key items of information that ought to be pro-actively and reactively disclosed for public works projects in order to support stakeholders to monitor these infrastructure projects, and to carry out assurance activities.
These 67 elements cover both project information and contract information for the planning, preparation, procurement and implementation phases of an infrastructure project and its associated contracting processes.
A lot of the information identified by CoST may be captured through contracting processes:
Contracts are issued for planning, design and preparation work;
Contracts are issued for construction of infrastructure;
Contracts are issued for monitoring construction implementation.
When open contracting principles and practices are put in place, data about these contracting processes, and documents associated with them, ought to be openly available in standard formats.
By linking existing open contracting disclosure (and ensuring key fields and documents are provided) with project-level information, new opportunities for data-driven infrastructure project monitoring are unlocked.
Theory of change and work plan¶
This project, running from June 2018 through to March 2019, has the following theory of change.
The technical development work plan consists of the following four components:
Supply and demand research (June/July 2018) - exploring the extent to which existing open contracting data can be used to understand major infrastructure projects and fulfill reporting requirements of the CoST Infrastructure Data Standard.
Project identifier research (June/July 2018) - identifying the opportunities to bring together data on projects through use of unique project identifiers.
Schema and guidance development (July - September 2018) - providing a clearly documented approach to the use of the core Open Contracting Data Standard (and extensions if appropriate) to provide the proactive disclosures needed by CoST, and outlining implementation models for this.
Implementation resources (October 2018 - February 2019) - creating guidance for implementers seeking to deploy the open contracting data standard for infrastructure projects
Getting started¶
The regular disclosure of structured data can greatly enhance the transparency and accountability of publicly funded infrastructure projects.
Publishing standardized data makes using data easier, for example to compare data across projects. It also supports the development of reusable tools and methodologies.
What is a project?¶
In the context of OC4IDS, the term ‘project’ refers to an infrastructure project, defined as the development of a set of infrastructure assets in a specified location, generally the responsibility of a single procuring entity and budget authority: for example, a highway overpass or a university campus.
An infrastructure project can stand alone (e.g. a new hospital), or can form part of a wider investment project or programme of work (e.g. a new rail station, as part of an extension to a railway line).
Within an infrastructure project, a procuring entity can initiate multiple contracting processes for the project design, construction or supervision.
Tip
The term "project" is used in many contexts to mean different things. In OC4IDS, the term "project" only refers to an infrastructure project and not to an investment project, investment program, or budget code.
What is the scope of OC4IDS?¶
OC4IDS describes how to structure and format the disclosures described by the CoST IDS.
The CoST IDS is a best practice framework for disclosure on infrastructure projects. It describes what information to disclose to support monitoring of infrastructure projects.
The CoST IDS and OC4IDS cover project-level data and summary contracting process data.
What is project-level data?¶
Project-level data relates to the project as a whole and covers the following stages:
Identification - the decision to develop a project within the budget and programme of a project owner.
Preparation - the feasibility study, environmental and social impact assessment, general scoping of the project, establishing the packaging and procurement strategy, preliminary statutory requirements on environmental and land impacts, and the resulting budget authorization.
Implementation - covers the procurement and implementation of the planning, design and works according to the procurement strategy.
Completion - covers the handover of the assets and close-out activities with details of the final scope, cost, and delivery time.
What is summary contracting process data?¶
Summary contracting process data relates to the contracts used to deliver the project and covers the following stages:
Procurement - the procuring entity and process; contract type and status; number of bidders; cost estimate and contract price; suppliers; scope of work and start date and duration of the contract.
Implementation - variations to contract price, duration and scope, and reasons for these changes.
CoST recommends disclosing data on contracts for the design, construction and supervision of a project and any other significant contract outsourced by the procuring entity.
How is OC4IDS structured?¶
The top-level of the OC4IDS data model is used for project-level data, covering the identification, preparation and completion stages of a project.
Each project in OC4IDS can have many related contracting processes.
The contractingProcesses array can be used to provide a summary of the procurement and implementation of each contracting process related to the project.
The contractingProcesses/modifications section can be used to record information on changes to each contracting process.
How does detailed contracting data fit in?¶
Alongside project-level data and documents, monitoring an infrastructure project can largely involve monitoring the contracts used to deliver it, particularly any primary construction contracts.
It is possible to use contracting data to identify infrastructure projects for monitoring. It can also be used to monitor projects for changes to costs, timescales and scope. Each change you identify can be recorded in the summary contracting process data section of OC4IDS, along with an explanation.
Where detailed contracting data is published using the Open Contracting Data Standard, the contractingProcesses/releases array in OC4IDS can be used to link to OCDS releases, recording each update to a contracting process.
OCDS is used to disclose detailed data on contracting processes for goods, works and services. It covers all stages of a contracting process: planning, initiation, award, contract and implementation.
OCDS data can be used to identify and monitor infrastructure projects. It can also be used to produce OC4IDS data. Converting OCDS data to OC4IDS data can reduce the amount of manual data entry necessary for infrastructure project monitoring.
Tool
OC4IDS Kit's convert-from-ocds command can be used to generate an OC4IDS file from OCDS data about the contracting processes related to an infrastructure project.
How do PPPs fit in?¶
Infrastructure projects can be procured in different ways, including through Public-Private Partnerships.
Where data on PPP projects is published using OCDS for PPPs, the contractingProcesses/releases array in OC4IDS can be used to link to OCDS for PPPs releases.
Why use OC4IDS?¶
Publishing your data using OC4IDS means that it can be compared with data from other publishers and supports the development of reusable tools for analysis of infrastructure project data. OC4IDS data can also be linked with other critical documents such as project pipelines and public sector budgets to allow for the tracking of the project from its identification to completion across different government institutions.
OC4IDS is designed to help you collect well-structured data, comparable across contexts, and with all the fields needed to make sure the data is clear and unambiguous. It has been designed to integrate with existing open contracting data sources, but also to work in cases where structured open contracting data is not available.
When can I use OC4IDS?¶
OC4IDS can be used in the following scenarios:
Publishing structured data from an infrastructure transparency portal
OC4IDS describes a standardized format for publishing structured data on infrastructure projects.
Read the guidance on publishing data from an infrastructure transparency portal.
Designing a new infrastructure transparency portal
OC4IDS describes the best practice information you ought to collect and disclose to support infrastructure project monitoring.
Using OCDS data for whole life-cycle infrastructure project monitoring
OC4IDS can be used to:
Join up OCDS data published about contracts related to an infrastructure project
Capture and record data about the project a contract relates to
Record a list of changes to a contracting process and reasons for those changes
Read the guidance on using data from procurement systems for infrastructure project monitoring.
Collecting data on infrastructure projects using a spreadsheet
The OC4IDS schema can be used to generate a spreadsheet template for collecting data.
Designing other data collection tools
OC4IDS provides definitions for fields and codelists which can be used to collect consistent data.
Publishing data that complies with the CoST IDS
OC4IDS describes how to structure and format the disclosures described by the CoST IDS.
Review the CoST IDS mapping to learn how to publish each element of the CoST IDS using OC4IDS.
Are you ready to start using OC4IDS?
Complete the OC4IDS scoping template and share it with the OC4IDS helpdesk.
Schema reference¶
The Open Contracting for Infrastructure Data Standard (OC4IDS) provides a common approach for the disclosure of structured data on infrastructure projects and their related contracting processes.
OC4IDS comprises a schema and codelists. The schema sets out the fields, structure, data types and validation rules for OC4IDS data. Some schema fields refer to codelists, to limit and standardize the possible values of the fields, in order to promote data interoperability.
The schema can be explored using the schema browser and can be downloaded here. The schema is expressed using JSON Schema, draft 4.
OC4IDS data must be published as part of a project package, which serves as a container for data on multiple projects and adds important metadata about the data publication.
The OC4IDS schema reuses many fields and structures from the Open Contracting Data Standard.
Schema browser¶
The OC4IDS schema can be explored using the browser below.
Click on schema elements to expand the tree, or use the '+' icon to expand all elements. Use { } to view the underlying schema for any section. Required fields are indicated in bold.
Schema reference¶
This page presents the fields in the OC4IDS schema in tables with additional information in paragraphs. Required fields are indicated in the Required column.
For fields that reference a sub-schema, a link is provided to a table with details of the sub-schema. To see how the fields and sub-schemas fit together, consult the schema browser.
Examples are provided for each table, showing how to represent the fields in the table in JSON format. For more information on the examples, see examples.
Project¶
The top-level object in OC4IDS is a project.
A project is defined as:
The development of a set of infrastructure assets in a specified location, generally the responsibility of a single procuring entity and budget authority: for example, a highway overpass or a university campus.
A project's fields include:
Metadata, such as the project's
title,descriptionandstatus.Budget data, which describes the projected costs or allocated budget for the project.
Data about the parties (organizations and other participants) involved in the project.
Links to documents relating to the project, such as needs assessments and project evaluations.
Data about contracting processes for different aspects of the project, such as design, construction and supervision.
Completion data, such as the final scope, duration and costs for the project.
Each project has the following fields.
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
Identifier or Reference |
An identifier for this infrastructure project. The identifier must be globally unique and must begin with a registered project identifier prefix. For more information, see the project identifier guidance. |
|||
updated |
string |
date-time |
||
Last updated |
The date on which project-level information was last updated. This should not be changed when constituent contracting processes information changes, unless this project-level data has been updated as a result, or to provide explanations or justifications for those changes. |
|||
title |
string |
|||
Project title |
The title of the project. |
|||
description |
string |
|||
Project description |
A description of this project. This should usually be no longer than a single paragraph. |
|||
status |
string |
|||
Status |
The current phase or status of this project, from the projectStatus codelist. |
|||
period |
object |
|||
Project period |
The period over which this project is planned to run. This may be updated during the preparation phase as information becomes available to more accurately specify anticipated start and end dates, but should not be updated during the implementation or completion phases. The planned completion date of the project should be provided in See Period |
|||
sector |
array[string] |
|||
Project sector |
One or more values from the projectSector codelist representing the sector(s) this project relates to. More detailed sector breakdown information can be provided using the pattern [sector].[subsector]. Where subsector codes are used the parent code should also be included, e.g. |
|||
purpose |
string |
|||
Project purpose |
The socioeconomic purpose of this project. |
|||
additionalClassifications |
array[Classification] |
|||
Additional classifications |
One or more additional project classifications may be provided to describe the social or economic focus of the project. This classification may take place against a locally developed codelist, or a globally established codelist. See Classification |
|||
type |
string |
|||
Project type |
Whether the primary focus of this project is the construction of a new asset or the rehabilitation or replacement of an existing asset, from the projectType codelist. |
|||
relatedProjects |
array[Related project] |
|||
Related projects |
References to projects related to the same set of infrastructure assets as this project. For example, a project for the replacement of a bridge might reference the earlier project for its initial construction. See RelatedProject |
|||
assetLifetime |
object |
|||
Asset lifetime |
The anticipated lifetime of the asset after this project is completed. This may be provided as either explicit dates or an estimated duration. See Period |
|||
locations |
array[Delivery Location] |
|||
Project locations |
Information about the location where a project is taking place. One or more locations may be provided, or the location may be described in a number of different ways, such as a point location for the central location of construction, and a gazetteer entry to describe the region where the project is taking place. See Location |
|||
budget |
object |
|||
Total project value |
Specify the projected costs or allocated budget for the infrastructure project (currency and amount). This cost should include land and property acquisition, environmental mitigation measures, health and safety provisions, client, consultant and contractor costs, as well as applicable taxes. Where this value includes costs incurred directly by the project owner or other agencies, which are not subject to procurement, then this value is likely to be higher than the sum of all the linked contracting processes. To indicate the profile of a budget over time, or the budget coming from different sources, the extended budgetBreakdown section may be used. |
|||
budget/description |
string |
|||
Description |
A short free-text description of the budget that will fund the project. This may be used to provide human-readable information on: the budget category for the project and/or the nature and source of the budget allocation (e.g. conditional, confirmed, or any official authorizations given to the budget allocation). |
|||
budget/amount |
object |
|||
Amount |
The projected costs or allocated budget for the project. See Value |
|||
budget/requestDate |
string |
date-time |
||
Request date |
The date on which the project budget was requested. |
|||
budget/approvalDate |
string |
date-time |
||
Approval date |
The date on which the project budget was approved. Where documentary evidence for this exists, it may be included among the project documents with the documentType set to 'budgetApproval'. |
|||
budget/budgetBreakdown |
array[Detailed budget breakdown] |
|||
Budget breakdown |
A detailed breakdown of the budget by period and/or participating funders. See BudgetBreakdown |
|||
forecasts |
array[Metric] |
|||
Forecasts |
Forecast metrics for this project, such as planned physical or financial progress over time. See Metric |
|||
parties |
array[Organization] |
|||
Parties |
Information on the parties (organizations, economic operators and other participants) who are involved in the project and their roles, e.g. buyer, procuring entity, supplier etc. Organization references elsewhere in the schema are used to refer back to this entries in this list. See Organization |
|||
publicAuthority |
object |
|||
Public authority |
The name and identifier of the public authority that is tendering and contracting the project. The full details of the entity should be added to the project-level |
|||
documents |
array[Document] |
|||
Documents |
Documentation related to this project. Entries may include a short text summary (plain text, HTML or Markdown), and/or a link to a specific document accessible on the web. At the identification phase, a project scope (documentType: projectScope) is expected. At the preparation phase, environmental impact (documentType: environmentalImpact) and land and settlement impact (documentType: landAndSettlementImpact) documentation is expected. During implementation, procurement documents should be shared at the contracting process level, but key documents may also be provided here. At the completion phase, final audit (documentType: finalAudit) and evaluation (documentType: projectEvaluation) reports and documents are expected. See Document |
|||
contractingProcesses |
array[Contracting process] |
|||
Contracting processes |
A single project may have a number of related contracting processes (design, construction, monitoring etc.). Project-level data should contain (a) an index of those contracting process; (b) the latest summary information about them; (c) a change history with explanations for any major modifications to contract duration, price or scope. Where OCDS data is published on each contracting process, a link should be provided to each available release of OCDS data (e.g. to each notice or updated notice), and this OCDS data may be used to automatically populate the summary information. |
|||
metrics |
array[Metric] |
|||
Metrics |
Actual metrics for this project, such as the actual physical or financial progress over time. See Metric |
|||
completion |
object |
|||
Completion |
This information is provided at project completion, and reflects the final timing and values relating to the project. The reason for any variation (not already explained) between the anticipated project scope, period and value should be detailed. |
|||
completion/endDate |
string |
date-time |
||
End date |
The actual completion date for the project (compare with the endDate in project period). |
|||
completion/endDateDetails |
string |
|||
End date details |
Details related to the endDate. This may be a justification for the project's completion date being different than in the original project. |
|||
completion/finalValue |
object |
|||
Final value |
The total cost of this project at completion (compare with project budget). See Value |
|||
completion/finalScope |
string |
|||
Final scope |
A short description of the final scope of the project at completion. |
|||
completion/finalScopeDetails |
string |
|||
Final scope details |
A reason, explanation or justification for any variation between the anticipated scope (compare to the projectScope document) and the final scope at completion. If appropriate, additional details may be included in the documents section, with a title indicating that these documents will describe and differences between the planned and completed scope of work. |
|||
language |
[string] |
|||
Language |
The default language of the data using either two-letter ISO639-1, or extended BCP47 language tags. The use of lowercase two-letter codes from ISO639-1 is recommended. |
|||
Sub-schemas¶
This section lists each sub-schema in the OC4IDS schema. Sub-schemas are parts of the schema that are represented as objects in OC4IDS data. Some sub-schemas are referenced from multiple places in the schema.
ContractingProcess¶
ContractingProcess is defined as:
Within OC4IDS, a contracting process provides both summary information, and a log of changes over time, either manually curated, or automatically generated through linked OCDS releases.
This sub-schema is referenced by the following properties:
Each ContractingProcess has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
Identifier |
An identifier for this contracting process. If this contracting process has been assigned an Open Contracting Identifier (OCID) by an external platform (e.g. national procurement system), that OCID must be recorded here. If information about this contracting process has been entered manually, or from a non-OCDS system, then an identifier may be created by the system data is entered into. |
|||
summary |
object |
|||
Summary |
Summary information about a contracting process, including a log of changes over time. |
|||
releases |
array[Release] |
|||
Linked releases |
The information known about a contracting process changes over time, both as new information becomes available, and as changes are made (such as amendments to scope and value). In the OCDS, each new update of information is known as a 'release'. This section provides space to record a link to each available release. See LinkedRelease |
|||
ContractingProcessSummary¶
ContractingProcessSummary is defined as:
Summary information about a contracting process and any modifications to it.
Summary information can be manually entered and the
modificationslist can be used to manually record a log of changes, with the date and details of each modification.Where OCDS data is available, most summary fields can be derived from OCDS releases, although the exact method to derive data might vary between implementations; and modifications can be identified by comparing a new release to previous releases to check for relevant changes, with the release identifier recorded in
modifications.
This sub-schema is referenced by the following properties:
Each ContractingProcessSummary has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
ocid |
string |
|||
Open Contracting Identifier |
If this contracting process has been assigned an Open Contracting Identifier (OCID) by an external platform (e.g. national procurement system), that OCID must be recorded here. Otherwise this field should be omitted. |
|||
externalReference |
string |
|||
External reference |
If this contracting process is identified by some external reference number it may be recorded here. |
|||
nature |
array[[string]] |
|||
Nature |
Whether this contracting process relates to the design, construction and/or supervision of the project, from the contractNature codelist. More than one value may be provided if the contract is for both design and construction, or both design and supervision, etc. |
|||
title |
string |
|||
Title |
The formal name of this contracting process. Once set, this should not normally by changed. |
|||
description |
string |
|||
Description |
The description should summarize the purpose of this contract and the initial scope of the work to be carried out under the contract. |
|||
status |
string |
|||
Status |
The status of this contracting process. Drawn from the contractingProcessStatus codelist. |
|||
tender |
object |
|||
Tender |
The activities undertaken in order to enter into a contract. |
|||
tender/procurementMethod |
string |
|||
Procurement method |
Specify tendering method using the method codelist (open, selective, limited, direct). |
|||
tender/procurementMethodDetails |
string |
|||
Procurement method details |
Additional detail on the procurement method used. This field should be used to record an agreed list of procurement process types, such as: International Competitive Bidding, National Competitive Bidding, Donor Procurement Rules, Framework or Direct Award. |
|||
tender/costEstimate |
object |
|||
Cost estimate |
The pre-tender estimated value of the contracting process. See Value |
|||
tender/costEstimate/amount |
[number] |
|||
Amount |
Amount as a number. |
|||
tender/costEstimate/currency |
[string] |
|||
Currency |
The currency of the amount, from the closed currency codelist. |
|||
tender/numberOfTenderers |
number |
|||
Number of tenderers |
The number of parties who placed a bid during this contracting process. |
|||
tender/tenderers |
array[Organization reference] |
|||
Tenderers |
All parties who submit a bid on a tender. More detailed information on bids and the bidding organization can be provided using the bid extension in a linked OCDS release. |
|||
tender/tenderers/0/name |
[string] |
|||
Organization name |
The name of the party being referenced. This must match the name of an entry in the parties section. |
|||
tender/tenderers/0/id |
string |
|||
Organization ID |
The id of the party being referenced. This must match the id of an entry in the parties section. |
|||
tender/procuringEntity |
object |
|||
Procuring entity |
The name and identifier of the procuring entity responsible for this contracting process. The full details of the entity should be added to the project-level |
|||
tender/procuringEntity/name |
[string] |
|||
Organization name |
The name of the party being referenced. This must match the name of an entry in the parties section. |
|||
tender/procuringEntity/id |
string |
|||
Organization ID |
The id of the party being referenced. This must match the id of an entry in the parties section. |
|||
tender/administrativeEntity |
object |
|||
Administrative entity |
The name and identifier of the entity responsible for contract administration if this is different from the procuring entity. The full details of the entity should be added to the project-level |
|||
tender/administrativeEntity/name |
[string] |
|||
Organization name |
The name of the party being referenced. This must match the name of an entry in the parties section. |
|||
tender/administrativeEntity/id |
string |
|||
Organization ID |
The id of the party being referenced. This must match the id of an entry in the parties section. |
|||
suppliers |
array[Organization reference] |
|||
Suppliers |
The name and identifier for each supplier for this contracting process. The full details of each supplier should be added to the project-level |
|||
contractValue |
object |
|||
Contract value |
The initial value of the contract. Changes to the initial value of the contract should be recorded in See Value |
|||
contractPeriod |
object |
|||
Contract period |
The initial duration of the contract. Changes to the initial duration of the contract should be recorded in See Period |
|||
finalValue |
object |
|||
Final value |
This should be provided when the contracting process is complete. This can be derived from the sum of See Value |
|||
documents |
array[Document] |
|||
Documents |
Additional documentation about this contracting process may be provided here, including reports and evaluations produced through a monitoring process, or links to web pages where further information about this process can be found. Where OCDS releases are published, further documents can be found by looking at the published releases. See Document |
|||
modifications |
array[Modification] |
|||
Modifications |
Details of changes to the duration, price, scope or other significant features of the contracting process should be logged here. See Modification |
|||
transactions |
array[Transaction information] |
|||
Transactions |
The spending transactions made against this contracting process. See Transaction |
|||
LinkedRelease¶
LinkedRelease is defined as:
A release of data represents the information known or updated at a particular point in time.
This sub-schema is referenced by the following properties:
Each LinkedRelease has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
ID |
A unique identifier for this update of information. This should be taken from the OCDS |
|||
tag |
array[string] |
Required |
||
Release tag |
One or more values from the releaseTag codelist used to indicate the information contained in this release, and the stage of the contracting process it represents. This should be filled from the OCDS |
|||
date |
string |
date-time |
Required |
|
Date |
The effective date of this release/update. This should be filled from the OCDS |
|||
url |
string |
uri |
Required |
|
URL |
A URL (web link) to a release package containing the OCDS release, if available. |
|||
Modification¶
Modification is defined as:
Contains a structured description of any changes, along with a free text justification.
This sub-schema is referenced by the following properties:
Each Modification has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
Identifier |
A local identifier for this modification. |
|||
date |
[string] |
date-time |
||
Date |
The date this modification was recorded. |
|||
description |
[string] |
|||
Description |
Details of the modification. This may be free text, or may be generated automatically and provide a structured description of the change. |
|||
rationale |
[string] |
|||
Rationale |
A summary of the reasons which have led to this modification to the originally planned scope, period or value. |
|||
type |
[string] |
|||
Type |
A value from the modificationType codelist, indicating whether the modification relates to the duration, value, scope or other aspect of the contract. |
|||
releaseID |
[string] |
|||
Release ID |
The identifier for the OCDS release this modification relates to. The referenced release should appear in the list of linked releases for this contracting process. |
|||
oldContractValue |
object |
|||
Old contract value |
Contract value before the modification, taking into account any prior modifications. See Value |
|||
newContractValue |
object |
|||
New contract value |
Contract value after the modification. See Value |
|||
oldContractPeriod |
object |
|||
Old contract period |
Contract period before the modification, taking into account any prior modifications. See Period |
|||
newContractPeriod |
object |
|||
New contract period |
Contract period after the modification. See Period |
|||
Period¶
Dates MUST be expressed using a full ISO 8601 date-time including a timezone. E.g.:
2018-09-18T11:26:04+01:00
Where the source system does not contain time information, a judgment ought to be made as to the relevant time to attach (e.g. start of the day; end of the working day etc.).
Period is defined as:
Key events during a project or contracting process may have a known start date, end date, duration, or maximum extent (the latest date the period can extend to). In some cases, not all of these fields will have known or relevant values.
This sub-schema is referenced by the following properties:
Each Period has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
startDate |
[string] |
date-time |
||
Start date |
The start date for the period. When known, a precise start date must be provided. |
|||
endDate |
[string] |
date-time |
||
End date |
The end date for the period. When known, a precise end date must be provided. |
|||
maxExtentDate |
[string] |
date-time |
||
Maximum extent |
The period cannot be extended beyond this date. This field can be used to express the maximum available date for extension or renewal of this period. |
|||
durationInDays |
[integer] |
|||
Duration (days) |
The maximum duration of this period in days. A user interface can collect or display this data in months or years as appropriate, and then convert it into days when storing this field. This field can be used when exact dates are not known. If a startDate and endDate are set, this field, if used, should be equal to the difference between startDate and endDate. Otherwise, if a startDate and maxExtentDate are set, this field, if used, should be equal to the difference between startDate and maxExtentDate. |
|||
Classification¶
Classification is defined as:
A classification consists of at least two parts: an identifier for the list (scheme) from which the classification is taken, and an identifier for the category from that list being applied. It is useful to also publish a text label and/or URI that users can draw on to interpret the classification.
This sub-schema is referenced by the following properties:
Each Classification has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
scheme |
string |
|||
Scheme |
The scheme or codelist from which the classification code is taken, using the open classificationScheme codelist. |
|||
id |
string |
|||
ID |
The classification code taken from the scheme. |
|||
description |
[string] |
|||
Description |
A textual description or title for the classification code. |
|||
uri |
[string] |
uri |
||
URI |
A URI to uniquely identify the classification code. |
|||
Location¶
Location is defined as:
The location where activity related to this project will be delivered, or will take place. A location may be described using a geometry (point location, line or polygon), a gazetteer entry, an address, or a combination of these.
This sub-schema is referenced by the following properties:
Each Location has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
Identifier |
A local identifier for this location, unique within the array this location appears in. |
|||
description |
[string] |
|||
Description |
A name or description of this location. This might include the name(s) of the location(s), or might provide a human-readable description of the location to be covered. |
|||
geometry |
object |
|||
Geometry |
We follow the GeoJSON standard to express basic location information, using longitude, latitude, and optional elevation values in the WGS84 (EPSG:4326) projection. A point location can be identified by geocoding a delivery address. For concession licenses, or other contracts covering a polygon location which is not contained in a known gazetteer, polygon and multi-polygon can be used. |
|||
geometry/type |
[string] |
|||
Type |
The type of GeoJSON Geometry Objects being provided. To provide longitude, latitude, and optional elevation, use 'Point', and enter an array of [longitude, latitude] or [longitude, latitude, elevation] as the value of the coordinates field: e.g. [-122.085, 37.42]. |
|||
geometry/coordinates |
array[[number, array]] |
|||
Coordinates |
The relevant array of points, e.g. [longitude, latitude] or [longitude, latitude, elevation], or a nested array of points, for the GeoJSON geometry being described. The longitude and latitude must be expressed in decimal degrees in the WGS84 (EPSG:4326) projection. |
|||
gazetteer |
object |
|||
Gazetteer |
Identifiers from a gazetteer (a geographical index or directory) for the location. |
|||
gazetteer/scheme |
[string] |
|||
Gazetteer scheme |
The identifier of the gazetteer. The |
|||
gazetteer/identifiers |
array[[string]] |
|||
Identifiers |
An array of one or more codes drawn from the gazetteer indicated by the |
|||
uri |
[string] |
|||
URI |
A URI to a further description of the activity location. This might be a human-readable document with information on the location, or a machine-readable description of the location. |
|||
address |
object |
|||
Address |
A physical address where works will take place. See Address |
|||
Value¶
Value is defined as:
Financial values should be published with a currency attached.
This sub-schema is referenced by the following properties:
Each Value has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
amount |
[number] |
|||
Amount |
Amount as a number. |
|||
currency |
[string] |
|||
Currency |
The currency of the amount, from the closed currency codelist. |
|||
Organization¶
Organization is defined as:
A party (organization)
This sub-schema is referenced by the following properties:
Each Organization has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
name |
[string] |
|||
Common name |
A common name for this organization or other participant in the contracting process. The identifier object provides a space for the formal legal name, and so this may either repeat that value, or may provide the common name by which this organization or entity is known. This field may also include details of the department or sub-unit involved in this contracting process. |
|||
id |
string |
|||
Entity ID |
The ID used for cross-referencing to this party from other sections of the release. This field may be built with the following structure {identifier.scheme}-{identifier.id}(-{department-identifier}). |
|||
identifier |
object |
|||
Primary identifier |
The primary identifier for this organization or participant. Identifiers that uniquely pick out a legal entity should be preferred. Consult the organization identifier guidance for the preferred scheme and identifier to use. See Identifier |
|||
additionalIdentifiers |
array[Identifier] |
|||
Additional identifiers |
A list of additional / supplemental identifiers for the organization or participant, using the organization identifier guidance. This can be used to provide an internally used identifier for this organization in addition to the primary legal entity identifier. See Identifier |
|||
address |
object |
|||
Address |
An address. This may be the legally registered address of the organization, or may be a correspondence address for this particular contracting process. See Address |
|||
contactPoint |
object |
|||
Contact point |
Contact details that can be used for this party. See ContactPoint |
|||
roles |
array[string] |
|||
Party roles |
The party's role(s) in the project, using the open partyRole codelist. |
|||
people |
array[Person] |
|||
People |
People associated with, representing, or working on behalf of this organization in respect of this project. See Person |
|||
OrganizationReference¶
OrganizationReference is defined as:
The id and name of the party being referenced. Used to cross-reference to the parties section
This sub-schema is referenced by the following properties:
Each OrganizationReference has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
name |
[string] |
|||
Organization name |
The name of the party being referenced. This must match the name of an entry in the parties section. |
|||
id |
string |
|||
Organization ID |
The id of the party being referenced. This must match the id of an entry in the parties section. |
|||
Address¶
The address sub-schema re-uses fields from schema.org and vCard. In the event source data cannot be broken down into these parts, data should contain at least a streetAddress and postalCode.
When working with data, users ought to be aware that addresses might not always be broken down using all the fields the schema provides.
Address is defined as:
An address.
This sub-schema is referenced by the following properties:
Each Address has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
streetAddress |
[string] |
|||
Street address |
The street address. For example, 1600 Amphitheatre Pkwy. |
|||
locality |
[string] |
|||
Locality |
The locality. For example, Mountain View. |
|||
region |
[string] |
|||
Region |
The region. For example, CA. |
|||
postalCode |
[string] |
|||
Postal code |
The postal code. For example, 94043. |
|||
countryName |
[string] |
|||
Country name |
The country name. For example, United States. |
|||
ContactPoint¶
ContactPoint is defined as:
A person, contact point or department to contact in relation to this contracting process.
This sub-schema is referenced by the following properties:
Each ContactPoint has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
name |
[string] |
|||
Name |
The name of the contact person, department, or contact point, for correspondence relating to this project. |
|||
email |
[string] |
|||
The e-mail address of the contact point/person. |
||||
telephone |
[string] |
|||
Telephone |
The telephone number of the contact point/person. This should include the international dialing code. |
|||
faxNumber |
[string] |
|||
Fax number |
The fax number of the contact point/person. This should include the international dialing code. |
|||
url |
[string] |
uri |
||
URL |
A web address for the contact point/person. |
|||
BudgetBreakdown¶
For more information about this sub-schema, see the OCDS Budget Breakdown extension documentation. BudgetBreakdown can also be extended further to include budget classifications data following the pattern described in the OCDS Budgets and Spend extension.
BudgetBreakdown is defined as:
This section allows a detailed budget breakdown to be expressed, covering multiple budget sources and multiple periods
This sub-schema is referenced by the following properties:
Each BudgetBreakdown has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
Identifier |
An identifier for this particular budget entry. |
|||
description |
[string] |
|||
Description |
A short free text description of this budget entry. |
|||
amount |
object |
|||
Amount |
The value of the budget line item. See Value |
|||
approvalDate |
string |
date-time |
||
Approval date |
The date on which this budget entry was approved. Where documentary evidence for this exists, it may be included among the project documents with |
|||
uri |
[string] |
uri |
||
Linked budget information |
A URI pointing directly to a machine-readable information about this budget entry. |
|||
period |
object |
|||
Budget period |
The period covered by this budget entry. See Period |
|||
sourceParty |
object |
|||
Source party |
An organization reference, linking to the entry in the |
|||
Document¶
Document is defined as:
Links to, or descriptions of, external documents can be attached at various locations within the standard. Documents can be supporting information, formal notices, downloadable forms, or any other kind of resource that ought to be made public as part of full open contracting.
This sub-schema is referenced by the following properties:
Each Document has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
ID |
A local, unique identifier for this document. This field is used to keep track of multiple revisions of a document through the compilation from release to record mechanism. |
|||
documentType |
[string] |
|||
Document type |
A classification of the document described, using the open documentType codelist. |
|||
title |
[string] |
|||
Title |
The document title. |
|||
description |
[string] |
|||
Description |
Where a link to a full document is provided, the description should provide a 1 - 3 paragraph summary of the information the document contains, and the Line breaks in text (represented in JSON using |
|||
url |
[string] |
uri |
||
URL |
This should be a direct link to the document or web page where the information described by the current documentType exists. |
|||
datePublished |
[string] |
date-time |
||
Date published |
The date on which the document was first published. This is particularly important for legally important documents such as notices of a tender. |
|||
dateModified |
[string] |
date-time |
||
Date modified |
Date that the document was last modified |
|||
format |
[string] |
|||
Format |
The format of the document, using the open IANA Media Types codelist (see the values in the 'Template' column), or using the 'offline/print' code if the described document is published offline. For example, web pages have a format of 'text/html'. |
|||
language |
[string] |
|||
Language |
The language of the linked document using either two-letter ISO639-1, or extended BCP47 language tags. The use of lowercase two-letter codes from ISO639-1 is recommended unless there is a clear user need for distinguishing the language subtype. |
|||
pageStart |
[string] |
|||
Page start |
When the information referenced exists within a large document, indicate the first page on which it can be found. This should refer to the printed page number, not the page number reported by software applications. |
|||
pageEnd |
[string] |
|||
Page end |
When the information referenced exists within a large document, indicate the last page on which it can be found. This should refer to the printed page number, not the page number reported by software applications. |
|||
accessDetails |
[string] |
|||
Access details |
A description of any special arrangements needed to access this document, for example: registering for access, paying a fee, or visiting a location to inspect the document. |
|||
author |
[string] |
|||
Author |
The names of the authors of the document. |
|||
Identifier¶
Use of stable official organization identifiers can help join up data between systems.
Organization identifiers should be constructed by collecting an official company (or government body) registration number for the organization, and then finding the org-id.guide list code for the list this identifier is taken from to use in the scheme field.
For example, if identifying a company in Colombia, look up its identifier in the Unified Commercial and Social Registry and use the list code CO-RUE.
Identifier is defined as:
A unique identifier for a party (organization).
This sub-schema is referenced by the following properties:
Each Identifier has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
scheme |
[string] |
|||
Scheme |
Organization identifiers should be taken from an existing organization identifier list. The scheme field is used to indicate the list or register from which the identifier is taken. This value should be taken from the Organization Identifier Scheme codelist. |
|||
id |
string |
|||
ID |
The identifier of the organization in the selected scheme. |
|||
legalName |
[string] |
|||
Legal Name |
The legally registered name of the organization. |
|||
uri |
[string] |
uri |
||
URI |
A URI to identify the organization, such as those provided by Open Corporates or some other relevant URI provider. This is not for listing the website of the organization: that can be done through the URL field of the Organization contact point. |
|||
Metric¶
Metric is defined as:
Metrics are used to set out forecast and actual metrics targets for a project: for example, planned and actual physical and financial progress over time.
This sub-schema is referenced by the following properties:
Each Metric has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
Identifier |
An identifier for this metric. In some cases this may be drawn from a codelist of metrics required for this type of contracting process or project, or in other instances may be an arbitrary identifier. |
|||
title |
[string] |
|||
Title |
The title of this metric |
|||
description |
[string] |
|||
Description |
A short description of the metric. This may include short details of measurement methods. |
|||
observations |
array[Observation] |
|||
Observations |
An array of target or actual values for this metric. See Observation |
|||
Observation¶
Observation is defined as:
An actual or target observation. Observations should include either a value (for financial metrics) or measure (for other metrics).
This sub-schema is referenced by the following properties:
Each Observation has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
Identifier |
A local identifier for this specific observation. This may be an arbitrary identifier, or could be a composite of the metric identifier, and the date and other dimensions of this observation. |
|||
period |
object |
|||
Period |
The period over which this observation is measured. See Period |
|||
value |
object |
|||
Value |
For financial metrics, the value of this forecast, target or actual observation. See Value |
|||
measure |
[string, number] |
|||
Measure |
For non-financial metrics, the measure of this forecast, target or actual observation. Measures may be provided as free text or numerical values. |
|||
unit |
object |
|||
Unit |
Unit |
|||
unit/name |
[string] |
|||
Unit name |
The name of the unit. |
|||
unit/scheme |
[string] |
|||
Scheme |
The list from which units of measure identifiers are taken. Use of the scheme 'UNCEFACT' for the UN/CEFACT Recommendation 20 list of "Codes for Units of Measure Used in International Trade" is recommended. |
|||
unit/id |
string |
|||
ID |
The identifier from the codelist referenced in the schema property. For example, with UNCEFACT, this is the value of the 'Common Code' column. From this identifier, applications can look-up the human readable name or symbol for this unit of measure. |
|||
unit/uri |
[string] |
uri |
||
URI |
If the scheme used provide a machine-readable URI for this unit of measure, this can be given. |
|||
dimensions |
object |
|||
Dimensions |
Any number of dimensions can be recorded within this object. Dimensions names should follow the camelCase conventions of OCDS. |
|||
notes |
[string] |
|||
Notes |
Any notes on this observation. This may include clarifying information. |
|||
Person¶
Use this object when you need to disclose the details of people associated with, representing or working on behalf of an organization involved in the project.
Person is defined as:
A natural person.
This sub-schema is referenced by the following properties:
Each Person has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
Identifier |
A local identifier for this person. |
|||
name |
string |
|||
Name |
The full name of the person. |
|||
jobTitle |
string |
|||
Job title |
The job title of the person (for example, Financial Manager). |
|||
Transaction¶
A spending transaction related to a contracting process.
Transaction is defined as:
A spending transaction related to the contracting process. Draws upon the data models of the Fiscal Data Package and the International Aid Transparency Initiative and should be used to cross-reference to more detailed information held using a Fiscal Data Package, IATI file, or to provide enough information to allow a user to manually or automatically cross-reference with some other published source of transactional spending data.
This sub-schema is referenced by the following properties:
Each Transaction has the following fields:
Title |
Description |
Type |
Format |
Required |
|---|---|---|---|---|
id |
string |
Required |
||
ID |
A unique identifier for this transaction. This identifier should be possible to cross-reference against the provided data source. For IATI this is the transaction reference. |
|||
source |
[string] |
uri |
||
Data source |
Used to point either to a corresponding Fiscal Data Package, IATI file, or machine or human-readable source where users can find further information on the budget line item identifiers, or project identifiers, provided here. |
|||
date |
[string] |
date-time |
||
Date |
The date of the transaction |
|||
value |
object |
|||
Value |
The value of the transaction. See Value |
|||
payer |
object |
|||
Payer |
An organization reference for the organization from which the funds in this transaction originate. |
|||
payee |
object |
|||
Payee |
An organization reference for the organization which receives the funds in this transaction. |
|||
uri |
[string] |
uri |
||
Linked spending information |
A URI pointing directly to a machine-readable record about this spending transaction. |
|||
Codelist reference¶
Some schema fields refer to codelists, to limit and standardize the possible values of the fields, in order to promote data interoperability.
Codelists are either be open or closed. Closed codelists are intended to be comprehensive; for example, the currency codelist covers all currencies in the world. Open codelists are intended to be representative, but not comprehensive.
Publishers must use the codes in the codelists, unless no code is appropriate. If no code is appropriate and the codelist is open, then a publisher may use a new code outside those in the codelist. If no code is appropriate and the codelist is closed, then a publisher should instead create an issue in the OC4IDS GitHub repository.
Extending open codelists
If you use new codes outside those in an open codelist, please create an issue in the OC4IDS GitHub repository, so that the codes can be considered for inclusion in the codelist.
For more information on open and closed codelists, refer to the Open Contracting Data Standard codelists documentation.
OCDS codelists¶
OC4IDS reuses some codelists from the Open Contracting Data Standard and its extensions:
Closed codelists¶
ContractingProcessStatus¶
ContractNature¶
ProjectStatus¶
Projects with a status of 'completed' may be displayed in a list of archived projects.
ProjectType¶
Open codelists¶
DocumentType¶
ModificationType¶
PartyRole¶
ProjectSector¶
classificationScheme¶
Packaging data¶
OC4IDS data must be published as part of project package, which acts as a container for data on multiple projects and adds important metadata about the publication. The project package schema describes this container.
You can view an interactive version of the project package schema below (requires JavaScript) or download it here.
Click on schema elements to expand the tree, or use the '+' icon to expand all elements. Use { } to view the underlying schema for any section.
Changelog¶
[X.X.X] - YYYY-MM-DD¶
Documentation¶
#344 - add implementation models guidance.
#343 - add Flatten Tool command to implementation guidance.
#328 - fix reference tables so that "Required" column is correct for arrays (e.g. LinkedRelease.tag is now correctly marked as "Required")
#355 - use correct normative and non-normative keywords in documentation.
#362 - add guidance on publishing in your own language.
#371 - add link to field level mapping template tutorial.
#370 - improve schema reference documentation and integrate worked example.
Schema¶
Codelists¶
Other¶
[0.9.3] - 2021-10-07¶
Documentation¶
#210:
update the 'Mapping from OCDS' column to reflect the logic used in convert-to-oc4ids.
remove references to the PPP profile, reference individual extensions instead.
update project identification mapping for sector.
replace reference to Budget and projects extension with Projects extension.
remove reference to 'publicAuthority' code from OCDS mapping.
#216 - update CoST IDS & OCDS mapping documentation to separate the OC4IDS to CoST IDS mapping and the OCDS to OC4IDS mapping.
#217 - remove repeated 'OCDS:' in mapping documentation.
#220 - add reactive disclosure elements to CoST IDS & OCDS mapping documentation.
#246 - correct link and wording to Project extension in project identifiers guidance.
#268, #269 replace 'finalAudit' with 'technicalAuditReport' and 'financialAuditReport' in mapping.
#278 - add reactive disclosures to worked example.
#304 - update blank OC4IDS file with schema changes, and add project package.
#316 - update wording around worked example file, add link to blank.json.
#260 - improve the clarity of the Getting Started documentation.
#329 - fix incorrect references to
document.typein the CoST IDS & OCDS mapping.#339 - update link to CoST IDS on mapping page.
#382 - update email addresses for support.
Schema¶
#277 - add
forecastsandmetrics, which can be used to publish implementation progress reports.#317 - update fields shared with OCDS for PPPs 1.0.0-beta3 and OCDS 1.1.5.
#264 - add a field and class for natural persons.
#273 - add
contractingProcesses/summary/transactions, which can be used to publish disbursement records.#284 - restore
classification/urifield.#223 - add stricter validation rules to catch empty arrays, objects and strings.
Codelists¶
#317 - update codes shared with OCDS for PPPs 1.0.0-beta3 and OCDS 1.1.5.
documentType codelist¶
Changed:
#261 Update description of 'feasibilityStudy' code to include "project".
#267 Update description of 'completionCertificate' code to include "project".
Added:
#262 'socialImpact'
#263 'resettlementPlan'
#265 'financialAgreement'
#266 'budgetAmendmentApproval'
#268 'technicalAuditReport'
#269 'financialAuditReport'
#271 'escalationApproval'
#272 'qualityAssuranceReport'
#274 'incorporationCertificate'
#275 'contractAmendment'
#270 'designReport'
#273 'paymentCertificate'
Removed:
[0.9.2] - 2020-06-29¶
Documentation¶
#96 - add guidance on providing project identifiers in OCDS data.
#120 - add list of registered project identifier prefixes to documentation.
#124 - clarify guidance on project identifier prefixes.
#131 - replace 'owner' with 'publicAuthority' in mapping.
#133 - improve clarity of 'what is a project' in getting started section.
#136 - add project identifier prefix to example file.
#143 - update worked example page to describe project package, use non-normative keywords, and edit for clarity.
#143 - add data user guide page.
#145 - re-order codelist reference page, refer to OCDS and extension documentation for codelists that are shared.
#146 - add 'publicAuthority' role to example file.
#218 - add link to CoST guidance note on OGP commitments.
#211 - update description of 'publicAuthority' role.
Schema¶
Project package schema¶
OC4IDS project schema¶
#127 - remove the requirement that linked OCDS releases must be provided in release packages containing only one release. Remove recommendation that OCDS releases are cached from schema and add guidance on caching releases from unreliable sources to implementation guidance.
#132 - add a publicAuthority organization reference field.
#139 - update properties of fields in common with OCDS to version 1.1.4.
#140 - update the description of
project/periodto clarify that this field should be used to provide the planned start and end dates during the preparation phase, for comparison with the actual completion date for the project.#141 - clarify that
contractingProcesses/summary/descriptionis for the contract's initial scope of work.#141 - remove incorrect guidance about other fields from
contractingProcesses/summary/modifications.#153 - add project/relatedProjects array.
#154 - add
.requestDatefield toproject/budgetto record the date of the budget request for the project.#156 - fix the description of
completion/endDateDetailsto refer to the end date of the project, not that of the contract.#157 - fix spelling and grammar issues.
#158 - make
contractingProcesses/releases/tagan array, not a string (bugfix).#160 - describe the components of
project/id, and link to guidance.#161 - removed
contractingProcesses/summary/ocidbecause it duplicatescontractingProcesses/id.#182 - update validation properties to enforce unique items in arrays and minimum length on required string fields.
Codelists¶
[0.9.1] - 2019-06-17¶
Changed¶
Add changelog.
Update ocds-babel to 0.1.0.
Fixed¶
Correct schema URLs in schema files.
[0.9.0-beta] - 2019-03-19¶
This changelog entry indicates notable changes since the alpha-2 development release of OC4IDS, it is not intended to be a complete list of changes.
In addition to the specific changes to schema and codelists noted below:
Various refinements and clarifications were made to schema and codelist descriptions.
Guidance on mapping values from OCDS was moved from the schema to the IDS and OCDS mapping section of the documentation.
Documentation was expanded and restructured.
Packaging¶
Add project package schema. OC4IDS data must be published as part of a project package.
Schema updates¶
sector- use projectSector open codelist.ContractingProcess- add requiredidfield.LinkedRelease- makeidrequired.variations- rename tomodifications.Location- add requiredidfield.
New codelists¶
projectSectorcodelist - add codelist for project sector.
Codelist updates¶
projectStatus codelist - replace 'construction' with 'implementation'.
variationType codelist - rename to modificationType.
partyRole codelist - add OC4IDS codes mentioned in schema and mapping:
funder
administrativeEntity
partyRole codelist - add codes from OCDS partyRole codelist:
buyer
procuringEntity
supplier
tenderer
partyRole codelist - remove PPP-specific codes:
bidder
qualifiedBidder
preferredBidder
privateParty
leadBank
lender
equityInvestor
consortiaMember
interestedParty
grantor
disqualifiedBidder
socialWitness
otherWitness
notary
documentType codelist - remove PPP-specific codes:
financeAdditionality
pppModeRationale
riskComparison
discountRate
equityTransferCaps
financeArrangements
guaranteeReports
grants
servicePayments
landTransfer
assetTransfer
revenueShare
otherGovernmentSupport
tariffMethod
tariffReview
tariffs
tariffIllustration
handover
financialStatement
documentType codelist - add codes from OCDS documentType codelist:
contractNotice
completionCertificate
procurementPlan
biddingDocuments
contractArrangements
physicalProgressReport
financialProgressReport
hearingNotice
marketStudies
eligibilityCriteria
clarifications
assetAndLiabilityAssessment
winningBid
complaints
contractAnnexe
subContract
projectPlan
billOfQuantity
bidders
conflictOfInterest
debarments
illustration
submissionDocuments
contractSummary
cancellationDetails
Registered project prefixes¶
The list below shows all registered prefixes. You can download the list as CSV.
Data validation¶
OC4IDS uses a permissive schema. It does not enforce strong technical validation requirements on data, other than some structural rules and data type rules (dates, numbers and strings).
The fact that data validates against the schema cannot be used to make any judgment about the quality of that data.
Extending the schema¶
The schema does not restrict the use of additional objects or fields. As a result, publishers of data are free to add extra details to their data.
No formal extensions mechanism currently exists for OC4IDS. However, the extensions mechanism from the Open Contracting Data Standard should be used as a reference model if such a mechanism is required in the future.
Implementation guidance¶
Project identifiers¶
A project identifier is a unique identifier for an infrastructure project. Every project in OC4IDS has a project identifier in the id field.
Project identifiers can be used to join up data published at different times or from different systems; for example, including a project identifier in contracting data makes it possible to join up data on the design, construction and supervision contracts within a single infrastructure project.
Local project identifiers in contracting data¶
A common need is to access data about the contracting processes related to an infrastructure project. When contracting systems use consistent identifiers to refer to infrastructure projects, this becomes possible. An example use case is automatically checking which projects have related contracting data, and then manually filtering projects for further scrutiny, monitoring or data collection.
Project identifiers in contracting data ought to be locally unique; this means that across all contracting data from a particular system or country, each project identifier refers to exactly one infrastructure project.
There are different approaches to including project identifiers in contracting data, with the best solution depending on the context of an implementation:
Include a free-text field for project identifiers in procurement systems and work with officials entering procurement information to make sure this is populated according to a defined pattern.
Free-text entry of project identifiers can lead to data quality issues; for example, project identifiers can be mistyped or two groups can accidentally choose to use the same identifier for different projects.
However, this approach allows some data quality checks to be run; for example, checking that all the contracting processes over a certain value from a given agency have a project identifier, and that the identifier matches a defined pattern or a local list of project identifiers.
This approach also enables the joining up of data on multiple contracting processes relating to a single infrastructure project.
Establish a national project register managed by a central agency and integrated into procurement systems. In this model, officials entering procurement information would look up and use the project's identifier from the national register. If the project is not yet in the register, they would request its addition.
This approach supports more comprehensive and effective data quality checks; for example, project identifiers entered into procurement systems can be immediately checked against the project register to prevent errors in data entry ("validation at source").
A central register can ensure that project identifiers are locally unique, and more robustly supports use cases like identifying projects lacking related contracts.
However, this approach requires political will and technical capacity to establish the central register and integrate it into procurement systems, and it requires an appropriate central actor to manage it.
Project identifiers in OCDS¶
In OCDS, the identifier for the individual infrastructure project to which a contracting process is related ought to be disclosed using the planning/project/id field, introduced in the Project extension.
The planning/budget/projectID field in OCDS ought not be used to disclose the identifier for an individual infrastructure project. This field is used to disclose the identifier for a project in the national budget to which the contracting process is related. Since projects in the national budget might include many individual infrastructure projects, it is necessary to disclose these identifiers separately.
Project identifier prefixes¶
Project identifiers in OC4IDS need to be globally unique; this means that, across all the data of all OC4IDS publishers, each project identifier refers to exactly one infrastructure project.
If local project identifiers are available in existing systems or data, these ought to be re-used to create globally unique project identifiers for use in OC4IDS. Otherwise, if local project identifiers are not available, publishers are allowed to assign local identifiers to projects in the new systems used to generate OC4IDS data.
To make local project identifiers globally unique for use in OC4IDS, a publisher requests a project identifier prefix from the OC4IDS Helpdesk. The publisher needs to then use the assigned prefix in all its project identifiers, according to following structure: [project identifier prefix]-[local project identifier].
For example: CoST Honduras requests a project identifier prefix from the OC4IDS Helpdesk. The OC4IDS Helpdesk assigns the randomly-generated prefix oc4ids-qu8r7p. CoST Honduras then creates globally unique project identifiers, by combining its assigned prefix with each local project identifier from its SISOCS system.
Project identifier prefixes are typically unique to each publisher. However, multiple publishers in the same jurisdiction can collaboratively decide to use the same project identifier prefix: for example, if multiple agencies are independently responsible for different projects. As such, the prefix serves to identify a series of infrastructure projects (to which many publishers can contribute), rather than to identify one publisher.
Request a project identifier prefix
To request a project identifier prefix, please e-mail data@open-contracting.org with the name of your organization and a brief description of your OC4IDS implementation.
You can view the list of registered prefixes.
Publishing data from an infrastructure transparency portal¶
OC4IDS can be used to publish standardized open data on infrastructure projects where information is already collected and disclosed through infrastructure transparency portals, whether by CoST Multi-Stakeholder Groups, government agencies or civil society organizations.
Publishing standardized open data reduces barriers to use of data and supports the development of reusable tools and methodologies for working with data on infrastructure projects.
If you also collect detailed data on contracting processes, this can be published using the Open Contracting Data Standard (OCDS).
Linking to related information
Infrastructure transparency portal creators ought to consider what other types of information might be important to citizens, in addition to the in depth scrutiny related information in OC4IDS.
For example, Highways England provides links to congestion and traffic restriction information alongside information on roads projects.
Getting started¶
Some of the following steps might require support from a technical expert. You can also contact the OC4IDS Helpdesk (data@open-contracting.org) for guidance.
(1) Make a commitment¶
Consider making or advocating for a public commitment to publish standardized open data using OC4IDS and OCDS.
Commitments are important to help align implementation with the goals of publishing open data and to help overcome technical, political or bureaucratic barriers to publication.
Applications to join CoST can be used to make a commitment or if your country is a member of the Open Government Partnership, your National Action Plan is another great place to start.
Refer to the OCDS implementation journey for information and resources about making commitments related to OCDS. Refer to the CoST and OGP guidance note for guidance on making OGP commitments related to CoST.
(2a) Map project-level data and summary contracting process data¶
Map existing data structures to OC4IDS.
Tip
The OC4IDS Field-Level Mapping Template can be used to document your mapping.
To learn how to use the mapping template, see the tutorial.
Your mapping might identify:
Gaps in your data where data in OC4IDS is not currently collected or disclosed in your system. Use OC4IDS as a guide to the information that is important to users and consider whether your system and business processes could be updated to collect and publish additional information.
Gaps in OC4IDS where data is collected by your system but doesn't map to OC4IDS. Rather than being excluded from your publication, such information ought to be included as additional fields in your data. Refer to extending the schema for information on including additional fields in your data.
(2b) Map detailed contracting process data¶
If you collect detailed data on contracting processes, refer to the OCDS implementation journey for information and resources about mapping and publishing your contracting data using OCDS.
Include an identifier for the infrastructure project that each contracting process relates to in your OCDS data, following the guidance on project identifiers in OCDS.
(3) Build your data, systems and processes¶
Create an OC4IDS JSON file for each project your system has information on and use the OC4IDS Data Review Tool to check that the files are structurally correct against OC4IDS.
Tip
You can use a blank example OC4IDS JSON file to get started.
If you are also publishing contracting data using OCDS, create an OCDS release each time the data about a contracting process changes and use the OCDS Data Review Tool to check your OCDS releases.
Make sure you have systems and/or business processes in place to keep the data you produce up to date.
(4) Publish your data¶
Publish your OC4IDS JSON fields (as either static files or via an API) at a stable URL, such as:
https://{your-website}/opendata/projects/{project-id}.json
If you are also publishing contracting data using OCDS, publish each new release of data as a JSON file at a stable URL such as:
https://{your-website}/opendata/contracting/{ocid}/{release-id}.json
Make sure your project-level files include links in the contractingProcesses/releases section to each related OCDS file.
To make your data easier to access, consider providing:
A regularly updated bulk file of all your data for download
Flattened (spreadsheet or CSV) representations of your data
A page on your website with details of how users can access your data
Tip
You can use Flatten Tool to convert OC4IDS data between JSON and CSV/Excel formats. For example, the following command converts the example project package to Excel format:
flatten-tool flatten -f xlsx example.json --root-id=id --root-list-path=projects
Refer to the OCDS documentation for more information on providing data in multiple formats.
Implementation models¶
OC4IDS implementation involves combining data on infrastructure projects and contracting processes. This guidance describes some examples of implementation models used by OC4IDS publishers. It is not an exhaustive list, but it can be used to inform your implementation.
Sources of data can include infrastructure transparency portals, procurement systems and project administration systems. OC4IDS implementation can also involve using contracting data published in OCDS format.
In this guidance we discuss options for the collection of data, the flow of data between systems and the publication of data. For more information about the design of the system architecture to support this process, see the System Architectures guidance in the OCDS documentation.
Standalone infrastructure transparency portal¶
In this model, procuring entities enter project and contract level data directly into an infrastructure transparency portal. The portal publishes project data and summary contracting process data in OC4IDS format. CoST Honduras uses this model in SISOCS, as does CoST West Lombok in INTRAS.
The main benefit of this approach is that it is relatively simple because it does not involve integrating data from different systems. The downside of this approach is that it can increase the data entry burden on procuring entities who might also need to enter contracting process data into a separate procurement system.
Integrated infrastructure transparency portal and procurement system¶
In this model, procuring entities enter project data directly into an infrastructure transparency portal, whilst contracting process data is imported from an existing procurement system. The portal then publishes project data and summary contracting process data in OC4IDS format.
For each project, the infrastructure transparency portal needs to join up the project data entered by the procuring entity with contracting data imported from the procurement system. If the contracting data includes project identifiers, this process can be automated. Otherwise, procuring entities need to manually associate contracts with projects.
CoST Ukraine uses this model in its infrastructure transparency portal, which imports data from Prozorro, the national procurement system. Project identifiers are not captured in Prozorro so procuring entities manually match contracts to projects.
The main benefit of this approach is reducing the data entry burden on procuring entities, who need only enter contracting data in one system. When the data from the procurement system includes project identifiers, the burden is further reduced since the transparency portal can match contracts to projects without manual intervention. The downsides of this approach are increased complexity of the transparency portal and the potential need for development work on the procurement system to enable access to its data.
When the procurement system publishes OCDS data, there are two further benefits:
OC4IDS Kit’s convert-from-ocds command can be used to generate OC4IDS data using the OCDS data as an input, reducing the amount of software development needed.
The published OC4IDS data can be linked to the OCDS data from the procurement system, allowing users to dig deeper into detailed data about the contracting processes related to each project.
Nuevo León’s Infraestructura Abierta platform implements a similar model:
Internal systems collect, combine and publish project and contracting data using OC4IDS and OCDS.
The Infraestructura Abierta platform consumes the OC4IDS and OCDS data and provides an interface for users to explore and analyze the data.
For more information on Nuevo León’s implementation, read the Technical case study.
Standalone procurement system¶
In this model, rather than implementing a separate infrastructure transparency portal, an existing procurement system is extended to collect project data. Procuring entities enter project data and contracting data directly into the procurement system and associate contracts with projects. The system publishes project data and summary contracting data in OC4IDS format and detailed contracting data in OCDS format. The OC4IDS data meets the needs of users with an interest in infrastructure projects and the OCDS data meets the needs of users with an interest in all types of contracting process.
Uganda’s Public Procurement and Disposal of Public Assets Authority uses this model in its Government Procurement Portal.
The main benefit of this model is that it does not require the development of a separate infrastructure transparency portal. The downside of this model is that it might involve significant changes to legacy procurement systems.
Using data from procurement systems for infrastructure monitoring¶
An increasing number of procurement portals now publish data using the Open Contracting Data Standard (OCDS). When OCDS is implemented in full, then:
Each contracting process is given a unique identifier (
ocid);Every update to that process, from planning through to implementation, ought to be published under the same
ocid, and in a structured open data format;It ought to be possible to download bulk data in OCDS format, or access this structured data via an API.
Even when an OCDS publisher does not provide data for every stage of the contracting process, it is still possible to use OCDS data to:
Discover contracts related to infrastructure projects;
Track these contracting processes, including changes to tenders, details of suppliers selected, and, in some cases, details of contract modifications.
Getting started¶
The following steps might require support from a technical expert. You can also contact the OC4IDS Helpdesk (data@open-contracting.org) for guidance.
(1) Evaluate the Open Contracting Data¶
Check that the data you plan to analyze is in OCDS format
Tip
You can use the OCDS Data Review Tool to check whether your data is in the correct format
Check which stages of the contracting process the data covers.
Check whether the publisher keeps a change history (multiple releases for each contracting process), or whether as a user of the data you will need to keep the change history.
(2) Identify how you will query the data¶
Some OCDS publishers provide an API that can be used to query data. Others provide access to bulk data that you can download into your own tools for querying.
Tip
If you are working with OCDS data from an unreliable source, consider caching a copy of the OCDS releases that relate to the infrastructure projects you are monitoring, and consider linking to the copies from your OC4IDS data in order to ensure they are available to users.
Tip
OCDS Kingfisher is an open source tool that can load OCDS data into a PostgreSQL database. It includes scrapers for many known OCDS data sources
(3) Develop a search strategy to discover infrastructure projects¶
Ideally, the procurement data source will include some sort of project or budget identifier fields that relate to a register of infrastructure projects.
Tip
If the procurement data you are working with is in OCDS format, refer to the guidance on project identifiers in OCDS for more information on where to find identifiers for projects.
However, where this is not the case, it might be possible to search for tenders with a particular set of item classifications, or from a particular buyer.
This might be possible by downloading and filtering spreadsheets of the data, or might involve queries written against your chosen data storage tool.
Worked example
Using the UK Contracts Finder dataset in OCDS format, and OCDS Kingfisher, we can use the following query to fetch contracting processes classified under the 'Architectural, construction, engineering and inspection services' hierarchy of the EU Common Procurement Vocabulary.
-- The following query runs against a filtered set of data in Kingfisher.
SELECT
-- The 'data' field contains the JSON representation of a contracting process. The data -> 'object' ->> 'value'
-- syntax is used to navigate this structure and select values. data -> 'tender' -> 'tenderPeriod' ->> 'endDate'
-- for example is analogous to the JSON path tender/tenderPeriod/endDate
data,
data->'buyer'->>'name' as buyer,
data->'tender'->'tenderPeriod'->>'endDate' as tenderEndDate,
EXTRACT(YEAR from cast(data->'tender'->'tenderPeriod'->>'endDate' as timestamp)) as tenderYear,
data->'tender'->>'title' as title,
data->'tender'->'value'->>'currency' as currency,
data->'tender'->'value'->>'amount' as value
-- We use a sub-query in order to select only contracting processes where there is at least one tender/item with a
-- particular classification.
FROM (
SELECT DISTINCT data from data
-- Kingfisher stores data as JSON blobs (jsonb). This expands the items array into a table we can join against.
LEFT JOIN LATERAL jsonb_array_elements(data->'tender'->'items') items on TRUE
-- All 'Architectural, construction, engineering and inspection services' have CPV codes starting with 71
WHERE items->'classification'->>'id' LIKE '71%'
) data
-- We sort by value (highest first). We cast values from the JSON before sorting.
ORDER BY cast(data -> 'tender' -> 'value' ->> 'amount' as float) DESC;
This returns over 11,000 procurement processes related to infrastructure, covering frameworks and procurements, with a value of up to £25bn a year. These processes include design work, construction and monitoring, and each needs to be reviewed to identify if it ought to be subject to monitoring.
(4) Populate project-level data¶
If your analysis of OCDS data reveals infrastructure projects to monitor, you can:
Use the information from a contracting process data to start populating a project-level disclosure;
Search for related contracts in order to link any other design, construction or monitoring contracts to this project;
Tip
When searching for related contracts, you might be looking for contracts from the same buyer, mentioning similar words or localities.
You might not be able to fill all the project-level details from the contracts, and might need to undertake additional research to find:
The project owner and name
The full scope of the project
The total project budget and cost estimates
Any environmental impact or land and settlement impact studies that have been undertaken
Tip
You can use a blank example OC4IDS JSON file to get started.
(5) Monitoring contracting process updates¶
When a publisher is using OCDS correctly, and is providing updates on a contracting process under the same ocid, you ought to be able to regularly fetch the latest data for each contracting process you are monitoring, and to compare it with the existing data you have, looking for changes.
Keep a copy each time the data changes, and if you see modifications to:
Price
Duration
Scope
check whether an adequate explanation has been given for these.
You can use OC4IDS to record each time a change is detected, and the reasons that are given for the change.
(6) Add project completion data¶
When there is evidence that a project has reached completion, it is important to further update the project-level disclosure.
If the OCDS data includes implementation data, including transactions or final spending information, then it might be possible to compare the total sum of all contract spending against the original anticipated contract spend, and overall project budget. It might also be possible to compare final contract delivery dates with originally planned dates. This can be used to identify possible modifications that are in need to explanation.
In other cases, you might need to identify other data sources (such as treasury or public spending data) that you can draw upon to check whether a project spend was as anticipated or not.
Tools and platform¶
You can use OCDS data as part of a manual monitoring process, or you can integrate OCDS into a comprehensive transparency portal.
Tools to help you with manual monitoring include:
OCDS Kingfisher - a framework for regularly fetching, storing and querying OCDS data.
OCDS Merge - a library to combine multiple releases of OCDS data into a summary (compiledRelease), and to identify changes over time (versionedRelease).
OCDS Show - a flexible framework for presenting templated views of OCDS data. Given a merged OCDS record, OCDS Show can highlight change over time.
When building an integrated tool that integrates OCDS data into infrastructure project monitoring:
The OC4IDS provides a common data structure for recording project-level information;
The CoST IDS and OCDS Mapping provides guidance on how to use OCDS data to populate project-level and contracting process summary data.
Assessing compliance with the CoST IDS¶
The CoST Infrastructure Data Standard (IDS) is a framework for disclosure which is adapted by CoST national programmes to meet their local needs. This section sets out how to use OC4IDS and OCDS to assess coverage of published data against the IDS. For example, to monitor which elements of IDS are being supplied and whether they are available for all projects or only some.
Note
It is not possible to fully automate checks of whether disclosures from a particular publisher, or disclosures about a particular project, meet the requirements of the CoST IDS. For example, a human check might be needed to determine whether documents linked to from the data contain the necessary information.
Getting started¶
The following steps might require support from a technical expert. You can also contact the OC4IDS Helpdesk (data@open-contracting.org) for guidance.
(1) Check your data formats¶
First, check that the disclosures you want to analyze are in the correct format. If they are not in the correct format, you will need to convert the data.
Project level data¶
Check whether the project-level data is published using OC4IDS
Tip
You can use the OC4IDS Data Review Tool to check that whether your data is in the correct format.
If the data isn’t published using OC4IDS, use the OC4IDS Field-Level Mapping Template to map the data to the specification and create an OC4IDS JSON file for each project.
Tip
You can use a blank example OC4IDS JSON file to get started.
Contracting data¶
Check whether the contracting data is published using OCDS.
Tip
You can use the OCDS Data Review Tool to check that whether your data is published in OCDS format.
If the contracting data is published using OCDS then use it to populate the contracting processes section of the project-level data, following the guidance on using contracting data to understand infrastructure projects.
If the data isn’t published using OCDS, use the OC4IDS Field-Level Mapping Template to map the data to the contracting processes section of OC4IDS and add the data to the OC4IDS JSON file for each project.
(2) Check which elements of IDS are disclosed¶
Use the CoST IDS Mapping to construct queries to determine which elements of the IDS are provided in the data.
For example, the CoST IDS mapping describes how the project name element of the IDS ought to be disclosed:
Project-Level: Publish as
title
Based on this description, the following pseudo code checks a folder containing OC4IDS JSON files to count the number of projects in which the project name is disclosed:
for each json file in folder
load json
if top-level "title" field exists in json and its value is not an empty string
increment project name count by 1
Data user guide¶
Publishing OC4IDS involves making choices about what projects, data and documents to include and/or exclude, and how to map existing data elements to the fields in OC4IDS.
In order for users to interpret data correctly and make effective use of it, it's important for publishers to describe these local decisions and to provide guidance to data users that includes:
the purpose of publication
how the data is generated
the data's scope and format
how the data can be reused
how the publisher can be contacted
Publishers ought to link to this data user guide from the project package's publicationPolicy field.
For more information, please refer to the OCDS publication policy guidance. For assistance in drafting a data user guide, please refer to the OCDS publication policy template.
Examples¶
This page provides examples to help you understand and implement OC4IDS. There are two examples:
Worked example¶
The worked example is a JSON file that conforms to the project package schema. It contains a single project that conforms to the project schema. You can view the complete worked example below or download the JSON file. You can also view excerpts from the worked example alongside each sub-schema in the schema reference documentation.
The worked example describes a fictional infrastructure project to upgrade a motorway in the UK with three related contracting processes. An example value is provided for each field in the schema, including:
forecastsandmetricsthat describe planned and actual physical progressmodificationsthat describe changes to the duration, scope and value of contracting processescompletiondata, describing the final end date, value and scope of the project.
Blank example¶
The blank example is a JSON file that conforms to the structure of the project schema. You can view the blank example below or download the JSON file. Field values are replaced with either:
Empty strings (
"") or empty arrays ([])The type of the field, e.g. "string" or "array"
The name of the codelist referenced by the field, e.g. "string from currency codelist"
Publishing data in your own language¶
You can publish the values of free-text fields – like title, description and parties/name – in your own language. You ought to set the language field to the language used in these free-text fields. For example:
{
"id": "1",
"title": "ตัวอย่างโครงการ",
"type": "construction",
"language": "th"
}
In order for your data to be interoperable and compatible with OC4IDS tools and methodologies:
Do not translate codes from codelists. For example, the value of the
typefield needs to be a code from the ProjectType codelist, like 'construction'. You cannot translate 'construction' to 'การก่อสร้าง':{ "id": "incorrect-example-1", "type": "การก่อสร้าง", }
Do not translate field names (object keys). For example, you cannot translate
titletoชื่อ:{ "id": "incorrect-example-2", "ชื่อ": "ตัวอย่างโครงการ", }
The fields whose values can be translated are listed in the internationalization lookup table.
Translating headers in spreadsheets/CSVs¶
In order to ease access for non-English speakers, instead of using the field names as column headers (which are always in English), you can use the field titles.
The titles are currently available in English and Spanish. If you would like to translate the titles to your own language, please contact the OC4IDS Helpdesk.
For example, this CSV excerpt uses field titles from the Spanish translation of OC4IDS:
Identificador o Referencia |
Título del Proyecto |
|---|---|
1 |
proyecto de ejemplo |
You can use Flatten Tool to generate files with translated field titles. For example, this command converts the example OC4IDS JSON file to XLSX format, using field titles from the Spanish schema:
flatten-tool flatten -s https://standard.open-contracting.org/infrastructure/0.9/es/project-schema.json -f xlsx --use-titles --root-id=id --root-list-path=projects example.json
Publishing in multiple languages¶
To publish data in multiple languages, follow the above guidance and publish a separate project package for each language. You need to ensure that the values of id fields are consistent across packages, so that users can find the translations of objects.
Internationalization lookup table¶
Use the following table to check whether a field can be published in your own language. You can download the table as a CSV spreadsheet.
path |
title |
translatable |
notes |
|---|---|---|---|
id |
Identifier or Reference |
True |
Only the part of the identifier following the prefix can be internationalized. |
updated |
Last updated |
False |
|
title |
Project title |
True |
|
description |
Project description |
True |
|
status |
Status |
False |
|
period |
Project period |
False |
|
period |
Period |
False |
|
period/startDate |
Start date |
False |
|
period/endDate |
End date |
False |
|
period/maxExtentDate |
Maximum extent |
False |
|
period/durationInDays |
Duration (days) |
False |
|
sector |
Project sector |
False |
|
purpose |
Project purpose |
True |
|
additionalClassifications |
Additional classifications |
False |
|
additionalClassifications |
Classification |
False |
|
additionalClassifications/scheme |
Scheme |
False |
|
additionalClassifications/id |
ID |
True |
|
additionalClassifications/description |
Description |
True |
|
additionalClassifications/uri |
URI |
False |
|
type |
Project type |
False |
|
relatedProjects |
Related projects |
False |
|
relatedProjects |
Related project |
False |
|
relatedProjects/id |
Relationship ID |
True |
|
relatedProjects/scheme |
Scheme |
False |
|
relatedProjects/identifier |
Identifier |
True |
|
relatedProjects/relationship |
Relationship |
False |
|
relatedProjects/title |
Related project title |
True |
|
relatedProjects/uri |
Related project URI |
False |
|
assetLifetime |
Asset lifetime |
False |
|
assetLifetime |
Period |
False |
|
assetLifetime/startDate |
Start date |
False |
|
assetLifetime/endDate |
End date |
False |
|
assetLifetime/maxExtentDate |
Maximum extent |
False |
|
assetLifetime/durationInDays |
Duration (days) |
False |
|
locations |
Project locations |
False |
|
locations |
Delivery Location |
False |
|
locations/id |
Identifier |
True |
|
locations/description |
Description |
True |
|
locations/geometry |
Geometry |
False |
|
locations/geometry/type |
Type |
False |
|
locations/geometry/coordinates |
Coordinates |
False |
|
locations/gazetteer |
Gazetteer |
False |
|
locations/gazetteer/scheme |
Gazetteer scheme |
False |
|
locations/gazetteer/identifiers |
Identifiers |
False |
|
locations/uri |
URI |
True |
|
locations/address |
Address |
False |
|
locations/address |
Address |
False |
|
locations/address/streetAddress |
Street address |
True |
|
locations/address/locality |
Locality |
True |
|
locations/address/region |
Region |
True |
|
locations/address/postalCode |
Postal code |
True |
|
locations/address/countryName |
Country name |
True |
|
budget |
Total project value |
False |
|
budget/description |
Description |
True |
|
budget/amount |
Amount |
False |
|
budget/amount |
Value |
False |
|
budget/amount/amount |
Amount |
False |
|
budget/amount/currency |
Currency |
False |
|
budget/requestDate |
Request date |
False |
|
budget/approvalDate |
Approval date |
False |
|
budget/budgetBreakdown |
Budget breakdown |
False |
|
budget/budgetBreakdown |
Detailed budget breakdown |
False |
|
budget/budgetBreakdown/id |
Identifier |
True |
|
budget/budgetBreakdown/description |
Description |
True |
|
budget/budgetBreakdown/amount |
Amount |
False |
|
budget/budgetBreakdown/amount |
Value |
False |
|
budget/budgetBreakdown/amount/amount |
Amount |
False |
|
budget/budgetBreakdown/amount/currency |
Currency |
False |
|
budget/budgetBreakdown/approvalDate |
Approval date |
False |
|
budget/budgetBreakdown/uri |
Linked budget information |
False |
|
budget/budgetBreakdown/period |
Budget period |
False |
|
budget/budgetBreakdown/period |
Period |
False |
|
budget/budgetBreakdown/period/startDate |
Start date |
False |
|
budget/budgetBreakdown/period/endDate |
End date |
False |
|
budget/budgetBreakdown/period/maxExtentDate |
Maximum extent |
False |
|
budget/budgetBreakdown/period/durationInDays |
Duration (days) |
False |
|
budget/budgetBreakdown/sourceParty |
Source party |
False |
|
budget/budgetBreakdown/sourceParty |
Organization reference |
False |
|
budget/budgetBreakdown/sourceParty/name |
Organization name |
True |
|
budget/budgetBreakdown/sourceParty/id |
Organization ID |
True |
|
forecasts |
Forecasts |
False |
|
forecasts |
Metric |
False |
|
forecasts/id |
Identifier |
False |
|
forecasts/title |
Title |
True |
|
forecasts/description |
Description |
True |
|
forecasts/observations |
Observations |
False |
|
forecasts/observations |
Observation |
False |
|
forecasts/observations/id |
Identifier |
True |
|
forecasts/observations/period |
Period |
False |
|
forecasts/observations/period |
Period |
False |
|
forecasts/observations/period/startDate |
Start date |
False |
|
forecasts/observations/period/endDate |
End date |
False |
|
forecasts/observations/period/maxExtentDate |
Maximum extent |
False |
|
forecasts/observations/period/durationInDays |
Duration (days) |
False |
|
forecasts/observations/value |
Value |
False |
|
forecasts/observations/value |
Value |
False |
|
forecasts/observations/value/amount |
Amount |
False |
|
forecasts/observations/value/currency |
Currency |
False |
|
forecasts/observations/measure |
Measure |
False |
Only string measures can be internationalized. |
forecasts/observations/unit |
Unit |
False |
|
forecasts/observations/unit/name |
Unit name |
True |
|
forecasts/observations/unit/scheme |
Scheme |
False |
|
forecasts/observations/unit/id |
ID |
True |
|
forecasts/observations/unit/uri |
URI |
False |
|
forecasts/observations/dimensions |
Dimensions |
False |
|
forecasts/observations/notes |
Notes |
True |
|
parties |
Parties |
False |
|
parties |
Organization |
False |
|
parties/name |
Common name |
True |
|
parties/id |
Entity ID |
True |
|
parties/identifier |
Primary identifier |
False |
|
parties/identifier |
Identifier |
False |
|
parties/identifier/scheme |
Scheme |
True |
|
parties/identifier/id |
ID |
True |
|
parties/identifier/legalName |
Legal Name |
True |
|
parties/identifier/uri |
URI |
False |
|
parties/additionalIdentifiers |
Additional identifiers |
False |
|
parties/additionalIdentifiers |
Identifier |
False |
|
parties/additionalIdentifiers/scheme |
Scheme |
True |
|
parties/additionalIdentifiers/id |
ID |
True |
|
parties/additionalIdentifiers/legalName |
Legal Name |
True |
|
parties/additionalIdentifiers/uri |
URI |
False |
|
parties/address |
Address |
False |
|
parties/address |
Address |
False |
|
parties/address/streetAddress |
Street address |
True |
|
parties/address/locality |
Locality |
True |
|
parties/address/region |
Region |
True |
|
parties/address/postalCode |
Postal code |
True |
|
parties/address/countryName |
Country name |
True |
|
parties/contactPoint |
Contact point |
False |
|
parties/contactPoint |
Contact point |
False |
|
parties/contactPoint/name |
Name |
True |
|
parties/contactPoint/email |
True |
||
parties/contactPoint/telephone |
Telephone |
True |
|
parties/contactPoint/faxNumber |
Fax number |
True |
|
parties/contactPoint/url |
URL |
False |
|
parties/roles |
Party roles |
False |
|
parties/people |
People |
False |
|
parties/people |
Person |
False |
|
parties/people/id |
Identifier |
True |
|
parties/people/name |
Name |
True |
|
parties/people/jobTitle |
Job title |
True |
|
publicAuthority |
Public authority |
False |
|
publicAuthority |
Organization reference |
False |
|
publicAuthority/name |
Organization name |
True |
|
publicAuthority/id |
Organization ID |
True |
|
documents |
Documents |
False |
|
documents |
Document |
False |
|
documents/id |
ID |
True |
|
documents/documentType |
Document type |
False |
|
documents/title |
Title |
True |
|
documents/description |
Description |
True |
|
documents/url |
URL |
False |
|
documents/datePublished |
Date published |
False |
|
documents/dateModified |
Date modified |
False |
|
documents/format |
Format |
True |
|
documents/language |
Language |
True |
|
documents/pageStart |
Page start |
True |
|
documents/pageEnd |
Page end |
True |
|
documents/accessDetails |
Access details |
True |
|
documents/author |
Author |
True |
|
contractingProcesses |
Contracting processes |
False |
|
contractingProcesses |
Contracting process |
False |
|
contractingProcesses/id |
Identifier |
True |
Only the part of the identifier following the prefix can be internationalized. |
contractingProcesses/summary |
Summary |
False |
|
contractingProcesses/summary |
Summary |
False |
|
contractingProcesses/summary/ocid |
Open Contracting Identifier |
True |
Only the part of the identifier following the prefix can be internationalized. |
contractingProcesses/summary/externalReference |
External reference |
True |
|
contractingProcesses/summary/nature |
Nature |
False |
|
contractingProcesses/summary/title |
Title |
True |
|
contractingProcesses/summary/description |
Description |
True |
|
contractingProcesses/summary/status |
Status |
False |
|
contractingProcesses/summary/tender |
Tender |
False |
|
contractingProcesses/summary/tender/procurementMethod |
Procurement method |
False |
|
contractingProcesses/summary/tender/procurementMethodDetails |
Procurement method details |
True |
|
contractingProcesses/summary/tender/costEstimate |
Cost estimate |
False |
|
contractingProcesses/summary/tender/costEstimate |
Value |
False |
|
contractingProcesses/summary/tender/costEstimate/amount |
Amount |
False |
|
contractingProcesses/summary/tender/costEstimate/currency |
Currency |
False |
|
contractingProcesses/summary/tender/numberOfTenderers |
Number of tenderers |
False |
|
contractingProcesses/summary/tender/tenderers |
Tenderers |
False |
|
contractingProcesses/summary/tender/tenderers |
Organization reference |
False |
|
contractingProcesses/summary/tender/tenderers/name |
Organization name |
True |
|
contractingProcesses/summary/tender/tenderers/id |
Organization ID |
True |
|
contractingProcesses/summary/tender/procuringEntity |
Procuring entity |
False |
|
contractingProcesses/summary/tender/procuringEntity |
Organization reference |
False |
|
contractingProcesses/summary/tender/procuringEntity/name |
Organization name |
True |
|
contractingProcesses/summary/tender/procuringEntity/id |
Organization ID |
True |
|
contractingProcesses/summary/tender/administrativeEntity |
Administrative entity |
False |
|
contractingProcesses/summary/tender/administrativeEntity |
Organization reference |
False |
|
contractingProcesses/summary/tender/administrativeEntity/name |
Organization name |
True |
|
contractingProcesses/summary/tender/administrativeEntity/id |
Organization ID |
True |
|
contractingProcesses/summary/suppliers |
Suppliers |
False |
|
contractingProcesses/summary/suppliers |
Organization reference |
False |
|
contractingProcesses/summary/suppliers/name |
Organization name |
True |
|
contractingProcesses/summary/suppliers/id |
Organization ID |
True |
|
contractingProcesses/summary/contractValue |
Contract value |
False |
|
contractingProcesses/summary/contractValue |
Value |
False |
|
contractingProcesses/summary/contractValue/amount |
Amount |
False |
|
contractingProcesses/summary/contractValue/currency |
Currency |
False |
|
contractingProcesses/summary/contractPeriod |
Contract period |
False |
|
contractingProcesses/summary/contractPeriod |
Period |
False |
|
contractingProcesses/summary/contractPeriod/startDate |
Start date |
False |
|
contractingProcesses/summary/contractPeriod/endDate |
End date |
False |
|
contractingProcesses/summary/contractPeriod/maxExtentDate |
Maximum extent |
False |
|
contractingProcesses/summary/contractPeriod/durationInDays |
Duration (days) |
False |
|
contractingProcesses/summary/finalValue |
Final value |
False |
|
contractingProcesses/summary/finalValue |
Value |
False |
|
contractingProcesses/summary/finalValue/amount |
Amount |
False |
|
contractingProcesses/summary/finalValue/currency |
Currency |
False |
|
contractingProcesses/summary/documents |
Documents |
False |
|
contractingProcesses/summary/documents |
Document |
False |
|
contractingProcesses/summary/documents/id |
ID |
True |
|
contractingProcesses/summary/documents/documentType |
Document type |
False |
|
contractingProcesses/summary/documents/title |
Title |
True |
|
contractingProcesses/summary/documents/description |
Description |
True |
|
contractingProcesses/summary/documents/url |
URL |
False |
|
contractingProcesses/summary/documents/datePublished |
Date published |
False |
|
contractingProcesses/summary/documents/dateModified |
Date modified |
False |
|
contractingProcesses/summary/documents/format |
Format |
True |
|
contractingProcesses/summary/documents/language |
Language |
True |
|
contractingProcesses/summary/documents/pageStart |
Page start |
True |
|
contractingProcesses/summary/documents/pageEnd |
Page end |
True |
|
contractingProcesses/summary/documents/accessDetails |
Access details |
True |
|
contractingProcesses/summary/documents/author |
Author |
True |
|
contractingProcesses/summary/modifications |
Modifications |
False |
|
contractingProcesses/summary/modifications |
Modification |
False |
|
contractingProcesses/summary/modifications/id |
Identifier |
True |
|
contractingProcesses/summary/modifications/date |
Date |
False |
|
contractingProcesses/summary/modifications/description |
Description |
True |
|
contractingProcesses/summary/modifications/rationale |
Rationale |
True |
|
contractingProcesses/summary/modifications/type |
Type |
False |
|
contractingProcesses/summary/modifications/releaseID |
Release ID |
True |
|
contractingProcesses/summary/modifications/oldContractValue |
Old contract value |
False |
|
contractingProcesses/summary/modifications/oldContractValue |
Value |
False |
|
contractingProcesses/summary/modifications/oldContractValue/amount |
Amount |
False |
|
contractingProcesses/summary/modifications/oldContractValue/currency |
Currency |
False |
|
contractingProcesses/summary/modifications/newContractValue |
New contract value |
False |
|
contractingProcesses/summary/modifications/newContractValue |
Value |
False |
|
contractingProcesses/summary/modifications/newContractValue/amount |
Amount |
False |
|
contractingProcesses/summary/modifications/newContractValue/currency |
Currency |
False |
|
contractingProcesses/summary/modifications/oldContractPeriod |
Old contract period |
False |
|
contractingProcesses/summary/modifications/oldContractPeriod |
Period |
False |
|
contractingProcesses/summary/modifications/oldContractPeriod/startDate |
Start date |
False |
|
contractingProcesses/summary/modifications/oldContractPeriod/endDate |
End date |
False |
|
contractingProcesses/summary/modifications/oldContractPeriod/maxExtentDate |
Maximum extent |
False |
|
contractingProcesses/summary/modifications/oldContractPeriod/durationInDays |
Duration (days) |
False |
|
contractingProcesses/summary/modifications/newContractPeriod |
New contract period |
False |
|
contractingProcesses/summary/modifications/newContractPeriod |
Period |
False |
|
contractingProcesses/summary/modifications/newContractPeriod/startDate |
Start date |
False |
|
contractingProcesses/summary/modifications/newContractPeriod/endDate |
End date |
False |
|
contractingProcesses/summary/modifications/newContractPeriod/maxExtentDate |
Maximum extent |
False |
|
contractingProcesses/summary/modifications/newContractPeriod/durationInDays |
Duration (days) |
False |
|
contractingProcesses/summary/transactions |
Transactions |
False |
|
contractingProcesses/summary/transactions |
Transaction information |
False |
|
contractingProcesses/summary/transactions/id |
ID |
True |
|
contractingProcesses/summary/transactions/source |
Data source |
False |
|
contractingProcesses/summary/transactions/date |
Date |
False |
|
contractingProcesses/summary/transactions/value |
Value |
False |
|
contractingProcesses/summary/transactions/value |
Value |
False |
|
contractingProcesses/summary/transactions/value/amount |
Amount |
False |
|
contractingProcesses/summary/transactions/value/currency |
Currency |
False |
|
contractingProcesses/summary/transactions/payer |
Payer |
False |
|
contractingProcesses/summary/transactions/payer |
Organization reference |
False |
|
contractingProcesses/summary/transactions/payer/name |
Organization name |
True |
|
contractingProcesses/summary/transactions/payer/id |
Organization ID |
True |
|
contractingProcesses/summary/transactions/payee |
Payee |
False |
|
contractingProcesses/summary/transactions/payee |
Organization reference |
False |
|
contractingProcesses/summary/transactions/payee/name |
Organization name |
True |
|
contractingProcesses/summary/transactions/payee/id |
Organization ID |
True |
|
contractingProcesses/summary/transactions/uri |
Linked spending information |
False |
|
contractingProcesses/releases |
Linked releases |
False |
|
contractingProcesses/releases |
Release |
False |
|
contractingProcesses/releases/id |
ID |
True |
|
contractingProcesses/releases/tag |
Release tag |
False |
|
contractingProcesses/releases/date |
Date |
False |
|
contractingProcesses/releases/url |
URL |
False |
|
metrics |
Metrics |
False |
|
metrics |
Metric |
False |
|
metrics/id |
Identifier |
False |
|
metrics/title |
Title |
True |
|
metrics/description |
Description |
True |
|
metrics/observations |
Observations |
False |
|
metrics/observations |
Observation |
False |
|
metrics/observations/id |
Identifier |
True |
|
metrics/observations/period |
Period |
False |
|
metrics/observations/period |
Period |
False |
|
metrics/observations/period/startDate |
Start date |
False |
|
metrics/observations/period/endDate |
End date |
False |
|
metrics/observations/period/maxExtentDate |
Maximum extent |
False |
|
metrics/observations/period/durationInDays |
Duration (days) |
False |
|
metrics/observations/value |
Value |
False |
|
metrics/observations/value |
Value |
False |
|
metrics/observations/value/amount |
Amount |
False |
|
metrics/observations/value/currency |
Currency |
False |
|
metrics/observations/measure |
Measure |
False |
|
metrics/observations/unit |
Unit |
False |
|
metrics/observations/unit/name |
Unit name |
True |
|
metrics/observations/unit/scheme |
Scheme |
False |
|
metrics/observations/unit/id |
ID |
True |
|
metrics/observations/unit/uri |
URI |
False |
|
metrics/observations/dimensions |
Dimensions |
False |
|
metrics/observations/notes |
Notes |
True |
|
completion |
Completion |
False |
|
completion/endDate |
End date |
False |
|
completion/endDateDetails |
End date details |
True |
|
completion/finalValue |
Final value |
False |
|
completion/finalValue |
Value |
False |
|
completion/finalValue/amount |
Amount |
False |
|
completion/finalValue/currency |
Currency |
False |
|
completion/finalValueDetails |
Final value details |
True |
|
completion/finalScope |
Final scope |
True |
|
completion/finalScopeDetails |
Final scope details |
True |
|
language |
Language |
True |
CoST IDS & OCDS Mapping¶
CoST – the Infrastructure Transparency Initiative (CoST) is the leading global initiative improving transparency and accountability in public infrastructure.
The CoST approach is based on four core features:
Disclosure - where procuring entities are asked to follow the CoST Infrastructure Data Standard. This describes 40 items of data that ought to be proactively disclosed at key stages of an infrastructure project cycle.
Assurance - an independent review of the disclosed data by assurance teams based within CoST national programmes. Teams identify key issues of concern analyzing the data that has been disclosed, and will put technical terms into plain language to allow stakeholders to understand the issues, and hold decision makers to account.
Multi-stakeholder working - each CoST national programme is managed by a stakeholder group including government, private sector and civil society.
Social accountability - raising awareness of key issues arising from the assurance process, and engaging civil society and media to hold decision makers to account.
The 'Infrastructure Data Standard' is a framework for disclosure which has been adapted by a range of CoST national programmes, who have variously prioritized different elements based on their local needs, or who have included additional elements that they wish to monitor: particularly additional kinds of documentation that ought to be provided for each infrastructure project.
You can read more about the Infrastructure Data Standard on the CoST website.
Frameworks and standards
There is an important distinction between the Infrastructure Data Standard (IDS) and the Open Contracting Data Standard (OCDS). IDS provides a framework to identify categories of information that ought to be disclosed. OCDS describes specific fields and how they should be structured as data.
The Open Contracting for Infrastructure Data Standard (OC4IDS) documented on this site acts as a bridge between the IDS framework, and the idea of a more structured technical data standard.
The following tables document two mappings:
The CoST IDS to OC4IDS mapping describes how to represent each element of the CoST IDS as structured data using OC4IDS. Use this mapping if you already collect data according to the CoST IDS and you want to publish your data using OC4IDS, or if you want to make sure that your OC4IDS publication conforms to the CoST IDS.
The OCDS to OC4IDS mapping describes how to use OCDS data to populate the sections of an OC4IDS file which relate to the CoST IDS. Use this mapping if you have access to OCDS data on infrastructure contracting processes and you want to create a summary by project in OC4IDS format, or if you want to check which CoST IDS elements your OCDS data covers.
The organization of the mapping tables reflects the structure of the CoST IDS, which is described in Getting Started.
The mapping tables use / notation to reference fields in OCDS data, e.g. /tender/status, and . notation to reference fields in the OC4IDS schema, e.g. .budget.approvalDate.
The CoST IDS also 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 reactive disclosures in each mapping.
Common operations¶
To avoid repetition in the mapping, we refer and link to the following common operations.
Add a project document¶
Add a Document object to the documents array and set its fields as follows:
Set its
.idincrementallySet its
.urlto a direct link to the documentSet its
.titleto the title of the document
Add a contracting process document¶
Add a Document object to the contractingProcesses.summary.documents array and set its fields as follows:
Set its
.idincrementallySet its
.urlto a direct link to the documentSet its
.titleto the title of the document
CoST IDS to OC4IDS Mapping¶
Project level¶
Identification¶
Preparation¶
Project completion¶
Reactive disclosures¶
Identification and preparation¶
Completion¶
Implementation progress reports¶
In addition to the documents listed in the mapping table, you can use OC4IDS to publish structured data on planned and actual physical and financial progress.
Choose from the following options, depending on the data you collect and the data needed by your use cases.
Actual progress over time
Add a
Metricobject to themetricsarray and:For financial progress, set its
idto 'financialProgress' and set its title to 'Financial progress', or the equivalent in the language of your publication.For physical progress, set its
idto 'physicalProgress' and set its title to 'Physical progress', or the equivalent in the language of your publication.
For each progress update, add an
Observationobject to theMetricobject's.observationsarray and:Set its
.idincrementallySet its
.measureto the financial progress of the project. For example, for a project that is 75% complete, set.measureto75Set its
.unit.nameto 'percent', set itsunit.idto 'P1' and set itsunit.schemeto 'UNCEFACT'Set its
period.startDateandperiod.endDateto the date on which the financial progress was measured
Example:
{
"metrics": [
{
"id": "physicalProgress",
"title": "Physical progress",
"observations": [
{
"id": "1",
"measure": "4.04",
"unit": {
"name": "percent",
"id": "P1",
"scheme": "UNCEFACT"
},
"period": {
"startDate": "2017-03-31T23:59:59Z",
"endDate": "2017-03-31T23:59:59Z"
}
},
{
"id": "2",
"measure": "7.98",
"unit": {
"name": "percent",
"id": "P1",
"scheme": "UNCEFACT"
},
"period": {
"startDate": "2017-04-30T23:59:59Z",
"endDate": "2017-04-30T23:59:59Z"
}
},
{
"id": "3",
"measure": "8.38",
"unit": {
"name": "percent",
"id": "P1",
"scheme": "UNCEFACT"
},
"period": {
"startDate": "2017-05-31T23:59:59Z",
"endDate": "2017-05-31T23:59:59Z"
}
}
]
}
]
}
A single progress figure
If your implementation does not store a change history, you can publish a single Observation object for each Metric and update the Observation object's .measure each time there is a progress update.
Example:
{
"metrics": [
{
"id": "financialProgress",
"title": "Financial progress",
"observations": [
{
"id": "1",
"measure": "4.04",
"unit": {
"name": "percent",
"id": "P1",
"scheme": "UNCEFACT"
},
"period": {
"startDate": "2017-03-31T23:59:59Z",
"endDate": "2017-03-31T23:59:59Z"
}
}
]
}
]
}
Planned progress over time
You can use the forecasts array to publish progress forecasts for different points in time.
Add a
Metricobject to theforecastsarray and:For financial progress, set its
idto 'financialProgress' and set its title to 'Financial progress', or the equivalent in the language of your publication.For physical progress, set its
idto 'physicalProgress' and set its title to 'Physical progress', or the equivalent in the language of your publication.
For each forecast, add an
Observationobject to theMetricobject's.observationsarray and:Set its
.idincrementallySet its
.measureto the forecast progress of the project. For example, to forecast when the project is expected to be complete, set.measureto100.Set its
.unit.nameto 'percent', set itsunit.idto 'P1' and set itsunit.schemeto 'UNCEFACT'Set its
period.startDateandperiod.endDateto the date on which you expect the progress to be achieved
Example:
{
"forecasts": [
{
"id": "physicalProgress",
"title": "Physical progress",
"observations": [
{
"id": "1",
"measure": "4.04",
"unit": {
"name": "percent",
"id": "P1",
"scheme": "UNCEFACT"
},
"period": {
"startDate": "2017-03-31T23:59:59Z",
"endDate": "2017-03-31T23:59:59Z"
}
},
{
"id": "2",
"measure": "7.98",
"unit": {
"name": "percent",
"id": "P1",
"scheme": "UNCEFACT"
},
"period": {
"startDate": "2017-04-30T23:59:59Z",
"endDate": "2017-04-30T23:59:59Z"
}
},
{
"id": "3",
"measure": "8.38",
"unit": {
"name": "percent",
"id": "P1",
"scheme": "UNCEFACT"
},
"period": {
"startDate": "2017-05-31T23:59:59Z",
"endDate": "2017-05-31T23:59:59Z"
}
}
]
}
]
}
Process level¶
The mappings in this section relate to the contractingProcesses section of the OC4IDS schema, unless otherwise specified.
Procurement¶
Implementation¶
Reactive disclosures¶
Procurement¶
Contract¶
Implementation¶
OCDS to OC4IDS Mapping¶
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.titlediffers for two contracting processes that relate to the same project, but OC4IDS has a singletitlefield at the project level.OCDS data that contains multiple
Organizationobjects with the same.rolethat map to a single field in OC4IDS: for example, where a contracting process has twoOrganizations with the 'procuringEntity' role, but OC4IDS has a single.summary.tender.procuringEntityfield at the contract level.Checking for duplicates when copying objects from OCDS. For example, checking whether an
Organizationobject 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
Documentwith 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¶
Preparation¶
Project completion¶
Reactive disclosures¶
Identification and preparation¶
Completion¶
Process level¶
The mappings in this section relate to the contractingProcesses section of the OC4IDS schema, unless otherwise specified.
Procurement¶
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.
Reactive disclosures¶
Procurement¶
Contract¶
Implementation¶
Support¶
If you are planning to publish or use data using the OC4IDS then the Open Contracting Partnership and CoST - the Infrastructure Transparency Initiative can provide free-of-charge support.
We can:
Help you identify approaches for converting data from your existing systems to OC4IDS;
Suggest existing tools and services which might help you publish or use OC4IDS data;
Provide guidance on mapping your data structures to the standard;
Give you feedback on draft data files, and support with validation of your data;
Use the following email addresses to request support:
opencode@infrastructuretransparency.org for support from CoST - the Infrastructure Transparency Initiative
data@open-contracting.org for support from the Open Contracting Partnership.
Contributing
Developers, or those wishing to provide technical input to OC4IDS, can go straight to the GitHub repository.