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 release packages and how to compile releases into records.
Releases are immutable – presenting information about a particular event in the lifetime of a contracting (or planning) process. Publishers must not edit a release after publication; a new release can be created by changing the release's id and date.
Releases must be published within a release package.
Note: If any conflicts are found between this text, and the text within the schema, the schema takes precedence.
:class: note
This page presents the release schema in tables, with additional information in paragraphs. You can also download the canonical version of the release schema as [JSON Schema](../../build/current_lang/release-schema.json), download it as a [CSV spreadsheet](../../build/current_lang/release-schema.csv), view it in an [interactive browser](release), or access it through the [Field-Level Mapping Template](https://www.open-contracting.org/resources/ocds-field-level-mapping-template/).
The full OCDS data model is based on the idea of publishing a new release every time information about a contracting (or planning) 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 (or planning) 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 ought to be based on an understanding of the merging process that is used to generate a snapshot record of a full contracting (or planning) process.
In this model, publishers need to to pay careful attention to null values and missing fields.
Fields that are not being used, or that have no value, should be excluded in their entirety (key and value) from a published file.
Only including fields which have values will keep versioned datasets cleaner.
There can 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 must be set to null. See the merging documentation for more details.
OCDS 1.1 allowed data to be published in multiple languages by suffixing a language code to a field name: for example, `title` for the default language and `title_es` for Spanish. OCDS 1.2 uses [full-file translations](../guidance/map/translations), instead.
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.
A release has a tag to indicate whether it is about a planning process or a contracting process and, if it is about the latter, to indicate the stage of the contracting process to which it relates. However, there are no formal restrictions on when information about a stage of the process can be provided.
For example, a publisher announcing the signing of a contract with a 'contract' tag might 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.
All new information about a contracting (or planning) process is described within a release.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0
:title: release
```
:collapse: planning,tender,awards,contracts,parties,buyer,relatedProcesses
:list: release
:tag: release
Each of the organizations referenced in a release must be included in the parties section.
In OCDS 1.0, the details (address, contact point, etc.) of the organizations involved in a contracting process were repeated across many fields (`tenderers`, `suppliers`, etc.). In OCDS 1.1, these details are instead collected under a top-level `parties` array, with the other fields referencing entries in this array, using [organization references](#organizationreference). This reduces repetition and supports publication of information about additional organizations: for example, multiple buyers.
Note that the organization references allow, but deprecate, the fields for organization details.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/parties
:expand: roles
:title: parties
```
The following details can be provided for each organization.
:pointer: /definitions/Organization
:collapse: identifier,additionalIdentifiers,address,contactPoint
:list: parties
Each organization has a details object. Through extensions, this can be used to provide detailed classification of organizations.
:list: partyDetail
:tag: parties
The planning section is used in a planning process. This includes information about, for example, needs identification, budget planning, the parent project and market research. Background documents such as feasibility studies and project plans can also be included in this section.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/planning
:title: planning
```
:pointer: /definitions/Planning
:collapse: budget,project,documents,milestones
:list: planning
:tag: planning
Apart from documents, the majority of planning 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 (or planning) process to existing projects and budgets even where linked data is not available.
The planning.budget.projectID field should not be used to disclose the identifier of an infrastructure or PPP project. Rather, this field is used to disclose the identifier of a programme of work as it appears in a budget, like a national or state budget. Since such programmes of work can include many infrastructure projects, it is necessary to disclose their identifiers separately. Use the the planning.project.id field to disclose the identifier of an infrastructure or PPP project.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/planning/budget
:title: budget
```
:pointer: /definitions/Budget
:collapse: amount
:list: budget
The project object includes details of the infrastructure or public-private partnership (PPP) project to which a planning process is related. This object is designed to allow both machine-readable linkable data about the parent project, cross-referencing to data held in other standards such as the Open Contracting for Infrastructure Data Standards Toolkit (OC4IDS) and the OCDS for PPPs profile, and human readable description of the parent project, supporting users to understand the relationship of the contracting (or planning) process to their parent project even where linked data is not available.
Where there is a separate OC4IDS dataset that describes the project the identifier from this dataset should be referenced in project.id. Where there is not a separate project dataset an appropriate project identifier will need to be generated. For more information on project identifiers see OC4IDS Project Identifiers.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/planning/project
:title: project
```
:pointer: /definitions/Project
:collapse: totalValue,additionalClassifications,locations
:list:
The tender section includes details of the announcement that an organization intends to source some particular goods, services or works and to establish one or more contract(s) for these.
It can contain details of a forthcoming process to receive and evaluate proposals to supply these goods, services or works and can also be used to record details of a completed tender stage, including details of bids received.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/tender
:title: tender
```
:pointer: /definitions/Tender
:collapse: items,tenderPeriod,enquiryPeriod,awardPeriod,contractPeriod,tenderers,documents,milestones,amendment,amendments,minValue,value,procuringEntity
:list: tender
:tag: tender
The Bid statistics and details extension can be used to provide bid statistics and detailed information about individual bids.
The award section is used to announce any awards issued for this tender. There can be multiple awards made. Releases can contain all, or a subset, of these awards. A related award block is required for every contract block, as the award contains information on the suppliers. In particular cases there can be multiple suppliers for a single award: for example, in the case of consortia and in framework agreements.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/awards/0
:title: award
```
:pointer: /definitions/Award
:collapse: items,value,suppliers,contractPeriod,documents,amendment,amendments
:list: award
:tag: award
The contract section is used to provide details of contracts that have been entered into. Every contract must have a related award, linked via the awardID field. This is because supplier information is contained within the 'award'.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/contracts/0
:title: contract
```
:pointer: /definitions/Contract
:collapse: period,value,items,documents,implementation,relatedProcesses,milestones,amendment,amendments
:list: contract
:tag: contract
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:
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/contracts/0/implementation
:title: implementation
```
:pointer: /definitions/Implementation
:collapse: transactions,milestones,documents
:list: implementation
Information on subcontracts is not currently included in the core OCDS schema, but might be handled by proposed extensions
:tag: implementation
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/contracts/0/implementation/transactions/0
:title: transaction
```
:pointer: /definitions/Transaction
:collapse: providerOrganization,receiverOrganization,amount,payer,payee,value
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 can be used to cross-reference to a third party source of data, and ought to reuse identifiers from that source.
To represent planned payments, use [Milestones](#milestones) instead.
In most circumstances, the payer identifier will match that of the buyer, and the payee identifier will match that of the supplier.
:list: transaction
See milestone reference below.
The implementation milestones should be updated to reflect when they are met.
Documents related to contract implementation are stored here. This can include subcontracts.
See document reference below.
A release may amend values 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.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/tender/amendments/0
:title: amendments
```
:pointer: /definitions/Amendment
:collapse: changes
:tag: amendment
Structured information on the former value of specific fields may be provided instead 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](../guidance/map/amendments) for more details.
The following building blocks are commonly re-used throughout the standard.
See the [parties](#parties) section.
An organization reference consists of two main components:
- An
idused to cross-reference the entry in the parties section that contains full information on this organization; - A
namefield 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.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/buyer
:title: organizationReference
```
:tag: organization_reference
See the parties section.
The identifier block provides a way to identify the legal entities involved in a contracting (or planning) process.
When describing an organizational unit (for example, a department or branch of an organization), the identifier field should identify the main organization. The other fields should describe the organizational unit. For more information, see organizational units.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/parties/0
:expand: identifier
:title: party
```
:pointer: /definitions/Identifier
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/parties/0
:expand: address
:title: party
```
:pointer: /definitions/Address
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/parties/0
:expand: contactPoint
:title: party
```
:pointer: /definitions/ContactPoint
Documents can 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.
Documents related to contracting (or planning) processes should be public by default. For more information, see the Open Contracting Partnership's report Mythbusting Confidentiality in Public Contracting and the Center for Global Development's Principles on Commercial Transparency in Public Contracts.
Documents should be published at their own stable URLs, accessible for free and without the need to search or login, and available at the time of publication of the OCDS release that refers to them.
OCDS allows summarizing information in the document's description field. Providing clear summaries is a good practice, as it allows applications to display this information in a user-interface and thus enables users to read key facts without having to search through the whole document.
If a document contains multiple languages, use the languages field to list the languages used in the document. If there are multiple versions of a document, each in a different language, add a separate Document object for each version of the document.
If an alternative representation of the data in an OCDS release exists, a link should be provided in the relevant .documents array. For example, if the data in an OCDS award release is also available as an HTML page, a link to the HTML page should be provided in awards.documents. Links to alternative representations of an entire contracting process should be provided in tender.documents.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/tender/documents/0
:title: document
```
:pointer: /definitions/Document
:list: document
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 can 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.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/awards/0/contractPeriod
:title: period
```
:pointer: /definitions/Period
OCDS makes use of ISO8601 date-times, following RFC3339 §5.6.
A time and timezone/offset must 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 can have legal significance, and where users of the data might 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 use sensible defaults for each field. For example, the startDate time of a clarification period can 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 '00:00:00' and either 'Z' (for UTC) or the timezone of the publisher. However, if the date is an endDate in a period object the default time value should be set to '23:59:59', indicating that the time refers to the end of the given date.
The items block is used to list the line-items associated with a tender, award or contract.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/tender/items/0
:title: items
```
:pointer: /definitions/Item
:collapse: classification,additionalClassifications,unit
:list: item
The unit block allows detailed specification of the parameters and price of units that make up a line-item.
If the Quantities, Units, Dimensions and Data Types Ontologies unit classification scheme is used, then publishers can use its CamelCase unit names, such as "SquareMile", in the unit.name field.
Other unit classification schemes can be used, including those in the unitClassificationScheme codelist.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/tender/items/0
:expand: unit
:title: unit
```
:pointer: /definitions/Item/properties/unit
:collapse: value
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/tender/items/0/classification
:title: classification
```
:pointer: /definitions/Classification
Milestone information can be included in the planning, tender, contract and contract implementation blocks.
The dateModified field should be changed whenever the progress towards a milestone is reviewed, and the status either updated, or re-confirmed.
[How to represent planned payments](../guidance/map/milestones.md#delivery-and-payment-data)
For delivery milestones, if there is a time frame for delivery, use .dueAfterDate for the start date and .dueDate for the end date.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/planning/milestones/0
:title: milestones
```
:pointer: /definitions/Milestone
:collapse: documents
:list: milestones
:tag: milestone
currency, amountNet and amountGross should be provided, wherever possible.
amount is defined as:
If both the amountNet and the amountGross match this definition, enter the amountNet as the amount.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/awards/0/value
:title: value
```
:pointer: /definitions/Value
Support for exchange rates can be provided using extensions.
In OCDS each contracting process can have only one tender stage. There are a number of cases where it is important to know about related contracting processes, including:
- When one planning process results in many tenders;
- When 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 should be used to cross-reference between the relevant contracting processes using their ocid.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/relatedProcesses
:title: relatedProcesses
```
:pointer: /definitions/RelatedProcess
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 field 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/relatedProcesspointing to the ocid of the planning process that resulted in a tender, atender/documentsentry with adocumentTypeof 'procurementPlan' and a link to web pages about the procurement plan could be provided; - When recording a
contract/relatedProcesspointing to the ocid of a sub-contracting process, acontract/documentsentry with adocumentTypeof 'subContract' and a title that describes it as the subcontracting process, could be provided; - When recording a
contract/relatedProcesspointing to the ocid of a contracting process to renew a given contract, acontract/documentsentry with adocumentTypeof 'tenderNotice' and a title that describes it as the successor process, could be provided;
The Location subschema can be used to provide the geographic coordinates or standardized location identifiers of the proposed or executed contract delivery in the Project, tender and Item objects.
:class: hint
```{jsoninclude} ../examples/release_schema_reference/release_package.json
:jsonpointer: /releases/0/planning/project/locations/0
:title: location
```
:pointer: /definitions/Location
The entries of the top-level links array are Link objects:
:pointer: /definitions/Link
:pointer: /definitions/SimpleIdentifier