media type(s) in APIs

[cportele]

We are working on CityJSON support in an API that implements OGC API Features and have a few questions:

• Currently there does not seem to be a registered media type for CityJSON. Are there any plans to register one? application/json is too general, e.g. for browsers to determine to which application the content should be delegated.
• Is there a timeline for v1.1? The main reason for the question is whether we should add support for the proposed CityJSONFeature concept and text sequences now or better wait. There is again the media type question as the same applies to application/json-seq.

Thanks!

[hugoledoux]

Great to hear that you are working on CityJSON support for OGC API Feature.

You should probably be aware that we had one student who finished an MSc thesis recently (link PDF + code not very cleaned...), but the aim was to mostly design the database so that features are served quickly. She didn't implement all the OGCAPIF specs, but the core follows it. Server was a done with Flask, which allows streaming too. Maybe this help?

Media type

No I didn't really consider this since I didn't think CityJSON was important enough for this, but now that you mention it, maybe I should apply. Also because now it's an OGC community standard. I'll think of this more... I guess you recommend us doing this?

v1.1 timeline

The draft is more or less finished, in branch "v1.1" in the specs folder you have the text (compiled there). We're currently testing and updating cjio (it will take a CityJSON and spit out a json-seq of CityJSONFeature).

We plan to release v1.1 in the fall.

I don't expect big changes from the current status, so you can start now I'd say. But this is where the feedback of the OGCAPIF team would be very useful, do you see things that could be improved?

[evetion]

With regards to media types, I roughly see the following options:

• No specific media type application/json, like topojson (https://github.com/topojson/topojson-specification/issues/11)
• Specific media type application/city+json, like geo+json. This can be done without an official RFC, but would be nice.
• Very (vendor) specific media type, like application/vnd.cityjson+json;version=x.y, like github does. Would make more room for other (sub)types or version differences.

Note that the ;parameter=value could be applied to any of the above.

[evetion]

Note that there are currently no OGC specific media types registered. In the past standards like WFS just used text/xml and the newer REST based specs use application/json.

I could imagine OGC as vendor in these media types, like application/vnd.ogc.city+json, but this would also work for OGC API Features: application/vnd.ogc.api.feature+json?

[cportele]

Thanks for the responses, and thanks for the link to the thesis. I will read it to see, if we can learn something for our implementation, which will be different, because there is already a database and CityJSON will not be the only output format.

Yes, I would recommend to register a media type (and a separate one for the text sequences encoding). Otherwise there is no proper way for clients to know that the API will provide data in CityJSON or that a response is CityJSON and not some other JSON format for features.

By the way, OGC has so far registered 3 media types for encodings (GML, GeoPackage and GeoXACML): application/gml+xml, application/geopackage+sqlite3, application/geoxacml+xml. Since CityJSON is now an OGC Community Standard it should also be possible to register a media type in the standards tree through OGC, but another option could be a registration in the vendor tree (as OGC or TU Delft).

For the JSON encoding of resources defined in OGC API standards we had briefly discussed registering one or more media types, but so far always decided against it, as this did not seem necessary so far. (I expect that this will change in the future once resources are reused outside of an API context, but this will require a better understanding to decide what to register and how to name it.)

Regarding the 1.1 timeline: good to know, I think we will go ahead and implement CityJSONFeatures and text sequences. It should be straightforward to do. I will get back, if I find any issues. So far, I have two observations:

• Since metadata has to be written first, it will not be possible to include the extent in the response unless we would do a query first to determine the extent of all selected data, but that will just increase the response time and in particular the time until the response starts. Any other approach to "guess" the extent will not result in a correct extent. But since that information is optional this should not be an issue per se. Unless, of course, if clients will only work, if the extent information is present.
• Since several members like metadata or transform must not be part of a CityJSONFeature object a single CityJSON feature response needs to be encoded as a CityJSON object and not a CityJSONFeature object. I guess that makes sense (even if it initially sounds counter-intuitive), because this is also what clients expect today.

[hugoledoux]

I have applied 3 days ago for a media type with iana, I applied for application/city+json.

I'm waiting to hear from them, will update here.

[hugoledoux]

okay it's just been approved: https://www.iana.org/assignments/media-types/application/city+json

I haven't applied for city+json-seq because it's only in v1.1, which is not a standard of the OGC (yet), and the approval is only doable through the OGC.