From dd97d4bcbd433fc16efcbcb9d246f1c986614498 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 27 Jun 2024 23:39:57 -0400 Subject: [PATCH] Review merger of Project and Location extensions - Merge reference.md content into schema. - Copy-edit Project and Location subschema. - Copy-edit Location codelists. Remove normative word imported from RFC 7946. - Use classification scheme example that conforms to guidance. - Use "datasets" not "data sets" per style guide. --- .../release_package.json | 2 +- docs/guidance/map/linked_standards.md | 2 +- docs/history/changelog.md | 6 ++- docs/schema/reference.md | 10 +---- schema/codelists/geometryType.csv | 12 +++--- schema/codelists/locationGazetteer.csv | 7 ++++ schema/codelists/locationGazetteers.csv | 7 ---- schema/release-schema.json | 40 +++++++++---------- 8 files changed, 40 insertions(+), 46 deletions(-) create mode 100644 schema/codelists/locationGazetteer.csv delete mode 100644 schema/codelists/locationGazetteers.csv diff --git a/docs/examples/release_schema_reference/release_package.json b/docs/examples/release_schema_reference/release_package.json index aa6c4427c..2d401a453 100644 --- a/docs/examples/release_schema_reference/release_package.json +++ b/docs/examples/release_schema_reference/release_package.json @@ -112,7 +112,7 @@ { "id": "03.04.05", "description": "Cycle lanes for road transport.", - "scheme": "My local scheme" + "scheme": "GB-EXAMPLE" } ], "locations": [ diff --git a/docs/guidance/map/linked_standards.md b/docs/guidance/map/linked_standards.md index afc5fe78c..0d64d6d19 100644 --- a/docs/guidance/map/linked_standards.md +++ b/docs/guidance/map/linked_standards.md @@ -8,7 +8,7 @@ The [Open Contracting for Infrastructure Data Standards](https://standard.open-c A joint effort by the [Infrastructure Transparency Initiative](https://infrastructuretransparency.org) (CoST) and the Open Contracting Partnership, it builds on best practice in open data and openness of public infrastructure procurement globally. -OCDS and OC4IDS data sets ought to be linked using the `planning.project` field, referencing the OC4IDS project identifier in `planning.project.id`. +OCDS and OC4IDS datasets ought to be linked using the `planning.project` object, by referencing the OC4IDS project identifier in the `planning.project.id` field. ## Open Fiscal Data Package diff --git a/docs/history/changelog.md b/docs/history/changelog.md index c921d1fbf..2cfb2aa75 100644 --- a/docs/history/changelog.md +++ b/docs/history/changelog.md @@ -75,7 +75,7 @@ Per the [normative and non-normative content and changes policy](../governance/n * [#1684](https://github.com/open-contracting/standard/pull/1684) `geometryType` * [#1316](https://github.com/open-contracting/standard/pull/1316) `language` * [#1326](https://github.com/open-contracting/standard/pull/1326) `linkRelationType` - * [#1684](https://github.com/open-contracting/standard/pull/1684) `locationGazetteers` + * [#1684](https://github.com/open-contracting/standard/pull/1684) `locationGazetteer` * [#1308](https://github.com/open-contracting/standard/pull/1308) `mediaType` * [#1459](https://github.com/open-contracting/standard/pull/1459) `partyScale` * [#1654](https://github.com/open-contracting/standard/pull/1654) `permission` @@ -200,7 +200,9 @@ Per the [normative and non-normative content and changes policy](../governance/n * Add new fields: * [#1335](https://github.com/open-contracting/standard/pull/1335) `planning.id` * [#1642](https://github.com/open-contracting/standard/pull/1642) `planning.finalStatus`, `planning.finalStatusDetails` and `planning.finalStatusDate` + * [#1684](https://github.com/open-contracting/standard/pull/1684) `planning.project` * [#1324](https://github.com/open-contracting/standard/pull/1324) `tender.datePublished` + * [#1684](https://github.com/open-contracting/standard/pull/1684) `tender.deliveryLocations` and `tender.deliveryAddresses` * [#1296](https://github.com/open-contracting/standard/pull/1296) [#1674](https://github.com/open-contracting/standard/pull/1674) `tender.exclusionGrounds` * [#1669](https://github.com/open-contracting/standard/pull/1669) `tender.expressionOfInterestDeadline` * [#1490](https://github.com/open-contracting/standard/pull/1490) `tender.identifiers` @@ -221,13 +223,13 @@ Per the [normative and non-normative content and changes policy](../governance/n * [#1372](https://github.com/open-contracting/standard/pull/1372) `Address.country` * [#1380](https://github.com/open-contracting/standard/pull/1380) [#1440](https://github.com/open-contracting/standard/pull/1440) `Document.languages` * [#1439](https://github.com/open-contracting/standard/pull/1439) `Document.relatedItems` + * [#1684](https://github.com/open-contracting/standard/pull/1684) `Item.deliveryLocations` and `Item.deliveryAddresses` * [#1455](https://github.com/open-contracting/standard/pull/1455) `Milestone.dueAfterDate` * [#1434](https://github.com/open-contracting/standard/pull/1434) `Milestone.value` * [#1490](https://github.com/open-contracting/standard/pull/1490) `SimpleIdentifier` * [#1519](https://github.com/open-contracting/standard/pull/1519) `Value.amountNet` and `Value.amountGross` * [#1490](https://github.com/open-contracting/standard/pull/1490) `contracts.identifiers` * [#1679](https://github.com/open-contracting/standard/pull/1679) `Organization.details.classifications` - * [#1684](https://github.com/open-contracting/standard/pull/1684) `planning.project`, `deliveryLocations` and `deliveryAddresses` to `Tender` and `Item` * Deprecate some fields: * [#1200](https://github.com/open-contracting/standard/pull/1200) `tender.submissionMethod`, because all codes from the `submissionMethod` codelist are deprecated. diff --git a/docs/schema/reference.md b/docs/schema/reference.md index 15bac851f..df3da00e2 100644 --- a/docs/schema/reference.md +++ b/docs/schema/reference.md @@ -122,7 +122,7 @@ 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, the parent project and market research. Background documents such as feasibility studies and project plans can also be included in this section. +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. ````{admonition} Example :class: hint @@ -150,8 +150,6 @@ The planning section is used in a planning process. This includes information ab 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. -The `planning.budget.projectID` field should not be used to disclose the identifier of an infrastructure or PPP project. Rather, this field is used to disclose the identifier of a programme of work as it appears in a budget, like a national or state budget. Since such programmes of work can include many infrastructure projects, it is necessary to disclose their identifiers separately. Use the the `planning.project.id` field to disclose the identifier of an infrastructure or PPP project. - ````{admonition} Example :class: hint @@ -172,10 +170,6 @@ The `planning.budget.projectID` field should not be used to disclose the identif #### Project -The `project` object includes details of the infrastructure or public-private partnership (PPP) project to which a planning process is related. This object is designed to allow both machine-readable linkable data about the parent project, cross-referencing to data held in other standards such as the [Open Contracting for Infrastructure Data Standards Toolkit (OC4IDS)](https://standard.open-contracting.org/infrastructure/latest/en/projects/#what-is-a-project) and the [OCDS for PPPs](https://standard.open-contracting.org/profiles/ppp/latest/en/) profile, and human readable description of the parent project, supporting users to understand the relationship of the contracting (or planning) process to their parent project even where linked data is not available. - -Where there is a separate OC4IDS dataset that describes the project the identifier from this dataset should be referenced in `project.id`. Where there is not a separate project dataset an appropriate project identifier will need to be generated. For more information on project identifiers see [OC4IDS Project Identifiers](https://standard.open-contracting.org/infrastructure/latest/en/guidance/identifiers/). - ````{admonition} Example :class: hint @@ -697,8 +691,6 @@ As well as providing this machine-readable link between processes, publishers ma ### Location -The `Location` subschema can be used to provide the geographic coordinates or standardized location identifiers of the proposed or executed contract delivery in the `Project`, `tender` and `Item` objects. - ````{admonition} Example :class: hint diff --git a/schema/codelists/geometryType.csv b/schema/codelists/geometryType.csv index f053feb6a..204a8ee85 100644 --- a/schema/codelists/geometryType.csv +++ b/schema/codelists/geometryType.csv @@ -1,7 +1,7 @@ Code,Title,Description,Source -Point,Point,"For type 'Point', the 'coordinates' member is a single position.",https://tools.ietf.org/html/rfc7946#section-3.1 -MultiPoint,MultiPoint,"For type 'MultiPoint', the 'coordinates' member is an array of positions.",https://tools.ietf.org/html/rfc7946#section-3.1 -LineString,LineString,"For type 'LineString', the 'coordinates' member is an array of two or more positions.",https://tools.ietf.org/html/rfc7946#section-3.1 -MultiLineString,MultiLineString,"For type 'MultiLineString', the 'coordinates' member is an array of LineString coordinate arrays.",https://tools.ietf.org/html/rfc7946#section-3.1 -Polygon,Polygon,"For type 'Polygon', the 'coordinates' member must be an array of linear ring coordinate arrays.",https://tools.ietf.org/html/rfc7946#section-3.1 -MultiPolygon,MultiPolygon,"For type 'MultiPolygon', the 'coordinates' member is an array of Polygon coordinate arrays.",https://tools.ietf.org/html/rfc7946#section-3.1 +Point,Point,"For type 'Point', the `coordinates` field is a single position.",https://tools.ietf.org/html/rfc7946#section-3.1 +MultiPoint,MultiPoint,"For type 'MultiPoint', the `coordinates` field is an array of positions.",https://tools.ietf.org/html/rfc7946#section-3.1 +LineString,LineString,"For type 'LineString', the `coordinates` field is an array of two or more positions.",https://tools.ietf.org/html/rfc7946#section-3.1 +MultiLineString,MultiLineString,"For type 'MultiLineString', the `coordinates` field is an array of LineString coordinate arrays.",https://tools.ietf.org/html/rfc7946#section-3.1 +Polygon,Polygon,"For type 'Polygon', the `coordinates` field is an array of linear ring coordinate arrays.",https://tools.ietf.org/html/rfc7946#section-3.1 +MultiPolygon,MultiPolygon,"For type 'MultiPolygon', the `coordinates` field is an array of Polygon coordinate arrays.",https://tools.ietf.org/html/rfc7946#section-3.1 diff --git a/schema/codelists/locationGazetteer.csv b/schema/codelists/locationGazetteer.csv new file mode 100644 index 000000000..fbcc3869c --- /dev/null +++ b/schema/codelists/locationGazetteer.csv @@ -0,0 +1,7 @@ +Category,Code,Title,Description,Source,URI Pattern +Sub-National,NUTS,EU Nomenclature of Territorial Units for Statistics,The Nomenclature of Territorial Units for Statistics (NUTS) was established by Eurostat in order to provide a single uniform breakdown of territorial units for the production of regional statistics for the European Union.,https://ec.europa.eu/eurostat/web/nuts/linked-open-data,http://data.europa.eu/nuts/code/ +National,ISO2,ISO 3166-1 alpha-2,ISO 3166-1 alpha-2 assigns two-letter codes to countries.,https://www.iso.org/iso-3166-country-codes.html, +Universal,GEONAMES,GeoNames,GeoNames assigns numerical identifiers to geographical names.,https://www.geonames.org/,https://www.geonames.org/ +Universal,OSMN,OpenStreetMap node,An OpenStreetMap node defines a point in space.,,https://www.openstreetmap.org/node/ +Universal,OSMW,OpenStreetMap way,"An OpenStreetMap way defines linear features and area boundaries, as an ordered list of nodes.",https://wiki.openstreetmap.org/wiki/Way,https://www.openstreetmap.org/way/ +Universal,OSMR,OpenStreetMap relation,"An OpenStreetMap relation combines nodes, ways, and/or other relations.",https://wiki.openstreetmap.org/wiki/Relation,https://www.openstreetmap.org/relation/ diff --git a/schema/codelists/locationGazetteers.csv b/schema/codelists/locationGazetteers.csv deleted file mode 100644 index fa5e62d4b..000000000 --- a/schema/codelists/locationGazetteers.csv +++ /dev/null @@ -1,7 +0,0 @@ -Category,Code,Title,Description,Source,URI Pattern -Sub-National,NUTS,EU Nomenclature of Territorial Units for Statistics,The Nomenclature of Territorial Units for Statistics (NUTS) was established by Eurostat in order to provide a single uniform breakdown of territorial units for the production of regional statistics for the European Union.,https://ec.europa.eu/eurostat/web/nuts/linked-open-data,http://data.europa.eu/nuts/code/ -National,ISO2,ISO Country Codes (3166-1 alpha-2),ISO 2-Digit Country Codes,https://www.iso.org/iso-3166-country-codes.html, -Universal,GEONAMES,GeoNames,"GeoNames provides numerical identifiers for many points of interest around the world, including administrative divisions, populated centres and other locations, embedded within a structured tree of geographic relations.",https://www.geonames.org/,https://www.geonames.org/ -Universal,OSMN,OpenStreetMap Node,"OpenStreetMap Nodes consist of a single point in space defined by a latitude, longitude and node ID. Nodes might have tags to indicate the particular geographic feature they represent.",,https://www.openstreetmap.org/node/ -Universal,OSMR,OpenStreetMap Relation,"Relations are used to model logical (and usually local) or geographic relationships between objects. In practice, boundaries of geographic areas are available as Relations in OpenStreetMap.",https://wiki.openstreetmap.org/wiki/Relation,https://www.openstreetmap.org/relation/ -Universal,OSMW,OpenStreetMap Way,An OpenStreetMap Way is an ordered list of OpenStreetMap nodes. It can be used to describe fragments of roads or local boundaries and bounding boxes.,https://wiki.openstreetmap.org/wiki/Way,https://www.openstreetmap.org/way/ diff --git a/schema/release-schema.json b/schema/release-schema.json index 702c8bbe1..b3b2dd6e0 100644 --- a/schema/release-schema.json +++ b/schema/release-schema.json @@ -164,7 +164,7 @@ "$ref": "#/definitions/Budget" }, "project": { - "title": "Project information", + "title": "Project", "description": "Information about the infrastructure or public-private partnership project to which the planning process is related.", "$ref": "#/definitions/Project" }, @@ -348,7 +348,7 @@ "$ref": "#/definitions/Value" }, "deliveryLocations": { - "title": "Delivery Locations", + "title": "Delivery locations", "description": "The locations where activity related to the opportunity will take place.", "type": "array", "items": { @@ -358,8 +358,8 @@ "uniqueItems": true }, "deliveryAddresses": { - "title": "Delivery Addresses", - "description": "The addresses to which, or where, goods or services related to the opportunity will be delivered.", + "title": "Delivery addresses", + "description": "The addresses to which goods or services related to the opportunity will be delivered.", "type": "array", "items": { "$ref": "#/definitions/Address" @@ -1292,7 +1292,7 @@ }, "projectID": { "title": "Project identifier", - "description": "The identifier of the project of which the future contract(s) will be part or through which it/they will be funded. Some organizations maintain a registry of projects, and the data should use the identifier from the relevant registry of projects. Although an integer is allowed, it is recommended to use a string.", + "description": "The identifier of the programme of work in a budget, of which the future contract(s) will be part or through which it/they will be funded. Although an integer is allowed, it is recommended to use a string.", "type": [ "string", "integer", @@ -1632,7 +1632,7 @@ "$ref": "#/definitions/Unit" }, "deliveryLocations": { - "title": "Delivery Locations", + "title": "Delivery locations", "description": "The locations where activity related to the opportunity, contract or license will be delivered.", "type": "array", "items": { @@ -1643,8 +1643,8 @@ "minItems": 1 }, "deliveryAddresses": { - "title": "Delivery Addresses", - "description": "The addresses to which, or where, goods or services related to the opportunity, contract or license will be delivered.", + "title": "Delivery addresses", + "description": "The addresses to which goods or services related to the opportunity, contract or license will be delivered.", "type": "array", "items": { "$ref": "#/definitions/Address" @@ -1833,7 +1833,7 @@ "properties": { "description": { "title": "Description", - "description": "A name or description of the location. This might include the name(s) of the location(s), or might provide a human-readable description of the location to be covered.", + "description": "The name or description of the location.", "type": [ "string", "null" @@ -1841,12 +1841,12 @@ }, "geometry": { "title": "Geometry", - "description": "We follow the [GeoJSON standard](https://www.rfc-editor.org/rfc/rfc7946) to express basic location information, using longitude, latitude, and optional elevation values in the [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System) (EPSG:4326) projection. A point location can be identified by geocoding an address. For concession licenses, or other scenarios covering a polygon location that is not contained in a known gazetteer, polygon and multi-polygon can be used.", + "description": "The spatial extent of the location, as a [GeoJSON Geometry object](https://www.rfc-editor.org/rfc/rfc7946).", "type": "object", "properties": { "type": { "title": "Type", - "description": "The type of [GeoJSON Geometry Objects](https://www.rfc-editor.org/rfc/rfc7946#section-3.1) being provided. To provide longitude, latitude, and optional elevation, use 'Point', and enter an array of [longitude, latitude] or [longitude, latitude, elevation] as the value of the coordinates field: e.g. [-122.085, 37.42].", + "description": "The type of the GeoJSON Geometry object, from the closed [geometryType](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#geometryType) codelist.", "type": [ "string", "null" @@ -1865,7 +1865,7 @@ }, "coordinates": { "title": "Coordinates", - "description": "The relevant array of points, e.g. [longitude, latitude] or [longitude, latitude, elevation], or a nested array of points, for the GeoJSON geometry being described. The longitude and latitude must be expressed in decimal degrees in the WGS84 (EPSG:4326) projection.", + "description": "The coordinates of the GeoJSON Geometry object. For example, [longitude, latitude] or [longitude, latitude, elevation] for a Point geometry, using the World Geodetic System 1984 (WGS84, EPSG:4326) with longitude and latitude units of decimal degrees.", "type": [ "array", "null" @@ -1881,22 +1881,22 @@ }, "gazetteer": { "title": "Gazetteer", - "description": "Identifiers from a gazetteer (a geographical index or directory) for the location.", + "description": "Identifiers for the location from a gazetteer (a geographical index or directory).", "type": "object", "properties": { "scheme": { - "title": "Gazetteer scheme", - "description": "The identifier of the gazetteer. The `locationGazetteers.csv` codelist provides details of services, where available, that can resolve a gazetteer entry to provide location names.", + "title": "Scheme", + "description": "The identifier of the gazetteer, from the open [locationGazetter](https://standard.open-contracting.org/{{version}}/{{lang}}/schema/codelists/#locationGazetter) codelist.", "type": [ "string", "null" ], - "codelist": "locationGazetteers.csv", + "codelist": "locationGazetteer.csv", "openCodelist": true }, "identifiers": { "title": "Identifiers", - "description": "An array of one or more codes drawn from the gazetteer indicated by the `scheme` field.", + "description": "One or more location codes taken from the scheme.", "type": [ "array", "null" @@ -1909,7 +1909,7 @@ }, "uri": { "title": "URI", - "description": "A URI to a further description of the location. This might be a human-readable document with information on the location, or a machine-readable description of the location.", + "description": "A URI for the location.", "type": [ "string", "null" @@ -2886,12 +2886,12 @@ }, "Project": { "title": "Project information", - "description": "Information about the infrastructure or public-private partnership project to which a planning process is related.", + "description": "Information about the infrastructure or public-private partnership (PPP) project to which a planning process is related.", "type": "object", "properties": { "id": { "title": "Identifier", - "description": "An externally provided identifier for the project. This can be a URI, an identifier from a projects register or based on the canonical version of the project's name. Project identifiers should be unique within the scope of the publication.", + "description": "An externally provided identifier for the project. This can be a URI, an [Open Contracting for Infrastructure Data Standards Toolkit (OC4IDS)](https://standard.open-contracting.org/infrastructure/latest/en/guidance/identifiers/) project identifier, [OCDS for PPPs](https://standard.open-contracting.org/profiles/ppp/latest/en/framework/#i-basic-project-information) project identifier, an identifier from a projects register, or an identifier based on the canonical version of the project's name. Project identifiers should be unique within the scope of the publication.", "type": [ "string", "null"