Expand Budget descriptions

[duncandewhurst]

The budget and projects extension previously included updates to descriptions of fields in the budget section of the core OCDS standard (see open-contracting/ocds-extensions#46).

The updated descriptions are copied below so they can be considered for inclusion in future updates to OCDS core:

Field/Object	Updated description
budget	This section contains basic information about the budget estimated for, or allocated to, this contracting process at the present time. Further documentation and data about how budgets have been allocated to a contracting process should be published outside of OCDS data, according to the best available standards.
budget/id	An identifier for the budget line item which provides funds for this contracting process. This identifier should be possible to cross-reference against formal budget documents.
budget/description	A short free-text description of the budget allocation for this contracting process. This may be used to provide human-readable information on the budget category allocated to this contracting process, and/or, information about the nature and source of the allocation (e.g. conditional, confirmed; any official authorizations given to the budget allocation).
budget/amount	The total value of budget allocations for this contracting process. The budget breakdown extension can be used to provide data for multiple budget sources, or to split the budget by years or other periods.
budget/project	The name of the project that through which this contracting process is funded. Detailed information should be provided in the planning.project object.
budget/projectID	An external identifier for the project that this contracting process forms part of. Required for legacy compatibility with OCDS core.
budget/uri	A URI pointing directly to records about the related budget for this contracting process. Where possible this URI should return machine and human-readable representations of the data.

[jpmckinney]

Do we consider all the above to be improvements over what's in core?

[duncandewhurst]

Per my notes in open-contracting-extensions/ocds_project_extension#12 (comment) I think for budget and budget/description these are improvements over the current definitions.

For budget/amount I think the current definition is better since it describes the use of negative values, though we could add the point on using budgetBreakdown for multi-year budgets to core (the current description only mentions multi-source)

For budget/project I think this definition is wrong (projectDetail doesn't exist) so the current definition is preferred.

For budget/projectID this definition doesn't make sense for core the current definition is preferred.

For budget/uri this definition introduces the idea that the uri should return machine- and human-readable records (the current definition only mentions machine-readable and points to the planning.documents block for human readable documents). We could consider adding that recommendation to core, which raises a wider question about whether we should make similar recommendations across all uris in the schema (see #706)

Noting that definitions for all of the above fields may be considered for change based on the ongoing discussions about modelling and linking budget and project data in OCDS.

[duncandewhurst]

Noting also that the updated description for budget/id replaces the reference to "provided data source" with "formal budget documents", in line with the deprecation of budget/source in OCDS 1.1

[jpmckinney]

In the extension, budget/amount also had:

Or, the value estimated for, or allocated to, this contracting process in a budget. This field should not be used to report the total value of the budget line funding this contracting process.

[ColinMaudry]

If I summarize well, here are the changes to be made to the core descriptions in 1.2:

✔️ Budget: This section contains basic information about the budget estimated for, or allocated to, this contracting process at the present time. Further documentation and data about how budgets have been allocated to a contracting process should be published outside of OCDS data, according to the best available standards.

✔️ budget/description: A short free-text description of the budget allocation for this contracting process. This may be used to provide human-readable information on the budget category allocated to this contracting process, and/or, information about the nature and source of the allocation (e.g. conditional, confirmed; any official authorizations given to the budget allocation).

❓ budget/uri: My understanding of the conclusions of #706 is that we keep the current description

❓ budget/amount: we can improve the current description by mentioning multi-years budgets.

I think the following bit would make it complex (I don't really get it 😛):

Or, the value estimated for, or allocated to, this contracting process in a budget

I think this warning would be a good addition:

This field should not be used to report the total value of the budget line funding this contracting process.

[ColinMaudry]

Or, the value estimated for, or allocated to, this contracting process in a budget

I think it repeats what the first sentence of the current description of Budget.amount says:

The value reserved in the budget for this contracting process.

[jpmckinney]

@ColinMaudry Yes, I think we can go ahead with the changes to Budget, budget/description and also budget/id, and we can add the warning you quoted to budget/amount.

[ColinMaudry]

Closed by #1167