Feature snapshot with `datetime` parameter

[alexrobin]

I have recently discovered that GML has the concept of DynamicFeature and Feature snapshots. This is a concept we would like to use in Connected Systems as well, but applied to GeoJSON (and other response formats).

I was wondering if using the datetime query parameter to specify the validTime of feature snapshots is appropriate, in addition to its filtering role.

In Connected Systems, we were thinking of having it work the following way:

• If datetime is a time instant T, then only features valid at T are returned, and, for dynamic features, a snapshot of its dynamic properties is provided at exactly T or the latest possible time before T.

• If datetime is a time period [T1,T2], then only features valid at anytime during the period are returned, and, for dynamic features, a snapshot of its dynamic properties is provided at exactly T2 or the latest possible time before T2.

• When no datetime parameter is specified, all features are returned, and, for dynamic features, a snapshot of its dynamic properties is provided at the current time or the latest possible time before the current time.

Does it make sense to you?

[cportele]

@alexrobin

So far, there was no explicit proposal or discussion to support the dynamic feature concept of GML (where each real-world phenomenon is mapped to a single feature and time-varying properties are represented so that the temporal validity is associated with each value).

Another option, which is also used in practice, is to map each version of a real-world phenomenon to a feature, which is different from the dynamic feature approach in GML.

There were a few discussions over the last years about support for versioning in general; for example, see #430 and #764. However, so far, there was no in-depth discussion or design and it would require a new task in the SWG charter (that said, starting new work only after a charter update does not seem to be how many/most SWGs seem to operate these days, so maybe we also shouldn't worry about it).

In any case, any design should also address how this impacts or changes other building blocks (e.g., the filter parameter from Part 3, property references in CQL2, the CRUD operations in Part 4, or the properties in the schema in Part 5, etc.).

From an API perspective, RFC 7089: HTTP Framework for Time-Based Access to Resource States -- Memento including the relevant HTTP headers and link relation types should be considered as well in the design.

With respect to the thinking of the Connected Systems SWG, the behavior is for features as you have described it (if the API uses datetime to filter based on temporal validity of the feature); this is specified in Part 1.

For an approach with "dynamic features", the behavior of the datetime parameter seems to be what I would expect, except for the case where no datetime parameter is present. In that case I would have expected all time slices / snapshots, at least if the API does not specify a default value for datetime.

[alexrobin]

@cportele Thanks for your insights.

Including all time slices by default (i.e. when no datetime is provided) is problematic when values of dynamic feature properties change often (e.g. when observed by automated sensors) as it could be a very large amount of data. That's why we were thinking of having a default to include the 'latest' known value instead.

We would also like to avoid creating a new feature (with a new identity) every time properties change ; that's why we like the GML concept of dynamic features.

Do you see any issues with us defining this kind of snapshot behavior in OGC API - Connected Systems? That would really help us bridge the gap between features and observation data streams.

[cportele]

Do you see any issues with us defining this kind of snapshot behavior in OGC API - Connected Systems?

My concern is that this changes the semantics of the datetime query parameter. It no longer simply selects the items, but also changes/subsets the content in the response. I have not thought this through, but it could still work, if you use a different itemType for these collections (e.g., "dynamicFeature" instead of "feature") with a different description of the query parameter.

[alexrobin]

We would like to keep itemType=feature because our goal is to stay compatible with vanilla feature API clients. If reusing datetime is not possible, in that case, I would rather define a new query parameter, perhaps validTime or snapshotTime.

If using the existing datetime parameter. We would still honor the filtering/selection behavior so it's still compliant with features. Do you think there could be side effects of changing the content dynamically (after all the server may change the content of a feature at any time, right?)

[cportele]

On the items endpoint, the server is supposed to return a representation of the features based on the parameters of the GET request. The various query parameters and HTTP headers have well-defined semantics that the server should honor. There should not be "side-effects".

When we look at the existing parts of Features plus the proposals, we can distinguish four types of parameters:

• bbox, datetime, filter, q, and ids impact which features are selected (no impact on the representation);
• crs, properties , skipGeometry, and maxAllowableOffset as well as the accept, accept-language, and accept-encoding headers impact the representation of each feature (no impact on the selection);
• filter-crs and filter-lang impact the interpretation of the value of another parameter;
• limit, offset (or whatever mechanism is used to access another page), and sortby impact which selected features are returned and their order.

Of course, any standard or implementation can add additional parameters.

[alexrobin]

Ok, I didn't see anywhere in the spec that there should not be any "side-effects" but I wasn't sure about it so that's why I asked before we do anything :-). I understand that you would want to avoid it since it's clearly not the intent of the datetime parameter.

What about if we introduce another query parameter in Connected Systems API just called snapshot (either a param with no value or a boolean value), that when used in conjunction with datetime triggers the change in representation by snapshotting dynamic property values at the specified time.

This way we don't change the server behavior for clients not intentionally using the dynamic feature snapshot functionality.

[cportele]

Adding a new boolean snapshot parameter that reduces the representation to property values to the time/interval specified in the datetime parameter would be fine in my view.

Regarding "side-effects": datetime is specified by the Core requirements class as a query parameter that selects features. Introducing an impact on the representation would be changing the semantics of the query parameter. This would be bad API design and could potentially break clients. And if specified in another requirements class, it would break the ModSpec, because the query parameter is redefined.

[alexrobin]

Ok, thanks. We'll look at something like this for CS API Part 2 then.