Release Reference

The Release Schema provides a detailed specification of the fields and data structures to use when publishing contracting data. Supplementary schemas show how to combine releases into data packages and how to compile releases into records.

Note: If any conflicts are found between this text, and the text within the schema, the schema takes precedence

Release structure

The majority of OCDS data is held within a release structure. One or more releases can be published within a release package. Releases are made up of a number of sections, arranged in the following structure.

Releases are given a tag to indicate the specific stage of a contracting process they represent. However, there are no formal restrictions on when information about a stage of the contracting process may be provided.

For example, a publisher announcing the signing of a contract with a ‘contract’ tag, may also include information in the award and tender blocks in order to provide a comprehensive picture of the contracting process to date which led to that contract being signed.

Package Metadata

Releases must be published within a release package. The release package provides metadata about the release(s) that it contains.

Title Description Type Format Required
uri string uri Required
Package identifier The URI of this package that identifies it uniquely in the world. Recommended practice is to use a dereferenceable URI, where a persistent copy of this package is available.
version string   Required
OCDS schema version The version of the OCDS schema used in this package, expressed as major.minor For example: 1.0 or 1.1
extensions array[string]    
OCDS extensions An array of OCDS extensions used in this package. Each entry should be a URL to the extension.json file for that extension.
publishedDate string date-time Required
Published date The date that this package was published. If this package is generated ‘on demand’, this date should reflect the date of the last change to the underlying contents of the package.
releases array[object]    
Releases
publisher object   Required
Publisher Information to uniquely identify the publisher of this package.
license [string, null] uri  
License A link to the license that applies to the data in this package. A Public Domain Dedication or Open Definition Conformant license is strongly recommended. The canonical URI of the license should be used. Documents linked from this file may be under other license conditions.
publicationPolicy [string, null] uri  
Publication policy A link to a document describing the publishers publication policy.

See the licensing guidance for more details on selecting a license, and publishing license information.

See the publication policy guidance for more details on what to include in a publication policy.

Release

All new information about a contracting process is described within a release.

Title Description Type Format Required
ocid string   Required
Open Contracting ID A globally unique identifier for this Open Contracting Process. Composed of a publisher prefix and an identifier for the contracting process. For more information see the Open Contracting Identifier guidance
id string   Required
Release ID An identifier for this particular release of information. A release identifier must be unique within the scope of its related contracting process (defined by a common ocid), and unique within any release package it appears in. A release identifier must not contain the # character.
date string date-time Required
Release Date The date this information was first released, or published.
tag array[string]    
Release Tag One or more values from the releaseTag codelist. Tags may be used to filter release and to understand the kind of information that a release might contain.
initiationType string   Required
Initiation type String specifying the type of initiation process used for this contract, taken from the initiationType codelist. Currently only tender is supported.
parties array[Organization]    
Parties

Information on the parties (organizations, economic operators and other participants) who are involved in the contracting process 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

buyer object    
Buyer

The buyer is the entity whose budget will be used to purchase the goods. This may be different from the procuring entity who may be specified in the tender data.

See OrganizationReference

planning object    
Planning

Information from the planning phase of the contracting process. This includes information related to the process of deciding what to contract, when and how.

See Planning

tender object    
Tender

The activities undertaken in order to enter into a contract.

See Tender

awards array[Award]    
Awards

Information from the award phase of the contracting process. There may be more than one award per contracting process e.g. because the contract is split among different providers, or because it is a standing offer.

See Award

contracts array[Contract]    
Contracts

Information from the contract creation phase of the procurement process.

See Contract

language [string, null]    
Release language Specifies 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 strongly recommended.

The following extensions are available for release

Process level title and description
For providing overall process titles and descriptions, often to give a free-text summary of the contracting process as a whole.

The following are community extensions and are not maintained by Open Contracting Partnership.

Parties

Each of the parties (organizations or other participants) referenced in a release must be included in the parties section.

Note

Parties

Version 1.1 of OCDS introduces a new approach to describing the buyers, suppliers, economic operators, and other participants in a contracting process. Instead of embedding organization information at various points within an OCDS release, information on all the parties involved in a contracting process is collected together in a top-level section, and the parties indicated by a cross-reference to their id at other points.

This reduces repetition of information on parties who appear at multiple points in the contracting process, and supports publication of information about additional parties to the contracting process, including auditors, multiple buyers, and consortia partners of a winning bidder.

The old, embedded data, approach to organization data is deprecated in OCDS 1.1, and will be removed in version 2.0.

The following details can be provided for each party.

Title Description Type Format Required
name [string, null]    
Common name A common name for this organization or other participant in the contracting process. The identifier object provides an space for the formal legal name, and so this may either repeat that value, or could 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 could 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

An person, contact point or department to contact in relation to this contracting process.

See ContactPoint

