Coordinates of a location

[larsolofsson]

In current schema latitude and logitude are just two optional properties. But both are required to specify the coordinates of a location. papiNet also needs to clarify what geodetic datum to use for the coordinates. The most common geodetic datum is WGS84. I propose that the coordinates are specified in an object that can be reused in several places.

CoordinatesWGS84:
  type: object
  required:
    - latitude
    - longitude
  properties:
    latitude:
      type: number
    longitude:
      type: number

I also propose a new design rule. When two or more properties are closely related and dependant on each other, then these properties should be specified in an object. For example, coordinates of a location can be optional in a construct, but both latitude and longitude are required for the coordinates.

[patricekrakow]

But, then we will have to change the structure from

{
  "id": "4cc7b1ba-6278-4a56-9ee2-ad316950c008",
  "name": "Sappi Lanaken Mill",
  "country": "BE",
  "latitude": 50.8827787,
  "longitude": 5.6375872
}

to

{
  "id": "4cc7b1ba-6278-4a56-9ee2-ad316950c008",
  "name": "Sappi Lanaken Mill",
  "country": "BE",
  "coordinatesWGS84": {
    "latitude": 50.8827787,
    "longitude": 5.6375872
  }
}

And the coordinatesWGS84 will not be required in the object, but the properties latitude and longitude will both be required within coordinatesWGS84.

We also think that the structure:

{
  "latitude": 50.8827787,
  "longitude": 5.6375872
}

could be defined by a global type CoordinatesWGS84:

CoordinatesWGS84:
  type: object
  required:
    - latitude
    - longitude
  properties:
    latitude:
      type: number
    longitude:
      type: number

[patricekrakow]

I would be a bit reluctant to make this kind of grouping mandatory as a style rule because sometimes this kind of grouping results in a verbose/hierarchical structure while a flat structure might be preferred.

[patricekrakow]

We will use the structure

{
  "id": "4cc7b1ba-6278-4a56-9ee2-ad316950c008",
  "name": "Sappi Lanaken Mill",
  "country": "BE",
  "coordinatesWGS84": {
    "latitude": 50.8827787,
    "longitude": 5.6375872
  }
}

that will help to support other coordinate systems using similar structure such as:

"coordinates____": {
  "____": 9.99,
  "____": 9.99
}

However, using this kind of hierarchical substructures should not be automatic, but we should consider them case by case.

[patricekrakow]

Done within https://github.com/papinet/papiNet-API/commit/19205ca38528bcb97c62243183dce00b64ef10ee.