release-schema(style): Improve alignment with style guide, closes #1610

- Do not declare the type of the field in its description.
- Do not refer to other fields or extensions in a field's description.
  - Move relevant content to the other fields' descriptions.
  - Extensions are already linked in reference.md.

docs/history/changelog.md

@@ -208,6 +208,7 @@ Per the [normative and non-normative content and changes policy](https://docs.go
  * [#1335](https://github.com/open-contracting/standard/pull/1335) Standardize the descriptions of `planning`, `planning.rationale`, `planning.budget`, `planning.documents`, and `planning.milestones`.
  * [#1530](https://github.com/open-contracting/standard/pull/1530) `Buyer`, `tender.items`, `awards.items`, `contracts.items`, `Item`, `Item.description`, `Item.unit`, `Unit`, `transaction.providerOrganization`, `transaction.receiverOrganization` to use consistent wording for "goods, services and/or works".
  * [#1528](https://github.com/open-contracting/standard/pull/1528) `tender.id`, `tender.hasEnquiries`, to reduce ambiguity and use consistent wording in the description of procurement stages.
+ * [#1618](https://github.com/open-contracting/standard/pull/1618) Normalize field descriptions according to a style guide.
 
 * Remove confusing terminology:
  * [#1487](https://github.com/open-contracting/standard/pull/1487) `planning.budget.project`, to remove sentence about translation options.

schema/release-schema.json

@@ -173,7 +173,7 @@
  },
  "milestones": {
  "title": "Planning milestones",
- "description": "A list of milestones associated with the planning process.",
+ "description": "Milestones associated with the planning process.",
  "type": "array",
  "items": {
  "$ref": "#/definitions/Milestone"
@@ -226,7 +226,7 @@
  },
  "description": {
  "title": "Tender description",
- "description": "A summary description of the tender. This complements any structured information provided using the items array. Descriptions should be short and easy to read. Avoid using ALL CAPS.",
+ "description": "A summary description of the tender. Descriptions should be short and easy to read. Avoid using ALL CAPS.",
  "type": [
  "string",
  "null"
@@ -388,7 +388,7 @@
  },
  "submissionMethodDetails": {
  "title": "Submission method details",
- "description": "Information about the methods by which bids are submitted. This can include the address, e-mail address or online service to which bids are submitted, and any special requirements to be followed for submissions. More structured information can be provided using the submission terms extension.",
+ "description": "Information about how to submit bids. This can include the address, e-mail address or online service to which bids are submitted, and any special requirements to be followed for submissions. This can also include information about how to submit enquiries.",
  "type": [
  "string",
  "null"
@@ -410,12 +410,12 @@
  },
  "enquiryPeriod": {
  "title": "Enquiry period",
- "description": "The period during which potential bidders may submit questions and requests for clarification to the buyer or the procuring entity. Details of how to submit enquiries should be provided in attached notices, or in submissionMethodDetails. Structured dates for when responses to questions will be made can be provided using tender milestones.",
+ "description": "The period during which potential bidders may submit questions and requests for clarification to the buyer or the procuring entity.",
  "$ref": "#/definitions/Period"
  },
  "hasEnquiries": {
  "title": "Has enquiries?",
- "description": "A true/false field to indicate whether any enquiries were received during the tender stage. Structured information on enquiries that were received, and responses to them, can be provided using the enquiries extension.",
+ "description": "Whether any enquiries were received.",
  "type": [
  "boolean",
  "null"
@@ -443,7 +443,7 @@
  },
  "selectionCriteria": {
  "title": "Selection criteria",
- "description": "The minimum requirements for potential suppliers to participate in the contracting process. Selection criteria ensure that a potential supplier has the legal and financial capacities and the technical and professional abilities to perform the contract. More structured information can be provided using the selection criteria extension.",
+ "description": "The minimum requirements for potential suppliers to participate in the contracting process. Selection criteria ensure that a potential supplier has the legal and financial capacities and the technical and professional abilities to perform the contract.",
  "type": [
  "string",
  "null"
@@ -474,7 +474,7 @@
  },
  "tenderers": {
  "title": "Tenderers",
- "description": "All organizations that submit a bid. More detailed information on bids and the bidding organization can be provided using the bid extension.",
+ "description": "All organizations that submit a bid.",
  "type": "array",
  "items": {
  "$ref": "#/definitions/OrganizationReference"
@@ -491,7 +491,7 @@
  },
  "milestones": {
  "title": "Milestones",
- "description": "A list of milestones associated with the tender.",
+ "description": "Milestones associated with the tender: for example, the date on which responses to enquiries are published.",
  "type": "array",
  "items": {
  "$ref": "#/definitions/Milestone"
@@ -861,7 +861,7 @@
  },
  "milestones": {
  "title": "Contract milestones",
- "description": "A list of milestones associated with the finalization of this contract.",
+ "description": "Milestones associated with the finalization of this contract.",
  "type": "array",
  "items": {
  "$ref": "#/definitions/Milestone"
@@ -907,7 +907,7 @@
  "properties": {
  "transactions": {
  "title": "Transactions",
- "description": "A list of the spending transactions made against this contract",
+ "description": "The spending transactions made against this contract.",
  "type": "array",
  "items": {
  "$ref": "#/definitions/Transaction"
@@ -1232,7 +1232,7 @@
  },
  "amount": {
  "title": "Amount",
- "description": "The value reserved for the future contract(s), within the budget. A negative value indicates income to the budget as a result of the future contract(s), rather than expenditure. If the budget is drawn from multiple sources or extends over multiple years, the budget breakdown extension can be used. This field should not be used to report the total value of the budget line that will fund the future contract(s).",
+ "description": "The value reserved for the future contract(s), within the budget. A negative value indicates income to the budget as a result of the future contract(s), rather than expenditure. This field should not be used to report the total value of the budget line that will fund the future contract(s).",
  "$ref": "#/definitions/Value"
  },
  "project": {
@@ -1510,7 +1510,7 @@
  "object",
  "null"
  ],
- "description": "Additional classification information about organizations can be provided using organization details extensions that define particular fields and classification schemes.",
+ "description": "Additional information about the organization.",
  "title": "Details",
  "properties": {
  "scale": {
@@ -1576,7 +1576,7 @@
  },
  "additionalClassifications": {
  "title": "Additional classifications",
- "description": "An array of additional classifications for the item.",
+ "description": "Additional classifications for the item.",
  "type": "array",
  "items": {
  "$ref": "#/definitions/Classification"