roles [array, null]    
Party roles The party’s role(s) in the contracting process. Role(s) should be taken from the partyRole codelist. Values from the provided codelist should be used wherever possible, though extended values can be provided if the codelist does not have a relevant code.
details [object, null]    
Details Additional classification information about parties can be provided using partyDetail extensions that define particular properties and classification schemes.

Detailed classification of parties can be provided using one or more party detail extensions.

The following extensions are available for parties

The following are community extensions and are not maintained by Open Contracting Partnership.

Planning

The planning section can be used to describe the background to a contracting process. This may include details of the budget from which funds are drawn, or related projects for this contracting process. Background documents such as a needs assessment, feasibility study and project plan can also be included in this section.

Title Description Type Format Required
rationale [string, null]    
Rationale The rationale for the procurement provided in free text. More detail can be provided in an attached document.
budget object    
Budget information

This section contain information about the budget line, and associated projects, through which this contracting process is funded. It draws upon data model of the Fiscal Data Package, and should be used to cross-reference to more detailed information held using a Budget Data Package, or, where no linked Budget Data Package is available, to provide enough information to allow a user to manually or automatically cross-reference with another published source of budget and project information.

See Budget

milestones array[Milestone]    
Planning milestones

A list of milestones associated with the planning stage.

See Milestone

The following extensions are available for planning

The following are community extensions and are not maintained by Open Contracting Partnership.

Apart from documents, the majority of information is held within the budget block. This is designed to allow both machine-readable linkable data about budgets, cross-referencing to data held in other standards such as the Fiscal Data Package or International Aid Transparency Initiative Standard, and human readable description of the related budgets and projects, supporting users to understand the relationship of the contracting process to existing projects and budgets even where linked data is not available.

Budget

Title Description Type Format Required
id [string, integer, null]    
ID An identifier for the budget line item which provides funds for this contracting process. This identifier should be possible to cross-reference against the provided data source.
description [string, null]    
Budget Source A short free text description of the budget source. May be used to provide the title of the budget line, or the programme used to fund this project.
amount object    
Amount

The value reserved in the budget for this contracting process. A negative value indicates anticipated income to the budget as a result of this contracting process, rather than expenditure. Where the budget is drawn from multiple sources, the budget breakdown extension can be used.

See Value

project [string, null]    
Project title The name of the project that through which this contracting process is funded (if applicable). Some organizations maintain a registry of projects, and the data should use the name by which the project is known in that registry. No translation option is offered for this string, as translated values can be provided in third-party data, linked from the data source above.
projectID [string, integer, null]    
Project identifier An external identifier for the project that this contracting process forms part of, or is funded via (if applicable). Some organizations maintain a registry of projects, and the data should use the identifier from the relevant registry of projects.
uri [string, null] uri  
Linked budget information A URI pointing directly to a machine-readable record about the budget line-item or line-items that fund this contracting process. Information may be provided in a range of formats, including using IATI, the Open Fiscal Data Standard or any other standard which provides structured data on budget sources. Human readable documents can be included using the planning.documents block.
source [string, null] uri  
Data Source

(Deprecated in 1.1) Used to point either to a corresponding Budget Data Package, or to a machine or human-readable source where users can find further information on the budget line item identifiers, or project identifiers, provided here.

This property was deprecated in version 1.1

The budget data source field was intended to link to machine-readable data about the budget for a contracting process, but has been widely mis-used to provide free-text descriptions of budget providers. As a result, it has been removed from version 1.1. budget/uri can be used to provide a link to machine-readable budget information, and budget/description can be used to provide human-readable information on the budget source.

The following extensions are available for budget

The following are community extensions and are not maintained by Open Contracting Partnership.

Tender

The tender section includes details of the announcement that an organization intends to source some particular goods, works or services, and to establish one or more contract(s) for these.

It may contain details of a forthcoming process to receive and evaluate proposals to supply these goods and services, and may also be used to record details of a completed tender process, including details of bids received.

Title Description Type Format Required
id [string, integer]   Required
Tender ID An identifier for this tender process. This may be the same as the ocid, or may be drawn from an internally held identifier for this tender.
title [string, null]    
Tender title A title for this tender. This will often be used by applications as a headline to attract interest, and to help analysts understand the nature of this procurement.
description [string, null]    
Tender description A summary description of the tender. This should complement structured information provided using the items array. Descriptions should be short and easy to read. Avoid using ALL CAPS.
status [string, null]    
Tender status The current status of the tender based on the tenderStatus codelist
procuringEntity object    
Procuring entity

The entity managing the procurement. This may be different from the buyer who pays for, or uses, the items being procured.

See OrganizationReference

items array[Item]    
Items to be procured

The goods and services to be purchased, broken into line items wherever possible. Items should not be duplicated, but a quantity of 2 specified instead.

See Item

value object    
Value

The total upper estimated value of the procurement. A negative value indicates that the contracting process may involve payments from the supplier to the buyer (commonly used in concession contracts).

See Value

minValue object    
Minimum value

The minimum estimated value of the procurement. A negative value indicates that the contracting process may involve payments from the supplier to the buyer (commonly used in concession contracts).

