Extend items with deliveryAddress and deliveryLocation

[timgdavies]

Including location information in OCDS has been discussed in issue #26. This issue summarises the current proposal, with a view towards agreement for version 1.1 of the standard.

An extension has been developed here which proposes the inclusion of two new properties against items:

• deliveryAddress - a standard Address block which can be used to provide a postal address where services should be delivered.
• deliveryLocation - a new block consisting of GeoJSON geometry objects and Gazetteer entries to describe a wider range of locations to which the contract line item relates.

It also proposes a new gazetteer codelist for identifying Gazetteers.

Below is an example of a geolocated item:

"items": [
    {
        "id": "item1",
        "description": "Ceremonial Trumpets for Oxford Town Hall",
        "classification": {
            "description": "Trumpets",
            "scheme": "CPV",
            "id": "37312100",
            "uri": "http://purl.org/cpv/2008/code-37312100"
        },
        "deliveryLocation": {
            "geometry": {
                "type": "Point",
                "coordinates": [51.751944, -1.257778]
            },
            "gazetteer": {
                "scheme": "GEONAMES",
                "identifiers": ["2640729"]
            },
            "description": "Central Oxford",
            "uri": "http://www.geonames.org/2640729/oxford.html"
        },
        "deliveryAddress": {
            "postalCode": "OX1 1BX",
            "countryName": "United Kingdom",
            "streetAddress": "Town Hall, St Aldate's",
            "region": "Oxfordshire",
            "locality": "Oxford"
        },
        "unit": {
            "name": "Items",
            "value": {
                "currency": "GBP",
                "amount": 10000
            }
        },
        "quantity": "10"
    }
]

Comments on this proposed location element are encouraged, including:

1) The structure of the location element (deliveryAddress, deliveryLocation, use of geoJSON, and Gazetteer approach) 2) Whether attaching location to line items is sufficient for most use cases;

[anderspeders]

Hi Tim, everyone,

Thanks for sharing this and kicking this off. For extractive contracts we have identified the same needs (with some adjustments). At NRGI plan to implement both in an upcoming November sprint for a redesigned resourceContracts.org:

• https://github.com/NRGI/resourcecontracts.org/issues/447
• https://github.com/NRGI/resourcecontracts.org/issues/484

For deliveryLocation you will notice that we will on extractives contracts both seek to implement points (one lat, long) and contract areas (multiple lat, longs) when capturing metadata. In order to try to get the geo stuff right we worked with Cadasta.org and @RBanick who did some amazing scoping work with us based on contracts from the Philippines: https://docs.google.com/document/d/1cJAw1a5wk6e0izNkELUHCgBSdH4toqvXs-4cU_tIyxk/edit

[CountCulture]

I find the term "deliveryAddress" somewhat confusing, particularly in conjunction with terms such as postal address. Feels like this could be one of:

• mailing address of the supplier
• address to which the goods are delivered
• location of the delivery of services, which would often be not an address but an area - e.g. district council boundary, in the case of waste disposal

[timgdavies]

For locations for delivery of services, use of deliveryLocation would be the appropriate property, where the gazetteer option could be used to classify using a recognised vocabulary for sub-national geographic area and/or a geoJSON objcet with the boundary could be provided.

We should be clear in guidance that a deliveryAddress would only ever be used when the good or service is substantially being delivered to to that street address.

It should not be used for any address information of the supplier, or just for the postal address of the buyer (which can be included in the buyer and supplier organisation objects respectively).

On Wednesday, October 7, 2015, CountCulture notifications@github.com wrote:

I find the term "deliveryAddress" somewhat confusing, particularly in conjunction with terms such as postal address. Feels like this could be one of:

• mailing address of the supplier
• address to which the goods are delivered
• location of the delivery of services, which would often be not an address but an area - e.g. district council boundary, in the case of waste disposal

+44 (0)7834 856 303 @timdavies http://www.timdavies.org.uk

[CountCulture]

Maybe we could make that clearer in the naming (serviceDeliveryAddress?). We could also use 'physical address' rather than 'postal address', or maybe just 'address'?

[AlCollier]

Worth considering whether physical address might be a Global Location Number https://en.m.wikipedia.org/wiki/Global_Location_Number and if so how this might be indicated. GLNs can indicate a more-precise delivery point than a postal address - such as a warehouse dock or shelf - so "physical location" might be better than "physical address". Also worth considering how we denote the different components of an address - useful for example for postal/zip code to be consistently in the same field.

