From 8bfbe719ec69b0a8c64ae2d34416870f83f6792f Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 23 Oct 2024 16:18:13 +1300 Subject: [PATCH 01/13] docs/schema/reference.md: Add organization definition --- docs/schema/reference.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 22cfafe62..3b5441efb 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -81,7 +81,12 @@ 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. + +An organization is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Organization +``` ```{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. From 244ef1958264817fbf4a83368e4ed901628aef3e Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Fri, 25 Oct 2024 12:27:51 +1300 Subject: [PATCH 02/13] docs/schema/reference.md: Add subschema descriptions --- docs/schema/reference.md | 262 ++++++++++++++++++++++++++++++++------- 1 file changed, 220 insertions(+), 42 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index adb56b241..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 ``` @@ -83,17 +91,17 @@ All new information about a contracting (or planning) process is described withi Each of the organizations referenced in a release must be included in the parties section. -An organization is defined as: - -```{field-description} ../../build/current_lang/release-schema.json /definitions/Organization -``` - ```{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. 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 @@ -104,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 @@ -127,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 @@ -138,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 @@ -147,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 @@ -164,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 @@ -175,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 @@ -184,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 @@ -208,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 @@ -229,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 @@ -238,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 @@ -253,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 @@ -264,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 @@ -279,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 @@ -290,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 @@ -307,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 @@ -316,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 ``` @@ -351,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 @@ -360,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 @@ -395,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 @@ -404,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 ``` @@ -418,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 @@ -428,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 @@ -444,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 @@ -460,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 ``` @@ -478,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 @@ -487,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 ``` @@ -497,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 @@ -510,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 ``` @@ -540,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 @@ -551,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 @@ -562,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 @@ -572,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 @@ -579,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 @@ -589,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 @@ -604,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 ``` @@ -620,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 @@ -629,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 @@ -644,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: @@ -662,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 ``` @@ -679,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 @@ -688,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 @@ -715,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 ``` From 87b73f464749d49a09367b27a1c389203ee7a92a Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 7 Nov 2024 14:21:02 +1300 Subject: [PATCH 03/13] docs/schema/reference.md: Don't quote full release description --- docs/schema/reference.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 2f503a7c7..f6aff3017 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -56,13 +56,7 @@ 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. - -A release is defined as: - -```{jsoninclude-quote} ../../build/current_lang/release-schema.json -:jsonpointer: /description -``` +A release describes a single contracting or planning process at a particular point in time. One process may be described by many releases. A release may repeat or update the information provided in previous releases about the process. ````{admonition} Example :class: hint From 36ece4f8e0aa41030b822a6a161b97ef2663ffe0 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 7 Nov 2024 14:24:30 +1300 Subject: [PATCH 04/13] docs/schema/reference.md: Remove parent objects from examples --- docs/schema/reference.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index f6aff3017..8eb7a4f90 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -516,9 +516,8 @@ An `Address` is defined as: :class: hint ```{jsoninclude} ../examples/release_schema_reference/release_package.json -:jsonpointer: /releases/0/parties/0 -:expand: address -:title: party +:jsonpointer: /releases/0/parties/0/address +:title: address ``` ```` @@ -539,9 +538,8 @@ A `ContactPoint` is defined as: :class: hint ```{jsoninclude} ../examples/release_schema_reference/release_package.json -:jsonpointer: /releases/0/parties/0 -:expand: contactPoint -:title: party +:jsonpointer: /releases/0/parties/0/contactPoint +:title: contactPoint ``` ```` @@ -675,8 +673,7 @@ A `Unit` is defined as: :class: hint ```{jsoninclude} ../examples/release_schema_reference/release_package.json -:jsonpointer: /releases/0/tender/items/0 -:expand: unit +:jsonpointer: /releases/0/tender/items/0/unit :title: unit ``` ```` @@ -699,8 +696,8 @@ An `ImmediateContainer` is defined as: :class: hint ```{jsoninclude} ../examples/release_schema_reference/release_package.json -:jsonpointer: /releases/0/tender/items/1 -:expand: immediateContainer +:jsonpointer: /releases/0/tender/items/1/immediateContainer +:expand: capacity :title: immediateContainer ``` ```` From d81af30ead34cc9e39d0ba06c41e60be37173bdb Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 7 Nov 2024 14:33:00 +1300 Subject: [PATCH 05/13] docs/schema/reference.md: Collapse references in jsonschema directives --- docs/schema/reference.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 8eb7a4f90..5b167f3ab 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -70,7 +70,7 @@ A release describes a single contracting or planning process at a particular poi Each release has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json -:collapse: planning,tender,awards,contracts,parties,buyer,relatedProcesses +:collapse: publisher,planning,tender,awards,contracts,parties,buyer,relatedProcesses,links ``` ```{extensionlist} The following extensions are available for release @@ -110,7 +110,7 @@ Each `Organization` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Organization -:collapse: identifier,additionalIdentifiers,address,contactPoint +:collapse: identifier,additionalIdentifiers,address,contactPoint,details/classifications ``` ```{extensionlist} The following extensions are available for organizations @@ -209,7 +209,7 @@ The `planning/project` section has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Project -:collapse: totalValue,additionalClassifications,locations +:collapse: totalValue,additionalClassifications,locations,sector ``` ### Tender @@ -236,7 +236,7 @@ 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 +:collapse: items,tenderPeriod,enquiryPeriod,awardPeriod,contractPeriod,tenderers,documents,milestones,amendment,amendments,minValue,value,procuringEntity,identifiers,maximumValue,deliveryLocations,deliveryAddresses,submissionTerms,exclusionGrounds,selectionCriteria ``` ```{extensionlist} The following extensions are available for the tender section @@ -273,7 +273,7 @@ Each `Award` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Award -:collapse: items,value,suppliers,contractPeriod,documents,amendment,amendments +:collapse: items,value,suppliers,contractPeriod,documents,amendment,amendments,maximumValue,estimatedValue ``` ```{extensionlist} The following extensions are available for award @@ -306,7 +306,7 @@ 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 +:collapse: period,value,items,documents,implementation,relatedProcesses,milestones,amendment,amendments,identifiers,maximumValue,estimatedValue ``` ```{extensionlist} The following extensions are available for contracts @@ -655,7 +655,7 @@ Each `Item` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Item -:collapse: classification,additionalClassifications,unit +:collapse: classification,additionalClassifications,unit,immediateContainer,deliveryLocations,deliveryAddresses ``` ```{extensionlist} These are extensions related to Items. @@ -706,6 +706,7 @@ Each `ImmediateContainer` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Item/properties/immediateContainer +:collapse: capacity ``` ### Classification @@ -898,6 +899,7 @@ Each `Quantity` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Quantity +:collapse: unit ``` ### SimpleIdentifier From cf29c74d48220fae972a4fd80c22bea3b6508ada Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 21 Nov 2024 12:33:32 +1300 Subject: [PATCH 06/13] docs/schema/reference.md: Add reminder to update release description --- docs/schema/reference.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 5b167f3ab..cfb5bd015 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -56,6 +56,8 @@ For example, a publisher announcing the signing of a contract with a 'contract' ### Release +% Align the sentence with the top-level `description` field of the `release-schema.json` file. + A release describes a single contracting or planning process at a particular point in time. One process may be described by many releases. A release may repeat or update the information provided in previous releases about the process. ````{admonition} Example From 907bea6fc56e28c85bfb8dc467e60ad0bc5b0d0a Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 28 Nov 2024 14:58:07 +1300 Subject: [PATCH 07/13] requirements.txt: Upgrade sphinxcontrib-opendataservices-jsonschema --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 9c2ea5690..1c7a3ab40 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,5 +5,5 @@ ocdskit==1.1.3 sphinx-design==0.4.1 sphinxcontrib-opencontracting==0.0.8 -sphinxcontrib-opendataservices-jsonschema==0.6.1 +sphinxcontrib-opendataservices-jsonschema==0.7.1 sphinxcontrib-opendataservices==0.5.0 From 261d30461abe37926391b78481ad5a44b4bbf72d Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 28 Nov 2024 14:58:39 +1300 Subject: [PATCH 08/13] docs/schema/reference.md (OrganizationReference): Replace Markdown content with jsonschema directive --- docs/schema/reference.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index cfb5bd015..7d141375d 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -453,11 +453,6 @@ 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 `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 @@ -476,6 +471,13 @@ An `OrganizationReference` is defined as: :tag: organization_reference ``` +Each `OrganizationReference` has the following fields: + +```{jsonschema} ../../build/current_lang/release-schema.json +:pointer: /definitions/OrganizationReference +:include: id,name +``` + ### Organization See the [parties](#parties) section. From 18da66233b20d8ef31e38655ca50b3b5fdf6149b Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 23 Dec 2024 15:03:05 +1300 Subject: [PATCH 09/13] docs/schema/reference.md: Quote descriptions from references --- docs/schema/reference.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 903462c90..381fc0494 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -257,6 +257,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). +The `awards` array is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /properties/awards +``` + An `Award` is defined as: ```{field-description} ../../build/current_lang/release-schema.json /definitions/Award @@ -290,6 +295,11 @@ Each `Award` has the following fields: 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 `contracts` array is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /properties/contracts +``` + A `Contract` is defined as: ```{field-description} ../../build/current_lang/release-schema.json /definitions/Contract @@ -323,7 +333,7 @@ Each `Contract` has the following fields: 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: +The `contracts/implementation` object is defined as: ```{field-description} ../../build/current_lang/release-schema.json /definitions/Implementation ``` @@ -364,6 +374,11 @@ 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`. +The `contracts/implementation/transactions` array is defined as: + +```{field-description} ../../build/current_lang/release-schema.json /definitions/Implementation/properties/transactions +``` + A `Transaction` is defined as: ```{field-description} ../../build/current_lang/release-schema.json /definitions/Transaction From 62390599679efc331302c372b2e9966eb39e471c Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 23 Dec 2024 15:08:27 +1300 Subject: [PATCH 10/13] docs/schema/reference.md: Replace 'section' with 'object' or 'array'. --- docs/schema/reference.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 381fc0494..2365efb4c 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -131,12 +131,12 @@ Each organization has a `details` object. Through extensions, this can be used t ### Planning -The `planning` section is defined as: +The `planning` object 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. +Background documents such as feasibility studies and project plans can also be included in `planning`. ````{admonition} Example :class: hint @@ -164,9 +164,9 @@ Background documents such as feasibility studies and project plans can also be i #### Budget -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. +Apart from documents, the majority of planning information is held within the `planning/budget` object. 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: +The `planning/budget` object is defined as: ```{field-description} ../../build/current_lang/release-schema.json /definitions/Budget ``` @@ -180,7 +180,7 @@ The `planning/budget` section is defined as: ``` ```` -The `planning/budget` section has the following fields: +The `planning/budget` object has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Budget @@ -193,7 +193,7 @@ The `planning/budget` section has the following fields: #### Project -The `planning/project` section is defined as: +The `planning/project` object is defined as: ```{field-description} ../../build/current_lang/release-schema.json /definitions/Project ``` @@ -207,7 +207,7 @@ The `planning/project` section is defined as: ``` ```` -The `planning/project` section has the following fields: +The `planning/project` object has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Project @@ -220,7 +220,7 @@ The `tender` section includes details of the announcement that an organization i 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: +The `tender` object is defined as: ```{field-description} ../../build/current_lang/release-schema.json /definitions/Tender ``` @@ -234,7 +234,7 @@ The `tender` section is defined as: ``` ```` -Each `tender` section has the following fields: +Each `tender` ojbect has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Tender From 31bd40bd446b2ce1117b491d54d5c24e9132f445 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Mon, 23 Dec 2024 15:10:25 +1300 Subject: [PATCH 11/13] docs/schema/reference.md: Fix typo --- docs/schema/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 2365efb4c..b7a484721 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -234,7 +234,7 @@ The `tender` object is defined as: ``` ```` -Each `tender` ojbect has the following fields: +Each `tender` object has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json :pointer: /definitions/Tender From 103b7715bdcd90fe6bc65acfad846b9fa8759288 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Tue, 24 Dec 2024 08:24:38 +1300 Subject: [PATCH 12/13] docs/schema/reference.md: Move worked example lists above jsonschema directives --- docs/schema/reference.md | 71 ++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 36 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index b7a484721..2d71d073b 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -68,6 +68,9 @@ A release describes a single contracting or planning process at a particular poi :title: release ``` ```` +```{workedexamplelist} The following worked examples are available for releases +:tag: release +``` Each release has the following fields: @@ -79,10 +82,6 @@ Each release has the following fields: :list: release ``` -```{workedexamplelist} The following worked examples are available for releases -:tag: release -``` - ### Parties Each of the organizations referenced in a release must be included in the parties section. @@ -108,6 +107,10 @@ An `Organization` is defined as: ``` ```` +```{workedexamplelist} The following worked examples are available for organizations +:tag: parties +``` + Each `Organization` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json @@ -125,10 +128,6 @@ Each organization has a `details` object. Through extensions, this can be used t :list: partyDetail ``` -```{workedexamplelist} The following worked examples are available for organizations -:tag: parties -``` - ### Planning The `planning` object is defined as: @@ -147,6 +146,10 @@ Background documents such as feasibility studies and project plans can also be i ``` ```` +```{workedexamplelist} The following worked examples are available for planning +:tag: planning +``` + `planning` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json @@ -158,10 +161,6 @@ Background documents such as feasibility studies and project plans can also be i :list: planning ``` -```{workedexamplelist} The following worked examples are available for planning -:tag: planning -``` - #### Budget Apart from documents, the majority of planning information is held within the `planning/budget` object. 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. @@ -234,6 +233,10 @@ The `tender` object is defined as: ``` ```` +```{workedexamplelist} The following worked examples are available for tenders +:tag: tender +``` + Each `tender` object has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json @@ -245,10 +248,6 @@ Each `tender` object has the following fields: :list: tender ``` -```{workedexamplelist} The following worked examples are available for tenders -:tag: tender -``` - ### Bids The [Bid statistics and details](https://extensions.open-contracting.org/en/extensions/bids/v1.1.4/) extension can be used to provide bid statistics and detailed information about individual bids. @@ -276,6 +275,10 @@ An `Award` is defined as: ``` ```` +```{workedexamplelist} The following worked examples are available for awards +:tag: award +``` + Each `Award` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json @@ -287,10 +290,6 @@ Each `Award` has the following fields: :list: award ``` -```{workedexamplelist} The following worked examples are available for awards -:tag: award -``` - ### 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'. @@ -314,6 +313,10 @@ A `Contract` is defined as: ``` ```` +```{workedexamplelist} The following worked examples are available for contracts +:tag: contract +``` + Each `Contract` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json @@ -325,10 +328,6 @@ Each `Contract` has the following fields: :list: contract ``` -```{workedexamplelist} The following worked examples are available for contracts -:tag: contract -``` - ### Implementation Implementation information can be updated over the course of a contract. It belongs nested within the contract it relates to. @@ -347,6 +346,10 @@ The `contracts/implementation` object is defined as: ``` ```` +```{workedexamplelist} The following worked examples are available for implementations +:tag: implementation +``` + Each `contracts/implementation` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json @@ -360,10 +363,6 @@ Each `contracts/implementation` has the following fields: Information on subcontracts is not currently included in the core OCDS schema, but might be handled by [proposed extensions](conformance_and_extensions) -```{workedexamplelist} The following worked examples are available for implementations -:tag: implementation -``` - #### 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. @@ -436,6 +435,10 @@ An `Amendment` is defined as: ``` ```` +```{workedexamplelist} The following worked examples are available for amendments +:tag: amendment +``` + Each `Amendment` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json @@ -443,10 +446,6 @@ Each `Amendment` has the following fields: :collapse: changes ``` -```{workedexamplelist} The following worked examples are available for amendments -:tag: amendment -``` - #### Changes ```{deprecated} 1.1 @@ -776,6 +775,10 @@ A `Milestone` is defined as: ``` ```` +```{workedexamplelist} The following worked examples are available for milestones +:tag: milestone +``` + Each `Milestone` has the following fields: ```{jsonschema} ../../build/current_lang/release-schema.json @@ -783,10 +786,6 @@ Each `Milestone` has the following fields: :collapse: documents ``` -```{workedexamplelist} The following worked examples are available for milestones -:tag: milestone -``` - ### Value A `Value` is defined as: From e779c080fb2638b32291426ad881acafc9c98ac1 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Tue, 24 Dec 2024 08:33:10 +1300 Subject: [PATCH 13/13] docs/schema/reference.md: Link to related content using seealso admonitions --- docs/schema/reference.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 2d71d073b..a8f17ee56 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -30,7 +30,11 @@ Only including fields which have values will keep versioned datasets cleaner. ### Emptying fields and values -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](merging) for more details. +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`. + +```{seealso} +[Merging reference documentation](merging) +``` ## Language @@ -500,7 +504,11 @@ See the [parties](#parties) section. The identifier block provides a way to [identify the legal entities](identifiers.md#organization-identifiers) 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](../guidance/map/organizational_units.md). +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. + +```{seealso} +[Worked example: Organizational units](../guidance/map/organizational_units.md) +``` An `Identifier` is defined as: @@ -571,7 +579,13 @@ Each `ContactPoint` has the following fields: 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](codelists.md#document-type) 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](https://www.open-contracting.org/resources/mythbusting-confidentiality-public-contracting/) and the Center for Global Development's [Principles on Commercial Transparency in Public Contracts](https://www.cgdev.org/publication/principles-commercial-transparency-public-contracts). +Documents related to contracting (or planning) processes should be public by default. + +```{seealso} +[Mythbusting Confidentiality in Public Contracting (Open Contracting Partnership)](https://www.open-contracting.org/resources/mythbusting-confidentiality-public-contracting/) + +[Principles on Commercial Transparency in Public Contracts (Center for Global Development)](https://www.cgdev.org/publication/principles-commercial-transparency-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.