See Value

procurementMethod [string, null]    
Procurement method Specify tendering method using the method codelist. This is a closed codelist. Local method types should be mapped to this list.
procurementMethodDetails [string, null]    
Procurement method details Additional detail on the procurement method used. This field may be used to provide the local name of the particular procurement method used.
procurementMethodRationale [string, null]    
Procurement method rationale Rationale for the chosen procurement method. This is especially important to provide a justification in the case of limited tenders or direct awards.
mainProcurementCategory [string, null]    
Main procurement category The primary category describing the main object of this contracting process from the procurementCategory codelist. This is a closed codelist. Local classifications should be mapped to this list.
additionalProcurementCategories [array, null]    
Additional procurement categories Any additional categories which describe the objects of this contracting process, from the extendedProcurementCategory codelist. This is an open codelist. Local categories can be included in this list.
awardCriteria [string, null]    
Award criteria Specify the award criteria for the procurement, using the award criteria codelist
awardCriteriaDetails [string, null]    
Award criteria details Any detailed or further information on the award or selection criteria.
submissionMethod [array, null]    
Submission method Specify the method by which bids must be submitted, in person, written, or electronic auction. Using the submission method codelist
submissionMethodDetails [string, null]    
Submission method details Any detailed or further information on the submission method. This may include the address, e-mail address or online service to which bids should be submitted, and any special requirements to be followed for submissions.
tenderPeriod object    
Tender period

The period when the tender is open for submissions. The end date is the closing date for tender submissions.

See Period

enquiryPeriod object    
Enquiry period

The period during which potential bidders may submit questions and requests for clarification to the entity managing procurement. Details of how to submit enquiries should be provided in attached notices, or in submissionMethodDetails. Structured dates for when responses to questions will be made can be provided using tender milestones.

See Period

hasEnquiries [boolean, null]    
Has enquiries? A true/false field to indicate whether any enquiries were received during the tender process. Structured information on enquiries that were received, and responses to them, can be provided using the enquiries extension.
eligibilityCriteria [string, null]    
Eligibility criteria A description of any eligibility criteria for potential suppliers.
awardPeriod object    
Evaluation and award period

The period for decision making regarding the contract award. The end date should be the date on which an award decision is due to be finalized. The start date is optional, and may be used to indicate the start of an evaluation period.

See Period

contractPeriod object    
Contract period

The period over which the contract is estimated or required to be active. If the tender does not specify explicit dates, the duration field may be used.

See Period

numberOfTenderers [integer, null]    
Number of tenderers The number of parties who submit a bid.
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 optional bid extension.

See OrganizationReference

documents array[Document]    
Documents

All documents and attachments related to the tender, including any notices. See the documentType codelist for details of potential documents to include. Common documents include official legal notices of tender, technical specifications, evaluation criteria, and, as a tender process progresses, clarifications and replies to queries.

See Document

milestones array[Milestone]    
Milestones

A list of milestones associated with the tender.

See Milestone

amendments array[Amendment]    
Amendments

A tender amendment is a formal change to the tender, and generally involves the publication of a new tender notice/release. The rationale and a description of the changes made can be provided here.

See Amendment

amendment object    
Amendment

The use of individual amendment objects has been deprecated. From OCDS 1.1 information should be provided in the amendments array.

See Amendment

This property was deprecated in version 1.1

The single amendment object has been deprecated in favour of including amendments in an amendments (plural) array.

The following extensions are available for the tender section

Enquiries
The enquiries extension can be used to record questions raised during a contracting process, and the answers provided.
Lots
A tender process may be divided into lots, where bidders can bid on one or more lots. Details of each lot can be provided here. Items, documents and other features can then reference the lot they are related to using relatedLot. Where no relatedLot identifier is given, the values should be interpreted as applicable to the whole tender.
Participation Fees
Where a tender process involves payment of fees to access documents, submit a proposal, or be awarded a contract, this extension can be used to provide fee details.

The following are community extensions and are not maintained by Open Contracting Partnership.

Bids

The optional bids extension can be used to provide summary and detailed information about bids.

Bid statistics and details
Allowing bid statistics, and detailed bid information to be represented.

The following are community extensions and are not maintained by Open Contracting Partnership.

Award

The award section is used to announce any awards issued for this tender. There may be multiple awards made. Releases can contain all, or a subset, of these awards. A related award block is required alongside every contract block, as the award contains information on the suppliers.

Title Description Type Format Required
id [string, integer]   Required
Award ID The identifier for this award. It must be unique and cannot change within the Open Contracting Process it is part of (defined by a single ocid). See the identifier guidance for further details.
title [string, null]    
Title Award title
description [string, null]    
Description Award description
status [string, null]    
Award status The current status of the award drawn from the awardStatus codelist
date [string, null] date-time  
Award date The date of the contract award. This is usually the date on which a decision to award was made.
value object    
Value

