Inconsistency with C.7 and OGC API Common Part 2

[petergarnaes]

In DMI we are trying do figure out how to describe the temporal axis in our forecast EDR API, which makes several model runs available as instances. Each model run covers different temporal ranges, as it run every few ours to give an updated forecast.

As far as we understand the EDR standard on conformance, OGC API Common Part 2 is the standard that dictates the metadata on collections.

According to the OpenAPI specification from OGC API Common Part 2 on extents, only interval and trs are defined on the temporal object. However, looking at C.7 in EDR standard, values is also defined, and contains no description on how it differentiates itself from interval. Also in C.7, interval is a list of list of strings, where as in the OpenAPI spec for Common Part 2 (as well as the example in Common Part 2) it is a list of strings with exactly 2 elements.

To add even further to the confusion, Common Part 2 states:

Temporal Interval provides a set of temporal periods. Typically only the first temporal period would be populated. However, like Bbox, additional periods can be added if the collection does not form a single temporal cluster.

However, again looking at the OpenAPI spec in Common Part 2:

        "temporal": {
            "description": "Begin and end times of the temporal extent.",
            "type": "object",
            "properties": {
                "interval": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "type": "array",
                        "minItems": 2,
                        "maxItems": 2,
                        "items": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": "true"
                            },
                        "example": [
                            "2011-11-11T12:22:11Z",
                            "2012-11-24T12:32:43Z"
                            ]
                        }
                    },
                "trs": {
                    "description": "Temporal reference system of the coordinates in the temporal extent (property `temporal`). Only the Gregorian calendar is supported by API-Collections. Extensions may support additional temporal reference systems.",
                    "type": "string",
                    "enum": [
                        "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
                        ],
                    "default": "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
                    }
                }
            }

The interval array is only allowed to hold 2 datetimes, ie. only 1 interval, which seems to contradict the above quote as well as the list of lists in annex C.7.

I assume some of these inconsistencies arise from Common Part 2 still not being finished, but the question still remains on how to interpret all of this for a forecast collection with several instances of different temporal range.

[m-burgoyne]

Interval is an array of arrays which define the minimum and maximum of the time period the data represents i.e.

[["2024-03-10T00:00Z", "2024-03-14T12:00Z"]]

if the data contains multiple distinct time intervals with breaks in the data values it can be represented as follows:

[["2024-03-10T00:00Z", "2024-03-10T18:00Z"],["2024-03-11T00:00Z", "2024-03-10T12:00Z",["2024-03-11T18:00Z", "2024-03-14T12:00Z"]]

Values provides a way of listing all of the available time steps within the data; this can be a list of time values or a list of repeating intervals i.e.:

As a list of individual time steps:

["2024-03-10T00:00Z","2024-03-10T03:00Z","2024-03-10T06:00Z","2024-03-10T09:00Z","2024-03-10T10:00Z"]

or as a repeating interval value:

["R5/2024-03-10T00:00Z/PT3H"]

If the interval between time steps changes in the data or there are breaks in the data values it can be represented as multiple repeating interval values as follows:

["R48/2024-03-10T00:00Z/PT3H","R12/2024-03-10T00:00Z/PT6H"]

[petergarnaes]

Thanks for the response, I assume interval would then cover the start of the earliest instance until the end of the latest instance/model run.

I assume values in I just need to specify all timesteps across all instances, even though they overlap a lot.

The way you describe Interval and Values is not supported by the EDR standard itself. Annex C is just informative, and disagrees with the actual standard OGC API Common Part 2. How will this be addressed?

[m-burgoyne]

Yes the extent defined by the Collection response should describe the temporal extent of all instances, the individual instance response extents would describe the temporal extent covered by each instance.

Annex C should be inline with the EDR OpenAPI schemas, which extend OpenAPI spec in Common Part 2 by adding the values attribute see extent.yaml.

I think the impression that there might be a difference is due to the fact that the example value in the JSON is for the inner array not the whole interval attribute, in the schema definition it states that interval is of type array which contains items of type array each of which can contain a minimum of two and a maximum of two string items.

        "temporal": {
            "description": "Begin and end times of the temporal extent.",
            "type": "object",
            "properties": {
                "interval": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "type": "array",
                        "minItems": 2,
                        "maxItems": 2,
                        "items": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": "true"
                            },
                        "example": [
                            "2011-11-11T12:22:11Z",
                            "2012-11-24T12:32:43Z"
                            ]
                        }
                    },
                "trs": {
                    "description": "Temporal reference system of the coordinates in the temporal extent (property `temporal`). Only the Gregorian calendar is supported by API-Collections. Extensions may support additional temporal reference systems.",
                    "type": "string",
                    "enum": [
                        "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
                        ],
                    "default": "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
                    }
                }
            }

[petergarnaes]

Annex C should be inline with the EDR OpenAPI schemas, which extend OpenAPI spec in Common Part 2 by adding the values attribute see extent.yaml.

Ahh, I see the OpenAPI spec indeed does specify this. I do struggle to find where in the EDR standard it states that the OpenAPI specification in EDR is the defacto standard to apply, and how the this extension that you mention works. I'm not good enough at reading the document it seems, but I'm curious to know how it applies.

I think the impression that there might be a difference is due to the fact that the example value in the JSON is for the inner array not the whole interval attribute, in the schema definition it states that interval is of type array which contains items of type array each of which can contain a minimum of two and a maximum of two string items.

You are absolutely right, my mistake

Edit: The Common Part 2 example is wrong, and is not a double array, which probably also added to my confusion.

[chris-little]

@petergarnaes @m-burgoyne actual standard OGC API Common Part 2. Do not forget that Common Part 2 has still not been approved, and it was a moving target when we developed API EDR. There are also other problems with it which are currently being discussed (what is a Collection allowed to contain? Processes? Queries? Or just "data"?
In the longer term, through the Temporal DWG, I envisage being able to set up a Temporal CRS with, say, UoM of hours, direction positive, origin of T+0 with an epoch/temporal datum specified by an ISO8601/RFC3339 timestamp and using a notation like WKT uses for Unix/Posix time.

[chris-little]

@petergarnaes This issue should be addressed when we have created and merged a PR to address adding support for OpenAPI V3.1 , which gives an opportunity to clarify the examples.

[chris-little]

EDR API SWG 126 2025-01-09 agreed to close when PR#590 merged.