-----Original Message----- From: "CountCulture" notifications@github.com Sent: ‎07/‎10/‎2015 15:31 To: "open-contracting/standard" standard@noreply.github.com Subject: Re: [standard] Extend items with deliveryAddress and deliveryLocation(#250)

Maybe we could make that clearer in the naming (serviceDeliveryAddress?). We could also use 'physical address' rather than 'postal address', or maybe just 'address'? — Reply to this email directly or view it on GitHub.

[rbanick]

I agree that "delivery" and "address" are misleading terms. Delivery certainly makes no sense in extractive industries, where locations describe concessions areas where resources are extracted -- the very opposite of delivery. In the same vein these areas are not addresses in the traditional sense: an offshore drilling area has no address.

Could we use Location to refer to the contract area and use an alternate term for the gazetteer reference area?

[timgdavies]

In terms of procurement contracts around which OCDS is currently focussed (extractives extension on the roadmap), my sense is that the deliveryAddress property, pointing to an address object does have a coherent meaning (Line item X should be delivered to street address Y).

As a property, deliveryAddress would rarely have use in an extractives context as it seems to be only really relevant for goods and services - so even if extractives re-uses the address object, it might be more appropriate to have a different property name.

For locations (Gazetteer entries and GeoJSON points/lines/polygons), we could consider either (a) re-using the same object in procurement and extractives contexts, but having a different propertyName to attach it (as it would be likely to also attach at a different point in extractives... i.e. not to line items); or (b) try and come up with a property name that captures the semantics of both cases.

Right now, the semantics of deliveryLocation are intended to be: the goods or services will ultimately end up being provided in this area.

(Summary - let's see how we can re-use the same objects for address and location across OCDS and ResourceContracts.org, but not worry too much about the property names that attach them to their parent objects right now....)

[timgdavies]

@AlCollier wrote:

Worth considering whether physical address might be a Global Location Number https://en.m.wikipedia.org/wiki/Global_Location_Number and if so how this might be indicated.

I suspect in this case it would make most sense to extend the address object attached by the deliveryAddress property to contain an extra property for globalLocationNumber (following the naming convention of Schema.org which we've tried to stick to in our address block already).

Are there use cases where public procurement systems are recording GLNs?

[AlCollier]

The UK National Health Service (which is a huge public procurer) announced their adoption - see for example https://www.gov.uk/government/news/it-systems-and-coding-including-gs1. Not sure how far they've got in practice. But given use of these codes in EDI it seems probable that they will exist in source systems.

-----Original Message----- From: "timgdavies" notifications@github.com Sent: ‎08/‎10/‎2015 10:12 To: "open-contracting/standard" standard@noreply.github.com Cc: "Al Collier" collier.al@gmail.com Subject: Re: [standard] Extend items with deliveryAddress and deliveryLocation(#250)

@AlCollier wrote: Worth considering whether physical address might be a Global Location Number https://en.m.wikipedia.org/wiki/Global_Location_Number and if so how this might be indicated. I suspect in this case it would make most sense to extend the address object attached by the deliveryAddress property to contain an extra property for globalLocationNumber (following the naming convention of Schema.org which we've tried to stick to in our address block already). Are there use cases where public procurement systems are recording GLNs? — Reply to this email directly or view it on GitHub.

[timgdavies]

Thanks @AlCollier. Really useful. Let's look out for a first case of this in data coming into OCDS, and see if we can work up extension at that point.

[CountCulture]

I think it's worth being rather cautious about this. GS1 codes are in general proprietary.

[AlCollier]

Take your point Chris. Not suggesting baking in GS1 per se but that if a system holds address data other than as a street address there should be a means to represent this, including the value and the encoding scheme used.

[timgdavies]

AidData have been doing some work which may be relevant to consider in finalising proposals here.

[timgdavies]

There is an updated version of the Location Extension here in the new extension format.

[timgdavies]

The current extension uses a single deliveryAddress for an item. However, I recently encountered a a consultancy contract tender which listed multiple work locations.

Should deliveryAddress allow an array, or should this be modelled by providing separate items for each location.

[joshuacpowell]

This matches with our experience. For one item classification (e.g. textbook delivery) you may have dozens (or more) delivery locations. I would favor an array of locations for a single item, rather than replicating items for the primary reason of data entry error risk: if you have 100 textbooks being delivered to 10 locations, users would need to allocate the textbooks to locations. In the worst case, this introduces a higher risk of double counting (e.g. entering 100 textbooks per location, rather than allocating across).

[georgneu]

The option to include multiple delivery locations does definitely meet the use case of citizens trying to monitor or track service delivery (as has come up in developing the use case for Buenos Aires). While its seems that this information is currently rarely captured in procurement systems, it could provide an opportunity to improve data quality.

[duncandewhurst]

@myroslav looping you in here following our conversation on use of items.deliveryLocation and items.deliveryAddress in the e-Auction scenario.

The semantics of delivery in the property name don't work for an e-Auction where the item is being sold rather than purchased.

Could we simply use items.location and items.address as the property names for all scenarios and add a description property to the address and location blocks to indicate what the address/location represents?

[timgdavies]

UK Government standards require that location information specifies the Co-ordinate Reference system being used for locations.

The way we use GeoJSON in the current OCDS location extension does not provide for specification of a Co-ordinate Reference Scheme (crs).

GeoJSON is also currently in the IETF standards track, which removes the crs attribute, and requires locations use WSG84.

We should update the documentation for the location extension to make clear co-ordinates should be in WSG84.

[andrewlorien]

Just starting to look into this... and to add just a little bit more complexity, Australia has our own standard which takes continental drift into account and deviates by about half a metre from WSG84. I don't know any departments who are using this in their contracts (we have very good, very standard national street addresses, even for coal mines). http://www.geoproject.com.au/gda.faq.html#q09

[timgdavies]

Thanks Andrew. This is handy pointer.

Do you think it is acceptable for us to folow GeoJSON though and use WSG84 in the standard, leaving it to publishers and users to convert data if required (for which I believe tools like ArcGIS have reusable libraries)?

We could add more documentation/guidance to make users aware.

@idlemoor might also have some GIS insights to add here...

[idlemoor]

I can certainly sympathise with the point of view that explicitly naming a CRS is an unnecessary complication that OCDS could well do without. There are thousands of national coordinate systems in the EPSG database. In a national context, people will either use the relevant national or local CRS, or what they habitually call "WGS84". Many local datums differ from WGS84 by hundreds of meters, so it's very important to know in which system the coordinates are expressed, and that's what's going on in the UK standards Tim refers to: OSGB36 is between 70 and 120 meters to the east of WGS84.

However, in the international context, people tend to use "WGS84". By this, they mean "what my GPS would show when it is set to the setting labelled WGS84". But strictly speaking, as Andrew points out, WGS84 is only one of many Terrestrial Reference Frames. The various TRFs are intended to compensate for continental drift (which involves both shift and rotation), geoid shape and glacial rebound (remember we are working in three dimensions, not two). Strictly, WGS84 works properly only in North America; other TRFs include ETRS89, used in Europe, and GDA94 (to be replaced by GDA2020) in Australia. There is a canonical TRF (ITRF2005) to which the others are referred.

It is important to note that the TRFs are not as chaotic as the legacy CRS's. They are modern standards that were created as close as reasonably possible to each other, and are only diverging slowly.

If you care about centimeter accuracy over decades you will always refer your coordinates to a local fixed datum on the ground (e.g. a nice brass stud) that has been accurately surveyed according to the local TRF.

If a couple of meters is good enough, for now you can just say "WGS84", and hope people in the twenty-fourth century will know what you meant and forgive your laxity.

Anyway, that is why GeoJSON purports to use WGS84, as probably should OCDS, or at least until GeoJSON sees fit to change.

Hope it's reasonably clear?

[duncandewhurst]

In NSW Australia eTendering system locations are specified at tender level and are defined based on both:

1. a list of NSW regions which is not known in any of the existing gazetteer codelist options.
2. a list of 'States and Territories'

(see example)

To meet this use case deliveryLocation would need to be specified at tender level, the list of NSW regions would need to be added as a local extension to the gazetteer codelist and either deliveryLocation or deliveryLocation.gazetteer would need to be array to capture both the region and state/territory level definitions.

[mpostelnicu]

To allow planners specify locations before achieving tender stage, for Vietnam we also have locations at the planning level. We are using the same location entity type you defined in the extension, but besides Item we also apply an array of locations to the Planning entity.

[timgdavies]

@mpostelnicu Just to check - did you consider using a tender block with a tender.status of 'planned' still at the planning stage, and locations attached to items there?

In OCDS, a planning release can (and often should) still include a tender block with information about the anticipated future tender.

I realise for some very early planning stages this may not be possible.

[jpmckinney]

Closed with creation of https://github.com/open-contracting/ocds_location_extension