The total value of this award. In the case of a framework contract this may be the total estimated lifetime value, or maximum value, of the agreement. There may be more than one award per procurement. A negative value indicates that the award may involve payments from the supplier to the buyer (commonly used in concession contracts).

See Value

suppliers array[Organization reference]    
Suppliers

The suppliers awarded this award. If different suppliers have been awarded different items of values, these should be split into separate award blocks.

See OrganizationReference

items array[Item]    
Items awarded

The goods and services awarded in this award, broken into line items wherever possible. Items should not be duplicated, but the quantity specified instead.

See Item

contractPeriod object    
Contract period

The period for which the contract has been awarded.

See Period

documents array[Document]    
Documents

All documents and attachments related to the award, including any notices.

See Document

amendments array[Amendment]    
Amendments

An award amendment is a formal change to the details of the award, and generally involves the publication of a new award notice/release. The rationale and a description of the changes made can be provided here.

See Amendment

amendment object    
Amendment

The use of individual amendment objects has been deprecated. From OCDS 1.1 information should be provided in the amendments array.

See Amendment

This property was deprecated in version 1.1

The single amendment object has been deprecated in favour of including amendments in an amendments (plural) array.

The following extensions are available for award

The following are community extensions and are not maintained by Open Contracting Partnership.

Contract

The contract section is used to provide details of contracts that have been entered into. Every contract needs to have a related award, linked via the awardID property. This is because supplier information is contained within the ‘award’. The framework contract details below help illustrate the reasons for this.

Title Description Type Format Required
id [string, integer]   Required
Contract ID The identifier for this contract. It must be unique and cannot change within its Open Contracting Process (defined by a single ocid). See the identifier guidance for further details.
awardID [string, integer]   Required
Award ID The award.id against which this contract is being issued.
title [string, null]    
Contract title Contract title
description [string, null]    
Contract description Contract description
status [string, null]    
Contract status The current status of the contract. Drawn from the contractStatus codelist
period object    
Period

The start and end date for the contract.

See Period

value object    
Value

The total value of this contract. A negative value indicates that the contract will involve payments from the supplier to the buyer (commonly used in concession contracts).

See Value

items array[Item]    
Items contracted

The goods, services, and any intangible outcomes in this contract. Note: If the items are the same as the award do not repeat.

See Item

dateSigned [string, null] date-time  
Date signed The date the contract was signed. In the case of multiple signatures, the date of the last signature.
documents array[Document]    
Documents

All documents and attachments related to the contract, including any notices.

See Document

implementation object    
Implementation

Information related to the implementation of the contract in accordance with the obligations laid out therein.

See Implementation

milestones array[Milestone]    
Contract milestones

A list of milestones associated with the finalization of this contract.

See Milestone

amendments array[Amendment]    
Amendments

A contract amendment is a formal change to, or extension of, a contract, and generally involves the publication of a new contract notice/release, or some other documents detailing the change. The rationale and a description of the changes made can be provided here.

See Amendment

amendment object    
Amendment

The use of individual amendment objects has been deprecated. From OCDS 1.1 information should be provided in the amendments array.

See Amendment

This property was deprecated in version 1.1

The single amendment object has been deprecated in favour of including amendments in an amendments (plural) array.

The following extensions are available for contracts

The following are community extensions and are not maintained by Open Contracting Partnership.

Implementation

Implementation information can be updated over the course of a contract. It belongs nested within the contract it relates to. Implementation blocks include the following elements:

Title Description Type Format Required
transactions array[Transaction information]    
Transactions

A list of the spending transactions made against this contract

See Transaction

milestones array[Milestone]    
Milestones

As milestones are completed, milestone completions should be documented.

See Milestone

documents array[Document]    
Documents

Documents and reports that are part of the implementation phase e.g. audit and evaluation reports.

See Document

The following extensions are available for implementation

The following are community extensions and are not maintained by Open Contracting Partnership.

Information on subcontracts is not currently included in the core OCDS schema, but may be handled by proposed extensions

Transaction

Title Description Type Format Required
id [string, integer]   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, null] 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, null] 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.

See OrganizationReference

payee object    
Payee

An organization reference for the organization which receives the funds in this transaction.

See OrganizationReference

uri [string, null] uri  
Linked spending information A URI pointing directly to a machine-readable record about this spending transaction.
amount object    
Amount

(Deprecated in 1.1. Use transaction.value instead) The value of the transaction. A negative value indicates a refund or correction.

See Value

This property was deprecated in version 1.1

This field has been replaced by the `transaction.value` field for consistency with the use of value and amount elsewhere in the standard.

providerOrganization object    
Provider organization

(Deprecated in 1.1. Use transaction.payer instead.) The Organization Identifier for the organization from which the funds in this transaction originate. Expressed following the Organizational Identifier standard - consult the documentation and the codelist.

See Identifier

This property was deprecated in version 1.1

This field has been replaced by the `transaction.payer` field to resolve ambiguity arising from ‘provider’ being interpreted as relating to the goods or services procured rather than the flow of funds between the parties.

