Handling Location DTO change to include VerticalDatumInfo

[rma-bryson]

Background

As part of ongoing work to support Vertical Datum for TimeSeries, Ratings, and Locations, a VerticalDatumInfo object is used to handle conversions to other datums.

At present, Location does not use a VerticalDatumInfo object, but it was decided that it should for consistency with the other resources.

Problem

Introducing VerticalDatumInfo for Locations will result in a different response shape than what has historically been used. Specifically:

• elevation

• elevationUnits

• verticalDatum

are no longer flat fields, and are instead represented via the VerticalDatumInfo object.

This is a breaking change for existing clients that consume Location representations in the current format.

Question / Discussion

What is the recommended procedure for handling breaking DTO / response-shape changes like this while maintaining compatibility with clients that rely on older formats?

We discussed a couple of potential approaches:

1. Introduce a new Location DTO (e.g. LocationV2)

• This would allow posting data in either the legacy or new format

• However, responses would always return the newer representation, which would still break existing consumers

2. Introduce a new API version (e.g. application/json;version=3)

• Keep the existing Location representation intact for older versions

• Introduce the VerticalDatumInfo-based structure in the new version

• Avoid mixing legacy and new schemas in the same contract

Before moving forward, we wanted to open this discussion to confirm:

• What the preferred approach is for schema-breaking changes like this

• Whether introducing a new API version is the intended mechanism

• Or if there is an established pattern we should follow instead

Example of change:

Old:

{
  "name": "LOC_TEST",
  "latitude": 38.5816,
  "longitude": -121.4944,
  "public-name": "LOC_TEST",
  "long-name": "LOCATION_TEST",
  "description": "For Testing",
  "timezone-name": "UTC",
  "location-kind": "SITE",
  "nation": "US",
  "state-initial": "CA",
  "county-name": "Sacramento",
  "nearest-city": "Sacramento",
  "horizontal-datum": "NGVD-29",
  "published-longitude": 38.5816,
  "published-latitude": -121.4944,
  "vertical-datum": "NGVD-29",
  "elevation": 36.089,
  "elevation-units": "ft",
  "map-label": "label",
  "bounding-office-id": "SPK",
  "office-id": "SPK"
}

New:

{
  "name": "LOC_TEST",
  "latitude": 38.5816,
  "longitude": -121.4944,
  "public-name": "LOC_TEST",
  "long-name": "LOCATION_TEST",
  "description": "For Testing",
  "timezone-name": "UTC",
  "location-kind": "SITE",
  "nation": "US",
  "state-initial": "CA",
  "county-name": "Sacramento",
  "nearest-city": "Sacramento",
  "horizontal-datum": "NGVD-29",
  "published-longitude": 38.5816,
  "published-latitude": -121.4944,
  "map-label": "label",
  "bounding-office-id": "SPK",
  "office-id": "SPK"
  "vertical-datum-info": {
    "unit": "ft",
    "native-datum": "NGVD-29",
    "elevation": 36.089,
    "offsets": [
      {
        "to-datum": "NGVD-29",
        "value": 0.0,
        "estimate": false
      },
      {
        "to-datum": "NAVD-88",
        "value": -2.532,
        "estimate": true
      }
    ]
  }
}

[rma-bryson]

@MikeNeilson @rma-rripken @adamkorynta @krowvin @msweier @rma-psmorris - tagging for discussion

[rma-rripken]

The rest of the json is kebab-case is the vertical datum going to be camel?

[rma-bryson]

No, I just injected that wrong. Its fixed now to all be kebab-case

[krowvin]

In order of my opinion high to low

Consider

/location/datum to only return additional datum metadata, for users that need that

Keep original same

A paramter include-datum-info to include key vertical-datum-info, but also return the vertical-datum key separately with it

A new response version
But could be troublesome if you make v3 the default response and not obvious it is an option

4. A variation of one or more of the above. Not just one of those.

[rma-rripken]

I like Charles #1. That way the existing Location DTO wouldn't have to change. The new datum controller would (presumably) be fast b/c its just the vertical-datum-info and not the rest of the Location metadata.

It is possible also to add vertical-datum-info to Location in a way that wouldn't break existing clients but I don't like it b/c it makes the DTO ambiguous - pulling the vertical-datum-info out completely seems much cleaner.

TimeSeries and Ratings also have vertical-datum-info. Similar end-points could be added for them. But then again those vertical-datum-info are just the vertical-datum-info of the associated Location so adding end-point for them wouldn't be that helpful.

Who asked for/needs vertical-datum-info? Does @msweier use it? Maybe we can hear what they think.

[msweier]

Yeah it was me, but I know of other districts that are just tracking datum conversions without cwms since this isn't exposed (I suspect many).

I agree with Charles. I was thinking of something like a /location/datum endpoint to manage the conversions, and keeping the timeseries return the same.

The veritical-datum-info from the location is inherited for timeseries, ratings etc.. correct? I can't think of a reason why a datum conversion would be different for a timeseries or rating at the same location.

Right now, it seems like the vertical datum info is based on an elevation conversion (offsets). I could also see the need for the conversion from the stage to a given elevation (I often see that info displayed from stage to elevation). I realize this may be more a database issue, and I can back out what I need from the elevation and offsets....but food for thought.

[rma-bryson]

Will move forward with adding a datum endpoint. Created a github ticket to track: #1577