diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 698b4754c..2f503a7c7 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -56,7 +56,13 @@ For example, a publisher announcing the signing of a contract with a 'contract' ### Release -All new information about a contracting (or planning) process is described within a release. +All new information about a contracting (or planning) process is described within a release. + +A release is defined as: + +```{jsoninclude-quote} ../../build/current_lang/release-schema.json +:jsonpointer: /description +``` ````{admonition} Example :class: hint @@ -67,6 +73,8 @@ All new information about a contracting (or planning) process is described withi ``` ```` +Each release has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :collapse: planning,tender,awards,contracts,parties,buyer,relatedProcesses ``` @@ -81,7 +89,7 @@ All new information about a contracting (or planning) process is described withi ### Parties -Each of the organizations referenced in a release must be included in the parties section. +Each of the organizations referenced in a release must be included in the parties section. ```{versionadded} 1.1 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. @@ -89,6 +97,11 @@ In OCDS 1.0, the details (address, contact point, etc.) of the organizations inv Note that the organization references allow, but deprecate, the fields for organization details. ``` +An `Organization` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Organization +``` + ````{admonition} Example :class: hint @@ -99,7 +112,7 @@ Note that the organization references allow, but deprecate, the fields for organ ``` ```` -The following details can be provided for each organization. +Each `Organization` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Organization @@ -122,7 +135,12 @@ Each organization has a `details` object. Through extensions, this can be used t ### Planning -The planning section is used in a planning process. This includes information about, for example, needs identification, budget planning and market research. Background documents such as feasibility studies and project plans can also be included in this section. +The `planning` section is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Planning +``` + +Background documents such as feasibility studies and project plans can also be included in this section. ````{admonition} Example :class: hint @@ -133,6 +151,8 @@ The planning section is used in a planning process. This includes information ab ``` ```` +`planning` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Planning :collapse: budget,project,documents,milestones @@ -142,13 +162,18 @@ The planning section is used in a planning process. This includes information ab :list: planning ``` -```{workedexamplelist} The following worked examples are available for plannings +```{workedexamplelist} The following worked examples are available for planning :tag: planning ``` #### Budget -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](https://specs.frictionlessdata.io/fiscal-data-package/) or [International Aid Transparency Initiative Standard](https://iatistandard.org/en/), 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. +Apart from documents, the majority of planning information is held within the `planning/budget` section. 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](https://specs.frictionlessdata.io/fiscal-data-package/) or [International Aid Transparency Initiative Standard](https://iatistandard.org/en/), 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` section is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Budget +``` ````{admonition} Example :class: hint @@ -159,6 +184,8 @@ Apart from documents, the majority of planning information is held within the bu ``` ```` +The `planning/budget` section has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Budget :collapse: amount @@ -170,6 +197,11 @@ Apart from documents, the majority of planning information is held within the bu #### Project +The `planning/project` section is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Project +``` + ````{admonition} Example :class: hint @@ -179,20 +211,23 @@ Apart from documents, the majority of planning information is held within the bu ``` ```` +The `planning/project` section has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Project :collapse: totalValue,additionalClassifications,locations ``` -```{extensionlist} The following extensions are available for project -:list: -``` - ### Tender -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. +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. +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. + +The `tender` section is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Tender +``` ````{admonition} Example :class: hint @@ -203,6 +238,8 @@ It can contain details of a forthcoming process to receive and evaluate proposal ``` ```` +Each `tender` section has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Tender :collapse: items,tenderPeriod,enquiryPeriod,awardPeriod,contractPeriod,tenderers,documents,milestones,amendment,amendments,minValue,value,procuringEntity @@ -224,6 +261,11 @@ The [Bid statistics and details](https://extensions.open-contracting.org/en/exte 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](../guidance/map/buyers_suppliers.md#consortia-suppliers) and in [framework agreements](../guidance/map/framework_agreements). +An `Award` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Award +``` + ````{admonition} Example :class: hint @@ -233,6 +275,8 @@ The award section is used to announce any awards issued for this tender. There c ``` ```` +Each `Award` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Award :collapse: items,value,suppliers,contractPeriod,documents,amendment,amendments @@ -248,7 +292,12 @@ The award section is used to announce any awards issued for this tender. There c ### Contract -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'. +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'. + +A `Contract` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Contract +``` ````{admonition} Example :class: hint @@ -259,6 +308,8 @@ The contract section is used to provide details of contracts that have been ente ``` ```` +Each `Contract` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Contract :collapse: period,value,items,documents,implementation,relatedProcesses,milestones,amendment,amendments @@ -274,7 +325,12 @@ The contract section is used to provide details of contracts that have been ente ### 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: +Implementation information can be updated over the course of a contract. It belongs nested within the contract it relates to. + +The `contracts/implementation` section is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Implementation +``` ````{admonition} Example :class: hint @@ -285,6 +341,8 @@ Implementation information can be updated over the course of a contract. It belo ``` ```` +Each `contracts/implementation` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Implementation :collapse: transactions,milestones,documents @@ -302,6 +360,19 @@ Information on subcontracts is not currently included in the core OCDS schema, b #### Transaction +Transactions can be used to represent actual flows of money between organizations in relation to a contract. As with the [budget](#budget) block, transactions can reference a third-party `source` of data, and ought to reuse identifiers from that source. + +```{note} +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`. + +A `Transaction` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Transaction +``` + ````{admonition} Example :class: hint @@ -311,19 +382,13 @@ Information on subcontracts is not currently included in the core OCDS schema, b ``` ```` +Each `Transaction` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Transaction :collapse: providerOrganization,receiverOrganization,amount,payer,payee,value ``` -The transaction block is modelled on the [International Aid Transparency Initiative (IATI) transaction element](https://iatistandard.org/en/iati-standard/203/activity-standard/iati-activities/iati-activity/transaction/), and can be used to represent actual flows of money between organizations in relation to this contract. As with the [budget](#budget) block, this can be used to cross-reference to a third party `source` of data, and ought to reuse identifiers from that source. - -```{note} -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`. - ```{extensionlist} The following extensions are available for transactions :list: transaction ``` @@ -346,6 +411,11 @@ A release may amend values from a previous release. Whilst the release & record 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. +An `Amendment` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Amendment +``` + ````{admonition} Example :class: hint @@ -355,6 +425,8 @@ The amendment array in a tender, award or contract block provides the ability to ``` ```` +Each `Amendment` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Amendment :collapse: changes @@ -390,6 +462,11 @@ An organization reference consists of two main components: * An `id` used to cross-reference the entry in the [parties](#parties) section that contains full information on this organization; * A `name` field that repeats the name given in the [parties](#parties) section, provided for the convenience of users viewing the data, and to support detection of mistakes in cross-referencing. +An `OrganizationReference` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/OrganizationReference +``` + ````{admonition} Example :class: hint @@ -399,7 +476,7 @@ An organization reference consists of two main components: ``` ```` -```{workedexamplelist} The following worked examples are available for organization reference +```{workedexamplelist} The following worked examples are available for organization references :tag: organization_reference ``` @@ -413,6 +490,11 @@ The identifier block provides a way to [identify the legal entities](identifiers 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](../guidance/map/organizational_units.md). +An `Identifier` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Identifier +``` + ````{admonition} Example :class: hint @@ -423,12 +505,19 @@ When describing an organizational unit (for example, a department or branch of a ``` ```` +Each `Identifier` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Identifier ``` #### Address +An `Address` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Address +``` + ````{admonition} Example :class: hint @@ -439,12 +528,19 @@ When describing an organizational unit (for example, a department or branch of a ``` ```` +Each `Address` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Address ``` #### ContactPoint +A `ContactPoint` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/ContactPoint +``` + ````{admonition} Example :class: hint @@ -455,6 +551,8 @@ When describing an organizational unit (for example, a department or branch of a ``` ```` +Each `ContactPoint` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/ContactPoint ``` @@ -473,6 +571,11 @@ If a document contains multiple languages, use the `languages` field to list the 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`. +A `Document` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Document +``` + ````{admonition} Example :class: hint @@ -482,6 +585,8 @@ If an alternative representation of the data in an OCDS release exists, a link s ``` ```` +Each `Document` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Document ``` @@ -492,9 +597,12 @@ If an alternative representation of the data in an OCDS release exists, a link s ### 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. +A `Period` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Period +``` -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. +`maxExtentDate` can be used to indicate the latest date up until which the period could be extended without an amendment. ````{admonition} Example :class: hint @@ -505,6 +613,8 @@ Periods can also include a `maxExtentDate` which indicates the latest possible e ``` ```` +Each `Period` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Period ``` @@ -535,7 +645,10 @@ In the event that a date field is not bound to a specific time at all, publisher ### Item -The items block is used to list the line-items associated with a tender, award or contract. +An `Item` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Item +``` ````{admonition} Example :class: hint @@ -546,6 +659,8 @@ The items block is used to list the line-items associated with a tender, award o ``` ```` +Each `Item` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Item :collapse: classification,additionalClassifications,unit @@ -557,6 +672,11 @@ The items block is used to list the line-items associated with a tender, award o #### Unit +A `Unit` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Unit +``` + ````{admonition} Example :class: hint @@ -567,6 +687,8 @@ The items block is used to list the line-items associated with a tender, award o ``` ```` +Each `Unit` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Item/properties/unit :collapse: value @@ -574,6 +696,11 @@ The items block is used to list the line-items associated with a tender, award o #### ImmediateContainer +An `ImmediateContainer` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/ImmediateContainer +``` + ````{admonition} Example :class: hint @@ -584,12 +711,19 @@ The items block is used to list the line-items associated with a tender, award o ``` ```` +Each `ImmediateContainer` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Item/properties/immediateContainer ``` ### Classification +A `Classification` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Classification +``` + ````{admonition} Example :class: hint @@ -599,6 +733,8 @@ The items block is used to list the line-items associated with a tender, award o ``` ```` +Each `Classification` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Classification ``` @@ -615,6 +751,11 @@ The `dateModified` field should be changed whenever the progress towards a miles For delivery milestones, if there is a time frame for delivery, use `.dueAfterDate` for the start date and `.dueDate` for the end date. +A `Milestone` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Milestone +``` + ````{admonition} Example :class: hint @@ -624,6 +765,8 @@ For delivery milestones, if there is a time frame for delivery, use `.dueAfterDa ``` ```` +Each `Milestone` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Milestone :collapse: documents @@ -639,6 +782,11 @@ For delivery milestones, if there is a time frame for delivery, use `.dueAfterDa ### Value +A `Value` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Value +``` + `currency`, `amountNet` and `amountGross` should be provided, wherever possible. `amount` is defined as: @@ -657,6 +805,8 @@ If both the `amountNet` and the `amountGross` match this definition, enter the ` ``` ```` +Each `Value` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Value ``` @@ -674,6 +824,23 @@ In OCDS each contracting process can have only one tender stage. There are a num In all these cases, the `relatedProcess` block should be used to cross-reference between the relevant contracting processes using their `ocid`. +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/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 contracting 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; + +A `RelatedProcess` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/RelatedProcess +``` + ````{admonition} Example :class: hint @@ -683,23 +850,18 @@ In all these cases, the `relatedProcess` block should be used to cross-reference ``` ```` +Each `RelatedProcess` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :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: +### Location -* 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 contracting 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; +A `Location` is defined as: -### Location +```{field-description} ../../build/current_lang/release-schema.json /definitions/Location +``` ````{admonition} Example :class: hint @@ -710,44 +872,65 @@ As well as providing this machine-readable link between processes, publishers ma ``` ```` +Each `Location` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Location ``` ### Link -The entries of the top-level `links` array are `Link` objects: +A `Link` is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Link +``` + +Links appear in the top-level `links` array: ```{field-description} ../../build/current_lang/release-schema.json /properties/links ``` +Each `Link` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Link ``` ### Quantity +A `Quantity` is defined as: + ```{field-description} ../../build/current_lang/release-schema.json /definitions/Quantity ``` +Each `Quantity` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Quantity ``` ### SimpleIdentifier +A `SimpleIdentifier` is defined as: + ```{field-description} ../../build/current_lang/release-schema.json /definitions/SimpleIdentifier ``` +Each `SimpleIdentifier` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/SimpleIdentifier ``` ### SimpleUnit +A `SimpleUnit` is defined as: + ```{field-description} ../../build/current_lang/release-schema.json /definitions/SimpleUnit ``` +Each `SimpleUnit` has the following fields: + ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/SimpleUnit ```