receiverOrganization object    
Receiver organization

(Deprecated in 1.1. Use transaction.payee instead). The Organization Identifier for the organization which receives the funds in this transaction. Expressed following the Organizational Identifier standard - consult the documentation and the codelist.

See Identifier

This property was deprecated in version 1.1

This field has been replaced by the `transaction.payee` field to resolve ambiguity arising from ‘receiver’ being interpreted as relating to the goods or services procured rather than the flow of funds between the parties.

The transaction block is modelled on the International Aid Transparency Initiative (IATI) transaction element, and can be used to represent actual flows of money between organizations in relation to this contract. As with the budget block, this may be used to cross-reference to a third party source of data, and can re-use identifiers from that source.

In most circumstances, the payer identifier should match that of the buyer, and the payee identifier should match that of the supplier.

Milestones

See milestone reference below.

The implementation milestones should be updated to reflect when they are met.

Documents

Documents related to contract implementation should be stored here. This may include subcontracts.

See document reference below.

Amendment

A release may amend properties from a previous release. Whilst the release & record model of OCDS offers the opportunity to keep a full versioned history of changes, in many cases it is important for changes to a tender, award or contract to be explicitly declared.

The amendment array in a tender, award or contract block provides the ability to detail the amendments that have taken place with dates, rationale and free-text descriptions of the change, as well as to point to the releases that contain information from before and after the amendment.

Title Description Type Format Required
date [string, null] date-time  
Amendment date The date of this amendment.
rationale [string, null]    
Rationale An explanation for the amendment.
id [string, null]    
ID An identifier for this amendment: often the amendment number
description [string, null]    
Description A free text, or semi-structured, description of the changes made in this amendment.
amendsReleaseID [string, null]    
Amended release (identifier) Provide the identifier (release.id) of the OCDS release (from this contracting process) that provides the values for this contracting process before the amendment was made.
releaseID [string, null]    
Amending release (identifier) Provide the identifier (release.id) of the OCDS release (from this contracting process) that provides the values for this contracting process after the amendment was made.
changes array[object]    
Amended fields

An array change objects describing the fields changed, and their former values. (Deprecated in 1.1)

This property was deprecated in version 1.1

A free-text or semi-structured string describing the changes made in each amendment can be provided in the amendment.description field. To provide structured information on the fields that have changed, publishers should provide releases indicating the state of the contracting process before and after the amendment.

Changes

The changes array was deprecated in OCDS 1.1. Structured information on the former value of specific fields should be provided by:

  • Including releases from before and after a change within a release package;
  • Using the amendment array in tender, contract or award to explicitly relate these releases to an amendment.

See the amendment implementation guidance for more details.

Building block reference

The following building blocks are commonly re-used throughout the standard.

OrganizationReference

Note

Organizations

The approach to including organizations information has changed in OCDS 1.1. Instead of embedding all the details of an organization, publishers should use an organization reference to indicate the entry in the parties section that contains full details of this organization.

An organization reference consists of two main components:

  • An id used to cross-reference the entry in the parties section that contains full information on this organization or entity;
  • A name field that repeats the name given in the parties section, provided for the convenience of users viewing the data, and to support detection of mistakes in cross-referencing.

The Organization Reference schema contains deprecated fields to prevent validation failures of OCDS 1.0 data.

Organization

See the parties section

Identifier

The identifier block provides a way to identify the legal entities involved in a contracting process.

If a contracting process represents a contract arranged by the department or branch of a larger organization, the legal entity (usually the registered organization) should be described in the identifier section, with details of the branch or department given in the name, address and contact point as relevant.

Title Description Type Format Required
scheme [string, null]    
Scheme Organization identifiers should be drawn from an existing organization identifier list. The scheme field is used to indicate the list or register from which the identifier is drawn. This value should be drawn from the Organization Identifier Scheme codelist.
id [string, integer, null]    
ID The identifier of the organization in the selected scheme.
legalName [string, null]    
Legal Name The legally registered name of the organization.
uri [string, null] 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.

Address

Title Description Type Format Required
streetAddress [string, null]    
Street address The street address. For example, 1600 Amphitheatre Pkwy.
locality [string, null]    
Locality The locality. For example, Mountain View.
region [string, null]    
Region The region. For example, CA.
postalCode [string, null]    
Postal code The postal code. For example, 94043.
countryName [string, null]    
Country name The country name. For example, United States.

ContactPoint

Title Description Type Format Required
name [string, null]    
Name The name of the contact person, department, or contact point, for correspondence relating to this contracting process.
email [string, null]    
Email The e-mail address of the contact point/person.
telephone [string, null]    
Telephone The telephone number of the contact point/person. This should include the international dialing code.
faxNumber [string, null]    
Fax number The fax number of the contact point/person. This should include the international dialing code.
url [string, null] uri  
URL A web address for the contact point/person.

Document

