Missmatch in item property.datetime definition in spec and openapi.yaml

[ltshb]

In the STAC SPEC v0.9.0 the item property.datetimeis defined as a single datetime in isoformat; see https://github.com/radiantearth/stac-spec/blob/v0.9.0/item-spec/item-spec.md#properties-object while datetime range are specified in https://github.com/radiantearth/stac-spec/blob/v0.9.0/item-spec/common-metadata.md#date-and-time-range to use property.start_datetime and property.end_datetime.
However the openapi.yaml (see https://stacspec.org/STAC-api.html#operation/getFeature and https://github.com/radiantearth/stac-spec/blob/568a04821935cc92de7b4b05ea6fa9f6bf8a0592/api-spec/STAC.yaml#L1291) specifies the datetime as a single datetime or a range separated with '/'! This is probably a copy paste mistake with the query parameter datetime ?

[m-mohr]

Thanks! Yes, that seems to be a copy&paste issue we need to fix.

[cholmes]

Ok, so I just dug into this and I think it's actually not an error. But admittedly it's a bit confusing.

The datetime specified in the OpenAPI documents is the query parameter. It's how you request a search against your STAC items. It's from the OGC API - Features specification: http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime

The times we specify in STAC core are our content model. You can have either datetime as one value, or start_datetime and end_datetime. In the latter case the datetime query would return against the 'default value', as determined by the server.

It's a little confusing since STAC's content type is called the same thing as the query parameter. But it could have been something totally different. Like if we called it stac_datetime stac_start and stac_end the query parameter would still be 'datetime', and would still work in the range thing. The range thing makes sense in a query, but it would make less sense for us to represent a time range in STAC as 'date1/date2'.

I could see an argument that it makes sense to try to align them, but on this query we're fully based on OGC API -Features, where the datetime parameter comes from, and I'm pretty sure they would not go for the extra complexity.

[m-mohr]

@cholmes No, it IS actually a bug, look here:

I also first found the parameter, but there's also a schema for the properties and that is actually wrong.

Edit: But we also need to ensure that the search still works, so that you can give datetime in the JSON body with the / and .. notations. I guess that's also where the issue may originate from

[cholmes]

Ah, ok. Tried to check closely. I'll dig in again and fix it.

[cholmes]

So it seems like the proper thing to do here is to make it so in openapi it gets across that people need to either have datetime or start_datetime & end_datetime. Is that possible? Does that seem like the right approach? Do an required anyOf with datetime or start/end. If anyone knows off hand how to approach this in OpenAPI I'm all ears. Or else I'll try to figure it out.

For the search with JSON we have it in an example (in examples.md), with "datetime": "2019-01-01/2019-05-01".

[m-mohr]

Sure, it's the same as in the JSON Schemas except that the type: null must be nullable: true.

Indeed, for search this must still be the case after your changes.

[m-mohr]

A PR is up for review: #54