schema: Replace relatesTo codelist field with relatesToTenderer boole…

…an field. Apply style guide and make readme consistent with schema.

README.md

@@ -1,10 +1,8 @@
 # Requirements
 
-The requirements extension is based on the EU's [Core Criterion and Core Evidence Vocabulary (CCCEV)](https://joinup.ec.europa.eu/node/153001) model for communicating criteria and responses.
+Adds fields to express the [Core Criterion and Core Evidence Vocabulary (CCCEV)](https://semiceu.github.io/CCCEV/).
 
-The extension is designed to allow procuring entities or buyers to express criteria, relating to either items being procured or bidders themselves, as structured data.
-
-Criteria can be responded to either by bidders, buyers or procuring entities, for example a buyer may respond with information about an item whilst a procuring entity may respond with information on whether a bidder is disbarred.
+CCCEV is designed to support the exchange of information between buyers or procuring entities that define criteria and tenderers that respond to these criteria by means of evidences. Criteria can relate to bids, tenderers, lots or items.
 
 If your data does not closely follow the [Core Criterion and Core Evidence Vocabulary (CCCEV)](https://semiceu.github.io/CCCEV/), consider the [Selection criteria](https://extensions.open-contracting.org/en/extensions/selectionCriteria/master/) extension.
 
@@ -13,7 +11,7 @@ If your data does not closely follow the [Core Criterion and Core Evidence Vocab
 The CCCEV model defines the following concepts:
 
 **Criterion**
-A criterion represents a rule or principle used to judge, evaluate or assess either an item or bidder. A criterion is satisfied when one or more of it's requirement groups are satisfied.
+A criterion represents a rule or principle used to judge, evaluate or assess bids, tenderers, lots or items. A criterion is satisfied when one or more of its requirement groups is satisfied.
 
 **Requirement Group**
 A requirement group is a collection of one or more individual requirements. A requirement group is satisfied when all of it's requirements are satisfied.
@@ -26,18 +24,11 @@ A requirements response is an assertion that responds to a specific requirement.
 
 Therefore the CCCEV model can be used to express both **AND** conditions, where a group of requirements must be met to satisfy a criterion, and **OR** conditions, where there are alternative requirements that can satisfy a criterion.
 
-## Schema
-
-The extension introduces a new subschema for each of the concepts described above, these are added to the following locations in the OCDS schema:
-
-* `tender.criteria` - an array of criteria
-* `tender.criteria.requirementGroups` - an array of requirement groups
-* `tender.criteria.requirementGroups.requirements` - an array of requirements
-* `Bid.requirementResponses` - an array of requirement responses (depends on the [Bid statistics and details](https://extensions.open-contracting.org/en/extensions/bids/master/) extension)
+The CCCEV model also defines a number of additional concepts including **formalFrameworks**, used to specify the legal instruments from criteria are derived, **evidence**, used both to specify and provide the evidence required to support a response, and additional properties of *requirements* such as **certificationLevel**. These are not yet implemented in this extension. This extension also does not describe formulae for calculating computed values, nor does it describe whether data should be published openly or not.
 
 ## Example
 
-Below is an example of requirements specified against both an item and a bidder which demonstrates both **AND** and **OR** conditions:
+Criteria for an item and a tenderer, with **AND** and **OR** conditions:
 
 ```json
 {
@@ -47,7 +38,6 @@ Below is an example of requirements specified against both an item and a bidder
  "id": "0001",
  "title": "Air intake",
  "description": "The vacuum cleaner air intake must be at least 100W",
- "relatesTo": "item",
  "relatedItem": "item1",
  "requirementGroups": [
  {
@@ -70,7 +60,6 @@ Below is an example of requirements specified against both an item and a bidder
  "id": "0002",
  "title": "Warranty",
  "description": "The vacuum cleaner must have warranty support options for at least 36 months",
- "relatesTo": "item",
  "relatedItem": "item1",
  "requirementGroups": [
  {
@@ -113,17 +102,17 @@ Below is an example of requirements specified against both an item and a bidder
  {
  "id": "0003",
  "title": "Years trading",
- "description": "Number of years the bidder has been trading",
- "relatesTo": "tenderer",
+ "description": "Number of years the tenderer has been trading",
+ "relatesToTenderer": true,
  "requirementGroups": [
  {
  "id": "0003-001",
- "description": "Number of years the bidder has been trading",
+ "description": "Number of years the tenderer has been trading",
  "requirements": [
  {
  "id": "0003-001-01",
  "title": "Years trading",
- "description": "Number of years the bidder has been trading",
+ "description": "Number of years the tenderer has been trading",
  "dataType": "integer",
  "pattern": "[0-9]*",
  "minValue": 3
@@ -137,7 +126,7 @@ Below is an example of requirements specified against both an item and a bidder
 }
 ```
 
-Below is an example of responses which meet the above requirements:
+Responses to the criteria:
 
 ```json
 {
@@ -174,12 +163,6 @@ Below is an example of responses which meet the above requirements:
 }
 ```
 
-## Further extensions
-
-The CCCEV model also defines a number of additional concepts including **formalFrameworks**, used to specify the legal instruments from criteria are derived, **evidence**, used both to specify and provide the evidence required to support a requirement response, and additional properties of *requirements* such as **certificationLevel** which are not currently implemented in this extension.
-
-This extension does not describe formulae for calculating computed values, nor does it describe whether data should be published openly or not.
-
 ## Issues
 
 Report issues for this extension in the [ocds-extensions repository](https://github.com/open-contracting/ocds-extensions/issues), putting the extension's name in the issue's title.
@@ -193,6 +176,8 @@ Report issues for this extension in the [ocds-extensions repository](https://git
  * `Contract.requirementResponses`
  * `Criterion.source`
  * `RequirementResponse.relatedTenderer`
+* Replace `Criterion.relatesTo` codelist field with `Criterion.relatesToTenderer` boolean field.
+* Remove `relatesTo.csv` codelist.
 * Remove `responseSource.csv` codelist.
 
 ### 2023-04-18

codelists/dataType.csv

@@ -1,6 +1,6 @@
 Code,Title,Description
-string,String,The requirement response must be of type string
-date-time,Date-time,The requirement response must be of type date-time (ISO8601)
-number,Number,"The requirement response must be of type number, i.e. a floating point or whole number"
-integer,Integer,The requirement response must be of type integer
-boolean,Boolean,The requirement response must be of type boolean
+string,String,The response must be of type string
+date-time,Date-time,The response must be of type date-time (ISO8601)
+number,Number,"The response must be of type number, i.e. a floating point or whole number"
+integer,Integer,The response must be of type integer
+boolean,Boolean,The response must be of type boolean

extension.json

@@ -3,7 +3,7 @@
  "en": "Requirements"
  },
  "description": {
- "en": "Adds a criteria section to the tender object and responses sections to bids, awards and contracts. Based on the EU's Core Criterion and Core Evidence Vocabulary (CCCEV)."
+ "en": "Adds fields to express the Core Criterion and Core Evidence Vocabulary (CCCEV)."
  },
  "documentationUrl": {
  "en": "https://extensions.open-contracting.org/en/extensions/requirements/"
@@ -12,8 +12,7 @@
  "1.1"
  ],
  "codelists": [
- "dataType.csv",
- "relatesTo.csv"
+ "dataType.csv"
  ],
  "schemas": [
  "release-schema.json"

release-schema.json

@@ -3,7 +3,7 @@
  "Criterion": {
  "type": "object",
  "title": "Criterion",
- "description": "A criterion on which either bidders or items will be judged, evaluated or assessed.",
+ "description": "A criterion on which bids, tenderers, lots or items will be judged, evaluated or assessed.",
  "required": [
  "id"
  ],
@@ -35,24 +35,17 @@
  ],
  "minLength": 1
  },
- "relatesTo": {
- "title": "Related schema element",
- "description": "The schema element that the criterion judges, evaluates or assesses. For example, the criterion might be defined against items or against bidders.",
+ "relatesToTenderer": {
+ "title": "Relates to tenderer",
+ "description": "The criterion judges, evaluates or assesses a tenderer.",
  "type": [
- "string",
+ "boolean",
  "null"
- ],
- "codelist": "relatesTo.csv",
- "openCodelist": false,
- "enum": [
- "tenderer",
- "item",
- null
  ]
  },
  "relatedItem": {
  "title": "Related item",
- "description": "Where relatesTo = \"item\" this field must be populated with the id of the item in this tender section which the criterion relates to. Where relatesTo <> \"item\" this field should be omitted.",
+ "description": "The identifier of the item in the tender section to which this criterion applies.",
  "type": [
  "string",
  "null"
@@ -156,7 +149,7 @@
  },
  "dataType": {
  "title": "Requirement datatype",
- "description": "The data type in which the requirement response must be provided.",
+ "description": "The data type in which the response must be provided.",
  "type": [
  "string",
  "null"
@@ -174,7 +167,7 @@
  },
  "pattern": {
  "title": "Response validation pattern",
- "description": "A regular expression against which validate the requirement response.",
+ "description": "A regular expression with which to validate the response.",
  "type": [
  "string",
  "null"
@@ -183,7 +176,7 @@
  },
  "expectedValue": {
  "title": "Expected value",
- "description": "Used to state the requirement when the response must be particular value.",
+ "description": "The expected value of the requirement, when the response must be specific value.",
  "type": [
  "string",
  "integer",
@@ -195,7 +188,7 @@
  },
  "minValue": {
  "title": "Minimum value",
- "description": "Used to state the lower bound of the requirement when the response must be within a certain range.",
+ "description": "The lower bound of the requirement, when the response must be within a certain range.",
  "type": [
  "integer",
  "number",
@@ -204,7 +197,7 @@
  },
  "maxValue": {
  "title": "Maximum value",
- "description": "Used to state the upper bound of the requirement when the response must be within a certain range.",
+ "description": "The upper bound of the requirement, when the response must be within a certain range.",
  "type": [
  "integer",
  "number",
@@ -213,30 +206,30 @@
  },
  "period": {
  "title": "Period",
- "description": "Used to specify a particular period the requirement applies to, for example the bidder's turnover in a given year.",
+ "description": "The period to which the requirement applies: for example, the tenderer's turnover in a given year.",
  "$ref": "#/definitions/Period"
  }
  },
  "minProperties": 1
  },
  "RequirementResponse": {
  "type": "object",
- "title": "Requirement Response",
- "description": "An assertion that responds to a single requirement. A requirement response provides the value for the requirement and may provide the period to which it applies.",
+ "title": "Requirement response",
+ "description": "An assertion that responds to a single requirement. A response provides the value for the requirement and may provide the period to which it applies.",
  "required": [
  "id",
  "requirement"
  ],
  "properties": {
  "id": {
  "title": "Identifier",
- "description": "The identifier for this requirement response. It must be unique and cannot change within the Open Contracting Process it is part of (defined by a single ocid). See the [identifier guidance](http://standard.open-contracting.org/latest/en/schema/identifiers/) for further details.",
+ "description": "The unique identifier of this response in the context of the contracting process.",
  "type": "string",
  "minLength": 1
  },
  "title": {
  "title": "Title",
- "description": "A title for this requirement response.",
+ "description": "The title of this response.",
  "type": [
  "string",
  "null"
@@ -245,7 +238,7 @@
  },
  "description": {
  "title": "Description",
- "description": "A description of this requirement response.",
+ "description": "The description of this response.",
  "type": [
  "string",
  "null"
@@ -254,7 +247,7 @@
  },
  "value": {
  "title": "Value",
- "description": "The value of this requirement response. The value must be of the type defined in the requirement.dataType field.",
+ "description": "The value of this response.",
  "type": [
  "string",
  "integer",
@@ -266,12 +259,12 @@
  },
  "period": {
  "title": "Period",
- "description": "The period which the requirement response is applicable to.",
+ "description": "The period to which the response applies.",
  "$ref": "#/definitions/Period"
  },
  "requirement": {
  "title": "Related requirement",
- "description": "The id and title of the requirement which the response is applicable to.",
+ "description": "A reference to the requirement to which the response applies.",
  "$ref": "#/definitions/RequirementReference"
  }
  },
@@ -280,20 +273,20 @@
  "RequirementReference": {
  "type": "object",
  "title": "Requirement reference",
- "description": "Used to cross reference a requirement.",
+ "description": "A reference to a requirement.",
  "required": [
  "id"
  ],
  "properties": {
  "id": {
  "title": "Requirement ID",
- "description": "The id of the requirement which the response is applicable to.",
+ "description": "The identifier of the requirement to which the response applies.",
  "type": "string",
  "minLength": 1
  },
  "title": {
  "title": "Requirement title",
- "description": "The title of the requirement which the response is applicable to.",
+ "description": "The title of the requirement to which the response applies.",
  "type": [
  "string",
  "null"
@@ -307,7 +300,7 @@
  "properties": {
  "requirementResponses": {
  "title": "Requirement responses",
- "description": "If the requirements extension is also in use, the detailed responses of this bid to the tender requirements can be specified here.",
+ "description": "The responses of this bid to the requirements.",
  "type": "array",
  "items": {
  "$ref": "#/definitions/RequirementResponse"
@@ -321,7 +314,7 @@
  "properties": {
  "criteria": {
  "title": "Criteria",
- "description": "A list of criteria on which either bidders or items will be judged, evaluated or assessed.",
+ "description": "Criteria on which bids, tenderers, lots or items will be judged, evaluated or assessed.",
  "type": "array",
  "items": {
  "$ref": "#/definitions/Criterion"