Documents may be attached at a number of points within the standard: to planning, tenders, awards, contracts and implementation Each document block can consist of multiple documents, classified using the documentType codelist.

The document block is also used to link to legal notices, which should have a documentType of ‘notice’.

Title Description Type Format Required
id [string, integer]   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, null]    
Document type A classification of the document described taken from the documentType codelist. Values from the provided codelist should be used wherever possible, though extended values can be provided if the codelist does not have a relevant code.
title [string, null]    
Title The document title.
description [string, null]    
Description A short description of the document. We recommend descriptions do not exceed 250 words. In the event the document is not accessible online, the description field can be used to describe arrangements for obtaining a copy of the document.
url [string, null] uri  
URL
direct link to the document or attachment. The server providing access to this document should be configured to correctly report the document mime type.
datePublished [string, null] 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, null] date-time  
Date modified Date that the document was last modified
format [string, null]    
Format The format of the document taken from the IANA Media Types codelist, with the addition of one extra value for ‘offline/print’, used when this document entry is being used to describe the offline publication of a document. Use values from the template column. Links to web pages should be tagged ‘text/html’.
language [string, null]    
Language Specifies 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 strongly recommended unless there is a clear user need for distinguishing the language subtype.

The following extensions are available for document

The following are community extensions and are not maintained by Open Contracting Partnership.

Period

A period has a start date, end date, and/or duration. Start and end dates are represented using date-times. Durations are represented as a number of days.

Periods may also include a maxExtentDate which indicates the latest possible end date of this period, or the latest date up until which the period could be extended without an amendment.

Title Description Type Format Required
startDate [string, null] date-time  
Start date The start date for the period. When known, a precise start date must always be provided.
endDate [string, null] date-time  
End date The end date for the period. When known, a precise end date must always be provided.
maxExtentDate [string, null] date-time  
Maximum extent The period cannot be extended beyond this date. This field is optional, and can be used to express the maximum available data for extension or renewal of this period.
durationInDays [integer, null]    
Duration (days) The maximum duration of this period in days. A user interface may wish to collect or display this data in months or years as appropriate, but should convert it into days when completing this field. This field can be used when exact dates are not known. Where a startDate and endDate are given, this field is optional, and should reflect the difference between those two days. Where a startDate and maxExtentDate are given, this field is optional, and should reflect the difference between startDate and maxExtentDate.

The following extensions are available for period

The following are community extensions and are not maintained by Open Contracting Partnership.

Date

OCDS makes use of ISO8601 date-times, following RFC3339 §5.6.

A time and timezone/offset MUST always be provided in a date-time.

The following are valid date-times:

  • ‘2014-10-21T09:30:00Z’ - 9:30 am on the 21st October 2014, UTC
  • ‘2014-11-18T18:00:00-06:00’ - 6pm on 18th November 2014 CST (Central Standard Time)

The following are not valid:

  • ‘2014-10-21’ - Missing time portion
  • ‘2014-10-21T18:00’ - missing seconds in time portion.
  • ‘2014-11-18T18:00:00’ - Missing timezone/offset portion
  • ‘11/18/2014 18:00’ - Not following the pattern at all!

Accurately including the time and timezone offsets is particular important for tender deadlines and other dates which may have legal significance, and where users of the data may be from different timezones. The character Z on the end of a date-time indicates the UTC (or Zero offset) timezone, whereas other timezones are indicated by their value ‘+/-hh:mm’ UTC on the end of the date-time value.

In the event that the system from which data is drawn only includes dates, and does not include time information, publishers should consider sensible defaults for each field. For example, the startDate time of a clarification period may be set to ‘00:00:00Z’ to indicate that clarifications can be requested from any time on the date stated, with the endDate time set to 23:59:59Z to indicate that clarifications can be sent up until the end of the endDate given. Alternatively, if clarification requests are only accepted in standard office hours, these values might be 09:00:00Z and 17:00:00Z respectively.

In the event that a date field is not bound to a specific time at all, publishers should choose a default time value of ‘23:59:59’ and either ‘Z’ (for UTC) or the timezone of the publisher, indicating that the time refers to the end of the given date.

Item

The items block is used to list the line-items associated with a tender, award or contract.

Title Description Type Format Required
id [string, integer]   Required
ID A local identifier to reference and merge the items by. Must be unique within a given array of items.
description [string, null]    
Description A description of the goods, services to be provided.
classification object    
Classification

The primary classification for the item. See the itemClassificationScheme to identify preferred classification lists, including CPV and GSIN.

See Classification

additionalClassifications array[Classification]    
Additional classifications

An array of additional classifications for the item. See the itemClassificationScheme codelist for common options to use in OCDS. This may also be used to present codes from an internal classification scheme.

See Classification

quantity [number, null]    
Quantity The number of units required
unit object    
Unit A description of the unit in which the supplies, services or works are provided (e.g. hours, kilograms) and the unit-price. For comparability, an established list of units can be used.

These are extensions related to Items.

