Proposal: Deprecation of JSON-LD Output

[StephenClouse]

Hi all,

We created this new category "Request For Comment" to solicit some feedback from our core users here before we make major changes to API. There is a formal process that NWS goes through involving public comment and Service Change Notices, and that will still happen, but this is to help us get a feel before we even invest the time to go down that road.

The first big thing we're looking at is reducing the complexity of our API by removing JSON-LD. Note that this is not all the JSON output, GeoJSON will still be around. But here's a bit more info.

When we started the API project around 2017, the Semantic Web and Linked Data was a hot item, and we decided to try to support that vision. But the ecosystem surrounding it has stagnated significantly, and what ended up winning in the end was old-school functional schemas described in rich documentation formats like OpenAPI. We invested a lot of effort a while back to make sure our OpenAPI description was complete and authoritative (even going as far as making the OAPI doc the source of truth internally, and having our application framework build its routing from that instead of the typical other way around), and with that, we don't really feel like JSON-LD is serving a purpose anymore. It's 99% the same as our GeoJSON output, but that spec has far broader support with things like mapping libraries for people building applications.

Some of our trouble with JSON-LD is reflected in the @context on each document, which are both large (so a bandwidth consideration) and mostly incorrect, and it would be a significant effort to make everything compliant. Also, we feel that GeoJSON is preferred by most people but there are unresolvable interoperability issues between the two standards, so our documents have never actually been compliant.

Given all that, we feel like the best long-term course would be to retire JSON-LD and stick to GeoJSON exclusively for geospatially-referenced data, and plain JSON described in our OAPI documentation for the rest.

This would likely be a year-long process that would go as follows:

• We will introduce new application/json outputs for non-geospatial data
• Geospatial endpoints will be pared down to remove application/ld+json and only support application/geo+json. This will include removing LD-specific attributes (like @context) from GeoJSON.
• Note the above is only applicable to JSON outputs. XML outputs (like /alerts CAP) will not be affected.

Anyway, we'd like to know what you all think, and find out if people are seriously using the JSON-LD outputs for production applications. Please let us know your thoughts here.

[netbymatt]

Both of my applications use the default GeoJSON responses. The deprecation process seems reasonable. I'd expect we'd hear about when each of the stages would be implemented in this forum when the time comes.