Support sub-locations on a location

[bmeesters]

Former title: Support zero or multiple geoReferences on locations. But decided to change the solution direction to move towards locations being able to point to other locations.

Type of request

• [x] I'd like to add something to the OTM 5 spec
• [ ] I'd like to change something in the OTM 5 spec

Is your feature request related to a problem?

There are a few problems with how locations can be modeled in OTM5:

1. A location that has only an address is inconsistent with a location that has both coordinates and an address.
2. Sometimes, you need more than one type of georefence for a location. For example whenever you want to model the area the location is occupying, exact coordinates that can be used for route guidance, and an address.
3. Larger locations often have multiple 'points of interest'. You cannot model the relationships between these points of interest and the parent location where they are present.

Each of these will be explained in more detail below:

1. Locations are inconsistent depending on their fields

Currently locations are required to have a geoReference. An awkward consequence is that if you have locations with some geoReferences and some address and those with only addresses that the format is not consistent:

// Only an address
{
  "id": "d90b4a73-0e45-46d1-ae86-f8142e031848",
  "geoReference": {
    "street": "Valutaboulevard",
    "houseNumber": "16",
    "houseNumberAddition": "C",
    "postalCode": "3825 BT",
    "city": "Amersfoort",
    "country": "NLD",
    "type": "addressGeoReference"
  }
}

// Now also with coordinates
{
  "id": "d90b4a73-0e45-46d1-ae86-f8142e031848",
  "geoReference": {
    "lat": 52.1938878,
    "lon": 5.4043508,
    "type": "latLonPointGeoReference"
  },
  "administrativeReference": { // address had to move...
    "street": "Valutaboulevard",
    "houseNumber": "16",
    "houseNumberAddition": "C",
    "postalCode": "3825 BT",
    "city": "Amersfoort",
    "country": "NLD"
  }
}

2. Not being able to have multiple geoReferences

Locations often have multiple geometric properties that can be of interest:

1. The official address of the location.
2. The lat/lon coordinates that can be used for route guidance.
3. The surface area of the location
4. First and last miles to get to the location.
5. A post address that does not have to be the same as the physical address.

Some of these can already be solved in OTM5. It is possible to provide both an address and coordinates (see example in 1), but it is not possible to have both a surface area and coordiantes that can be used for a route guidance.

3. Multiple points of interest.

Larger locations that are used for logistic operations (such as warehouses) often are so large that there are multiple points of interest. For example a distribution center often has multiple docks where you can load/unload. You can work around this issue by creating new OTM locations for each dock. But there is no means to link those docks to the official location, potentially resulting in repeating the same shared data over and over again.

Describe the solution you'd like

To solve these issues I propose the following changes:

1. Make the geoReference in a location optional instead of mandatory. This ensures that locations with an address and locations with an address + coordinates looks consistent. It is also an easy change to do.

2. Support sub-locations on a location. This is a change that requires just one extra field without any new formats while opening multiple options

   • You can cleanly model points of interest like docks or charging stations that are present on a distribution center.
   • Whenever you need to model elaborate locations that need coordinates, surface areas, post addresses, official addresses, etc. you can all model these using sub-locations. It also allows control over what location information to share with what parties. Since you can always choose to only send the sub-locations that are relevant.

An example would look like:

{
    "id": "d90b4a73-0e45-46d1-ae86-f8142e031848",
    "name": "parent location",
    "geoReference": {
        "lat": 52.1938878,
        "lon": 5.4043508,
        "type": "latLonPointGeoReference"
    },
    "administrativeReference": {
        "street": "Valutaboulevard",
        "houseNumber": "16",
        "houseNumberAddition": "C",
        "postalCode": "3825 BT",
        "city": "Amersfoort",
        "country": "NLD"
    },
    "subLocations": [
        {
            "associationType": "inline",
            "entity": {
                "id": "3f39c1f6-2653-4f6a-a6bf-57c3fe8fa054",
                "name": "dock on parent location",
                "geoReference": {
                    "lat": 52,
                    "lon": 5,
                    "type": "latLonPointGeoReference"
                }
            }
        },
        {
            "associationType": "inline",
            "entity": {
                "id": "b61acb70-64ef-40d1-8251-709d080b8153",
                "name": "postal address",
                "administrativeReference": {
                    "street": "Some other value",
                    "houseNumber": "16"
                }
            }
        }
    ]
}

[thomaskolmans]

I think it's best suited to have the address georeference removed as it only creates the possibility for confusion.

[bmeesters]

@thomaskolmans We cannot remove it as that would require we go to OTM6.0. We can only deprecate it, which is the proposed approach.

[bmeesters]

We had a discussion a little while ago, but I forgot to post the conclusions. In general we see the value, but the more general solution would be if we can support 'locations' within locations. That way, you can add multiple addresses, each with their own coordinates that all relate to some overarching location.

Examples include:

• Docks in warehouses, where you want to precisely define where trucks need to load and unload.
• Cities, that have their own geographical boundaries, but also points of interest in those cities with their own addresses.
• Environmental zones.

We can opt for a similar solution as with consignments and support 'relatedLocations` as a new field on the location itself.

[bmeesters]

Discussed: we want examples to see how it works. I'll prepare something for the next time.

[bmeesters]

I have updated the description with examples and more descriptions on the why and the how

[bmeesters]

Discussed last Wednesday and accepted as candidate for OTM5.6

[bmeesters]

This is now part of OTM5.6 so can be closed.