Location
Allow the point of delivery for a given item or the site of works to be completed to be indicated in both the tender, award and contract stage.

The following are community extensions and are not maintained by Open Contracting Partnership.

Classification

Title Description Type Format Required
scheme [string, null]    
Scheme An classification should be drawn from an existing scheme or list of codes. This field is used to indicate the scheme/codelist from which the classification is drawn. For line item classifications, this value should represent an known Item Classification Scheme wherever possible.
id [string, integer, null]    
ID The classification code drawn from the selected scheme.
description [string, null]    
Description A textual description or title for the code.
uri [string, null] uri  
URI A URI to identify the code. In the event individual URIs are not available for items in the identifier scheme this value should be left blank.

Unit

The unit block allows detailed specification of the parameters and price of units that make up a line-item. Although no codelist for units has been established in the current release of the standard, publishers may consider using the Units provided by the Quantities, Units, Dimensions and Data Types Ontologies in the unit.name field (drawing on the CamelCase unit names, such as SquareMile), in order to provide detailed information the cost per unit of a line-item.

Title Description Type Format Required
scheme [string, null]    
Scheme The list from which units of measure identifiers are taken. This should be an entry from the options available in the unitClassificationScheme codelist. Use of the scheme ‘UNCEFACT’ for the UN/CEFACT Recommendation 20 list of ‘Codes for Units of Measure Used in International Trade’ is recommended, although other options are available.
id [string, null]    
ID The identifier from the codelist referenced in the scheme property. Check the codelist for details of how to find and use identifiers from the scheme in use.
name [string, null]    
Name Name of the unit.
value object    
Value

The monetary value of a single unit.

See Value

uri [string, null] uri  
URI If the scheme used provide a machine-readable URI for this unit of measure, this can be given.

Milestone

Milestone information can be included in the planning, tender, contract and contract implementation blocks.

Title Description Type Format Required
id [string, integer]   Required
ID A local identifier for this milestone, unique within this block. This field is used to keep track of multiple revisions of a milestone through the compilation from release to record mechanism.
title [string, null]    
Title Milestone title
type [string, null]    
Milestone type The type of milestone, drawn from an extended milestoneType codelist.
description [string, null]    
Description A description of the milestone.
code [string, null]    
Milestone code Milestone codes can be used to track specific events that take place for a particular kind of contracting process. For example, a code of ‘approvalLetter’ could be used to allow applications to understand this milestone represents the date an approvalLetter is due or signed. Milestone codes is an open codelist, and codes should be agreed among data producers and the applications using that data.
dueDate [string, null] date-time  
Due date The date the milestone is due.
dateMet [string, null] date-time  
Date met The date on which the milestone was met.
dateModified [string, null] date-time  
Date modified The date the milestone was last reviewed or modified and the status was altered or confirmed to still be correct.
status [string, null]    
Status The status that was realized on the date provided in dateModified, drawn from the milestoneStatus codelist.
documents array[Document]    
Documents

List of documents associated with this milestone (Deprecated in 1.1).

See Document

This property was deprecated in version 1.1

Inclusion of documents at the milestone level is now deprecated. Documentation should be attached in the tender, award, contract or implementation sections, and titles and descriptions used to highlight the related milestone. Publishers who wish to continue to provide documents at the milestone level should explicitly declare this by using the milestone documents extension.

Notes:

  • The dateModified field should be changed whenever the progress towards a milestone is reviewed, and the status either updated, or re-confirmed.

The following extensions to milestone are available

Milestone documents
Documents at the milestone level were deprecated in OCDS 1.1. This extension re-introduces the ability to attach documents to each individual milestone.

The following are community extensions and are not maintained by Open Contracting Partnership.

Value

Financial values should always be published with a currency attached.

Title Description Type Format Required
amount [number, null]    
Amount Amount as a number.
currency [string, null]    
Currency The currency for each amount should always be specified using the uppercase 3-letter currency code from ISO4217.

Support for exchange rates, and tax information, can be provided using extensions.

The following extensions for value are available

The following are community extensions and are not maintained by Open Contracting Partnership.

RelatedProcess

In OCDS each contracting process can have only one planning and tender stage. There are a number of cases where it is important to know about related planning and tendering processes, including:

  • When one planning process results in many tenders;
  • What a contract is awarded following two distinct, but related, tender processes, such as in national frameworks with locally run mini-competitions;
  • When a contract results in the award of sub-contracts - and those sub-contracts are also tracked using OCDS;
  • When a contract is coming up for renewal or replacement, and there is a contracting process to award the renewal/replacement contract;

In all these cases, the relatedProcess block can be used to cross-reference between the relevant open contracting processes using their ocid.

