Building Blocks

In mapping your data to OCDS, or using OCDS data, you will encounter a number of common data structures.

Sections and structure

An OCDS document is made up of a number of sections. These are:

  • release metadata - contextual information about each release of data;

    • parties - information about the organizations and other participants involved in the contracting process;

    • planning - information about the goals, budgets and projects a contracting process relates to;

    • tender - information about how a tender will take place, or has taken place;

    • awards - information on awards made as part of a contracting process;

    • contract - information on contracts signed as part of a contracting process;

      • implementation - information on the progress of each contract towards completion.

These are represented in a JSON document as follows:

  "language": "en",
  "ocid": "contracting-process-identifier",
  "id": "release-id",
  "date": "ISO-date",
  "tag": [
  "initiationType": "tender",
  "parties": {},
  "buyer": {},
  "planning": {},
  "tender": {},
  "awards": [
  "contracts": [
      "implementation": {}

Building blocks: fields

The OCDS schema sets out the fields that ought to be included in each section (where applicable), making use of simple re-usable building blocks (field structures) to represent data.

For example, common building blocks are provided for:

  • Parties (Organizations)

  • Amounts

  • Items

  • Time periods

  • Documents

  • Milestones


    "address": {
        "countryName": "United Kingdom",
        "locality": "London",
        "postalCode": "N11 1NP",
        "region": "London",
        "streetAddress": "4, North London Business Park, Oakleigh Rd S"
    "contactPoint": {
        "email": "",
        "faxNumber": "01234 345 345",
        "name": "Procurement Team",
        "telephone": "01234 345 346",
        "url": ""
    "id": "GB-LAC-E09000003",
    "identifier": {
        "id": "E09000003",
        "legalName": "London Borough of Barnet",
        "scheme": "GB-LAC",
        "uri": ""
    "name": "London Borough of Barnet",
    "roles": [
    "amount": 11000000,
    "currency": "GBP"
        "additionalClassifications": [
                "description": "Cycle path construction work",
                "id": "45233162-2",
                "scheme": "CPV",
                "uri": ""
        "classification": {
            "description": "Construction work for highways",
            "id": "45233130",
            "scheme": "CPV",
            "uri": ""
        "description": "string",
        "id": "0001",
        "quantity": 8,
        "unit": {
            "name": "Miles",
            "value": {
                "amount": 137000,
                "currency": "GBP"
    "endDate": "2011-08-01T23:59:00Z",
    "startDate": "2010-07-01T00:00:00Z"
        "datePublished": "2010-05-10T10:30:00Z",
        "description": "Award of contract to build new cycle lanes in the centre of town to AnyCorp Ltd.",
        "documentType": "notice",
        "format": "text/html",
        "id": "0007",
        "language": "en",
        "title": "Award notice",
        "url": ""
    "description": "A consultation period is open for citizen input to shape the final plans.",
    "dueDate": "2015-04-15T17:00:00Z",
    "id": "0001",
    "title": "Consultation Period"

Using building blocks

These building blocks can be used in various different sections. For example, items can occur in tender (to indicate the items that a buyer wishes to buy), in an award object (to indicate the items that an award has been made for) and in a contract object (to indicate the items listed in the contract).

In addition to these building blocks, the OCDS schema sets out the specific ways they can be used in each section, and describes a number of additional fields that can appear in specific section. For example, fields for:

  • titles and descriptions of tenders, awards and contracts

  • procurementMethod

  • awardCriteria

  • submissionMethod

  • etc.

Many of these fields make use of lightweight codelists provided by OCDS.


In some cases, publishers or users need building blocks and fields which are not provided in the core OCDS schema.

We maintain a list of extensions that provide additional building blocks and fields.

Field level mapping

The Open Contracting Data Standard helpdesk maintain a field-level mapping template that can be used to cross-walk between your internal data systems and OCDS.


OCDS defines two kinds of codelist:

  • Closed codelists provide a fixed list of values. When using a field with a closed codelist, publishers need to use an option from the published lists. This supports the global comparability of OCDS data on key dimensions.

  • Open codelists provide representative values. However, publishers can suggest amendments to these codelists, or provide their own extended values.

Codelist values are case sensitive strings with associated labels, available in each language OCDS has been translated into.

Publishers need to map their existing classification systems to OCDS codes wherever possible. Many closed codelist fields are paired with a detail field where more detailed classification information can be provided.

Worked Example

In the EU, contracts can be initiated through a number of different procedures including:

  • Open procedure;

  • Restricted procedure;

  • Competitive procedure with negotiation;

  • Competitive dialogue; and

  • Innovation partnership

However, to support comparison across continents, the main OCDS procurement method codelist is a closed codelist with four values:






All interested suppliers can submit a tender.



Only qualified suppliers are invited to submit a tender.



The procuring entity contacts a number of suppliers of its choice.



The contract is awarded to a single supplier without competition.

All procedures need to be mapped to one of these options.

To publish OCDS data, an EU publisher with data categorized by EU procedures needs to map the longer list of procedures to the narrower OCDS codelist and provide the codelist value in the procurementMethod field. They can then provide the more detailed procedure type in an extended procurementMethodDetails field.

For an Open Procedure, when a free-text justification of why the procedure was chosen is available, this would end up as:

    "procurementMethodDetails":"Open Procedure",
    "procurementMethodRationale":"To maximize competition."