Title Description Type Format Required
id [string]    
Relationship ID A local identifier for this relationship, unique within this array.
relationship [array, null]    
Relationship Specify the type of relationship using the related process codelist.
title [string, null]    
Related process title The title of the related process, where referencing an open contracting process, this field should match the tender/title field in the related process.
scheme [string, null]    
Scheme The identification scheme used by this cross-reference from the related process scheme codelist codelist. When cross-referencing information also published using OCDS, an Open Contracting ID (ocid) should be used.
identifier [string, null]    
Identifier The identifier of the related process. When cross-referencing information also published using OCDS, this should be the Open Contracting ID (ocid).
uri [string, null] uri  
Related process URI A URI pointing to a machine-readable document, release or record package containing the identified related process.

A related process can be declared at two points in an OCDS release.

(1) At the release level - used to point backwards to prior processes, such as planning or framework establishment.

(2) At the contract level - used to point onward to sub-contracts, renewal or replacement processes that relate solely to the particular contract the property appears in.

As well as providing this machine-readable link between processes, publishers may also provide links to human-readable documentation in the relevant documents blocks. For example:

  • When recording a release/relatedProcess pointing to the ocid of the planning process that resulted in a tender, a tender/documents entry with a documentType of ‘procurementPlan’ and a link to web pages about the procurement plan could be provided;
  • When recording a contract/relatedProcess pointing to the ocid of a sub-contracting process, a contract/documents entry with a documentType of ‘subContract’ and a title that describes it as the subcontracting process, could be provided;
  • When recording a contract/relatedProcess pointing to the ocid of a tender process to renew a given contract, a contract/documents entry with a documentType of ‘tenderNotice’ and a title that describes it as the successor process, could be provided;

Location

The addition of location information is currently handled through a proposed extension to the standard.

Publisher

The publisher block is used in release and record packages to identify the source of a dataset.

Title Description Type Format Required
publisher object   Required
Publisher Information to uniquely identify the publisher of this package.
publisher/name string   Required
Name The name of the organization or department responsible for publishing this data.
publisher/scheme [string, null]    
Scheme The scheme that holds the unique identifiers used to identify the item being identified.
publisher/uid [string, null]    
uid The unique ID for this entity under the given ID scheme. Note the use of ‘uid’ rather than ‘id’. See issue #245.
publisher/uri [string, null] uri  
URI A URI to identify the publisher.

Language

Many publishers need to be able to share key data in multiple languages. All free-text title and description fields in the Open Contracting Data Standard can be given in one or more languages.

Language variations are included by a copy of multi-lingual fields, suffixed with a language code.

E.g. title and title_es

In order to allow users to identify the language used in non-suffixed fields, OCDS release and records should declare the default language in the language field.

Languages should be identified using language tags taken from BCP47. The specification allows BCP47 values in order to accommodate variations in dialect where this is important. However, publishers should use the two letter ISO639-1 two-letter language tags in the vast majority of circumstances, and should not assume that the users are able to distinguish between sub-tag variations (for example, OCDS publishers should strongly prefer ‘en’ over ‘en_US’ or ‘en_GB’).

To include a language variation of a field, the field name should be suffixed with _ and the appropriate language tag. For example: title_es for Spanish.

Worked example

A contract for ‘Software consultancy services’ may be published in a release with the default language sent to ‘en’ (the ISO639-1 code for English). The following examples give the description of an item as English, French and Spanish.

json

{
    "language": "en",
    "tender": {
        "item": {
            "description": "Software consultancy services",
            "description_es": "Servicios de consultoria en software",
            "description_fr": "Services de conseil en logiciels"
        }
    }
}

csv

description description_es description_fr
Software consultancy services Servicios de consultoria en software Services de conseil en logiciels

Release handling

The full OCDS data model is based on the idea of publishing a new release every time information about a contracting process changes. This way, users can gain a full view of change over time, and third-parties can understand what needs to be updated in any system that is tracking the progress of a contracting process.

Publishers will need to choose how to generate new releases, and whether to repeat information in each release, or just to provide changes. This choice should be based on an understanding the merging process that is used to generate a snapshot record of a full contracting process.

This model also requires publishers to pay careful attention to null values and missing fields.

Empty fields

Fields that are not being used, or that have no value, can be excluded in their entirety (key and value) from a published file.

Only including fields which have values will keep versioned datasets cleaner.

Emptying fields and values

There may be cases where a publisher needs to remove, rather than update, a value which was set in a previous release. In this case, the fields should explicitly be set to null.

The following describes how null values will be handled in the compilation of a record:

  • If a field is included with a value in one release, and then set to null in a subsequent release, that field will be recorded as null in the compiled record (though past values of it should remain in the versioned section of the record).
  • If a field is set to null in one release, and is also set to null in a subsequent release, it will be recorded as null as per the original release, and the record will not show any change based on the subsequent release I.e. fields that are set to null are recorded as such and then only changed if the value is set.
  • If a field is set to null in one release, and then has a value in a subsequent release, it will first appear in the record, and the version section of the record as null and then with the subsequent value.
  • If a field does not appear in one release, and then appears with a value in a subsequent release, it will first appear in the record, and the version section of the record, when the first release that contains it is compiled into the record.