Merge pull request #194 from opengeospatial/issue-155

resolves #155 /Issues with temporal data, including (open) ranges / periods)

core/openapi/parameters/time.yaml → core/openapi/parameters/datetime.yaml

@@ -1,13 +1,17 @@
-name: time
+name: datetime
 in: query
 description: >-
-  Either a date-time or a period string that adheres to RFC3339. Examples:
+  Either a date-time or an interval, open or closed. Date and time expressions
+  adhere to RFC 3339. Open intervals are expressed using double-dots.
+
+  Examples:
 
   * A date-time: "2018-02-12T23:20:50Z"
-  * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
+  * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
+  * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
 
   Only features that have a temporal property that intersects the value of
-  `time` are selected.
+  `datetime` are selected.
 
   If a feature has multiple temporal properties, it is the decision of the
   server whether only a single temporal property is used to determine

core/openapi/schemas/featureCollectionGeoJSON.yaml

@@ -17,7 +17,7 @@ properties:
       $ref: link.yaml
   timeStamp:
     type: string
-    format: dateTime
+    format: date-time
   numberMatched:
     type: integer
     minimum: 0

core/openapi/schemas/timeStamp.yaml

@@ -1,4 +1,4 @@
 description: This property indicates the time and date when the response was generated.
 type: string
-format: dateTime
+format: date-time
 example: '2017-08-17T08:05:32Z'

core/standard/annex_ats.adoc

@@ -177,11 +177,13 @@ The bounding box is provided as four or six numbers, depending on whether the co
 The coordinate reference system of the values SHALL be interpreted as WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate reference system is specified in a parameter bbox-crs. +
 Tests: A.4.4.12 +
 | *Requirement 22:* Feature Collection Operation Time Parameter +
-Each feature collection operation SHALL support a parameter time with the following characteristics (using an OpenAPI Specification 3.0 fragment): +
+Each feature collection operation SHALL support a parameter datetime with the following characteristics (using an OpenAPI Specification 3.0 fragment): +
 Tests: A.4.4.13 +
 | *Requirement 23:* Feature Collection Operation Time Parameter Response +
-Only features that have a temporal geometry that intersects the timestamp or time period SHALL be part of the result set, if the time parameter is provided. +
-The temporal information is either a date-time or a period string that adheres to RFC3339. +
+Only features that have a temporal geometry that intersects the timestamp or time interval SHALL be part of the result set, if the datetime parameter is provided. +
+The temporal information is either a date-time or an interval. +
+The syntax of date-time is specified by RFC 3339, 5.6. +
+Open ranges in time intervals at the start or end are supported using a double-dot (`..`). +
 If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. +
 Tests: A.4.4.13 +
 | *Requirement 24:* Feature Collection Response +
@@ -200,7 +202,7 @@ Tests: A.4.4.10 +
 If a property timeStamp is included in the response, the value SHALL be set to the time stamp when the response was generated. +
 Tests: A.4.4.10 +
 | *Requirement 28:* Feature Collection Response numberMatched +
-If a property numberMatched is included in the response, the value SHALL be identical to the number of features in the feature collections that match the selection parameters like bbox, time or additional filter parameters. +
+If a property numberMatched is included in the response, the value SHALL be identical to the number of features in the feature collections that match the selection parameters like bbox, datetime or additional filter parameters. +
 A server MAY omit this information in a response, if the information about the number of matching features is not known or difficult to compute. +
 Tests: A.4.4.10 +
 | *Requirement 29:* Feature Collection Response numberReturned +
@@ -731,10 +733,10 @@ Validate the proper handling of the bbox parameter.
 ====== d) References:
 Requirements 20 and 21
 
-===== A.4.4.13 Time Parameter
+===== A.4.4.13 Date-Time Parameter
 
 ====== a) Test Purpose:
-Validate the proper handling of the time parameter.
+Validate the proper handling of the datetime parameter.
 
 ====== b) Pre-conditions:
 
@@ -743,12 +745,14 @@ successfully.
 
 ====== c) Test Method:
 
-. Verify that the OpenAPI document correctly describes the time parameter for the Get Features operation.
+. Verify that the OpenAPI document correctly describes the datetime parameter for the Get Features operation.
 
-. Repeat Test A.4.4.9 using different values for the time parameter.
+. Repeat Test A.4.4.9 using different values for the datetime parameter.
 
 . For each execution of Test A.4.4.9, repeat Test A.4.4.10 to validate the results.
 
+. Use time intervals in the tests to verify the correct behavior for time intervals. In particular check that the start and end date-time are part of the interval (i.e. everything that is `>=` than the start and `<=` the end date-time is selected). Use also fractions of seconds in the tests.
+
 ====== d) References:
 Requirements 22 and 23
 

core/standard/clause_7_core.adoc

@@ -56,8 +56,8 @@ Accessing a `Collection` using HTTP GET returns a `CollectionResponse`. This
 response basically consists of features in the collection. The features included
 in the response are determined by the server based on parameters of the request.
 
-A `bbox` or `time` parameter may be used to select only a subset of the features in
-the collection (the features that are located in the bounding box or time period).
+A `bbox` or `datetime` parameter may be used to select only a subset of the features in
+the collection (the features that are located in the bounding box or time interval).
 
 The `limit` parameter may be used to request only a subset of the
 selected features and to indicate that the client wants to page through
@@ -652,57 +652,57 @@ A template for the definition of the parameter in YAML according to
 OpenAPI 3.0 is available at
 link:https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/parameters/bbox.yaml[bbox.yaml].
 
-==== Parameter time
+==== Parameter datetime
 
 include::requirements/core/REQ_fc-time-definition.adoc[]
 
 include::requirements/core/REQ_fc-time-response.adoc[]
 
-"Intersects" means that the time (instant or period) specified in the parameter
-`time` includes a timestamp that is part of the temporal geometry of the feature
-(again, a time instant or period). For time periods this includes the start
+"Intersects" means that the time (instant or interval) specified in the parameter
+`datetime` includes a timestamp that is part of the temporal geometry of the feature
+(again, a time instant or interval). For time intervals this includes the start
 and end time.
 
 .A date-time
 =================
-February 12, 2018, 23:20:52 GMT:
+February 12, 2018, 23:20:52 UTC:
 
-`time=2018-02-12T23%3A20%3A52Z`
+`datetime=2018-02-12T23%3A20%3A52Z`
 =================
 
 For features with a temporal property that is a timestamp (like `lastUpdate`
 in the building features), a date-time value would match all features where
 the temporal property is identical.
 
-For features with a temporal property that is a date or a time period,
+For features with a temporal property that is a date or a time interval,
 a date-time value would match all features where the timestamp is on that
-day or within the time period.
+day or within the time interval.
 
-.A period using a start and end time
+.Intervals
 =================
-February 12, 2018, 00:00:00 GMT to March 18, 2018, 12:31:12 GMT:
+February 12, 2018, 00:00:00 UTC to March 18, 2018, 12:31:12 UTC:
 
-`time=2018-02-12T00%3A00%3A00Z%2F2018-03-18T12%3A31%3A12Z`
-=================
+`datetime=2018-02-12T00%3A00%3A00Z%2F2018-03-18T12%3A31%3A12Z`
 
-.A period using start time and a duration
-=================
-A duration of 1 month, 6 days, 12 hours, 31 minutes and 12 seconds from
-February 12, 2018, 00:00:00 GMT:
+February 12, 2018, 00:00:00 UTC or later:
+
+`datetime=2018-02-12T00%3A00%3A00Z%2F..`
+
+March 18, 2018, 12:31:12 UTC or earlier:
 
-`time=2018-02-12T00%3A00%3A00Z%2FP1M6DT12H31M12S`
+`datetime=..%2F2018-03-18T12%3A31%3A12Z`
 =================
 
 For features with a temporal property that is a timestamp (like `lastUpdate`
-in the building features), a time period would match all features where
-the temporal property is within the period.
+in the building features), a time interval would match all features where
+the temporal property is within the interval.
 
-For features with a temporal property that is a date or a time period,
-a time period would match all features where the values overlap.
+For features with a temporal property that is a date or a time interval,
+a time interval would match all features where the values overlap.
 
 A template for the definition of the parameter in YAML according to
 OpenAPI 3.0 is available at
-link:https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/parameters/time.yaml[time.yaml].
+link:https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/parameters/datetime.yaml[datetime.yaml].
 
 ==== Parameters for filtering on feature properties
 
@@ -882,7 +882,7 @@ A `400` will be returned in the following situations:
 * If query parameter `limit` is not an integer or not between minimum and maximum;
 * if query parameter `bbox` does not have 4 (or 6) numbers or they do not form
 a bounding box;
-* if parameter `time` is not a valid time stamp or time period.
+* if parameter `datetime` is not a valid time stamp or time interval.
 
 
 === Feature

core/standard/requirements/core/REQ_fc-numberMatched.adoc

@@ -4,7 +4,7 @@
 
 If a property `numberMatched` is included in the response, the value SHALL
 be identical to the number of features in the feature collections that match
-the selection parameters like `bbox`, `time` or additional filter parameters.
+the selection parameters like `bbox`, `datetime` or additional filter parameters.
 
 A server MAY omit this information in a response, if the information about the
 number of matching features is not known or difficult to compute.

core/standard/requirements/core/REQ_fc-time-definition.adoc

@@ -2,12 +2,12 @@
 |===
 |*Requirement {counter:req-id}* |/req/core/fc-time-definition +
 
-Each feature collection operation SHALL support a parameter `time`
+Each feature collection operation SHALL support a parameter `datetime`
 with the following characteristics (using an OpenAPI Specification 3.0 fragment):
 
 [source,YAML]
 ----
-name: time
+name: datetime
 in: query
 required: false
 schema:

core/standard/requirements/core/REQ_fc-time-response.adoc

@@ -2,11 +2,27 @@
 |===
 |*Requirement {counter:req-id}* |/req/core/fc-time-response +
 
-Only features that have a temporal geometry that intersects the timestamp or
-time period SHALL be part of the result set, if the `time` parameter is provided.
+Only features that have a temporal geometry that intersects the temporal
+information in the `datetime` parameter SHALL be part of the result set,
+if the parameter is provided.
 
-The temporal information is either a date-time or a period string that
-adheres to RFC 3339.
+The temporal information is either a date-time or an interval.
+The parameter value SHALL conform to the following syntax (using
+link:https://tools.ietf.org/html/rfc2234[ABNF]):
+
+```
+interval-closed     = date-time "/" date-time
+interval-open-start = "../" date-time
+interval-open-end   = date-time "/.."
+interval            = interval-closed / interval-open-start / interval-open-end
+datetime            = date-time / interval
+```
+
+The syntax of `date-time` is specified by
+link:https://tools.ietf.org/html/rfc3339#section-5.6[RFC 3339, 5.6].
+
+Open ranges in time intervals at the start or end are supported using a
+double-dot (`..`).
 
 If a feature has multiple temporal properties, it is the decision of the
 server whether only a single temporal property is used to determine

guide/conformance_checklist.md

@@ -72,7 +72,7 @@ Derived from the [WFS 3.0, Part 1, version 3.0.0-draft.1](https://cdn.rawgit.com
     * [ ] "limit" parameter includes (changeable) "default"
     * [ ] "limit" parameter includes (changeable) "maximum"
   * [ ] "bbox" query parameter.  Only features intersecting this rectangle are returned.
-  * [ ] "time" query parameter.  Only features intersecting this time stamp or period are returned.
+  * [ ] "datetime" query parameter.  Only features intersecting this time stamp or interval are returned.
   * [ ] (recommended) For simple int/string properties of features include a querystring parameter with the property name to filter on.  For strings, wildcard matches may be useful in addition to simple equality.
 * [ ] Response includes links:
   * [ ] rel "self"

guide/section_11_conformance_checklists.adoc

@@ -74,7 +74,7 @@ Derived from the [WFS 3.0, Part 1, version 3.0.0-draft.1](https://rawcdn.githack
     * [ ] "limit" parameter includes (changeable) "default"
     * [ ] "limit" parameter includes (changeable) "maximum"
   * [ ] "bbox" query parameter.  Only features intersecting this rectangle are returned.
-  * [ ] "time" query parameter.  Only features intersecting this time stamp or period are returned.
+  * [ ] "datetime" query parameter.  Only features intersecting this time stamp or interval are returned.
   * [ ] (recommended) For simple int/string properties of features include a querystring parameter with the property name to filter on.  For strings, wildcard matches may be useful in addition to simple equality.
 * [ ] Response includes links:
   * [ ] rel "self"

openapi-buildings.yaml

@@ -131,7 +131,7 @@ paths:
       parameters:
       - $ref: '#/components/parameters/limit'
       - $ref: '#/components/parameters/bbox'
-      - $ref: '#/components/parameters/time'
+      - $ref: '#/components/parameters/datetime'
       - $ref: '#/components/parameters/function'
       responses:
         '200':
@@ -169,7 +169,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/bbox'
-        - $ref: '#/components/parameters/time'
+        - $ref: '#/components/parameters/datetime'
         - $ref: '#/components/parameters/function'
       responses:
         '200':
@@ -294,17 +294,21 @@ components:
           type: number
       style: form
       explode: false
-    time:
-      name: time
+    datetime:
+      name: datetime
       in: query
       description: >-
-        Either a date-time or a period string that adheres to RFC 3339. Examples:
+        Either a date-time or an interval, open or closed. Date and time expressions
+        adhere to RFC 3339. Open intervals are expressed using double-dots.
+
+        Examples:
 
         * A date-time: "2018-02-12T23:20:50Z"
-        * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
+        * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
+        * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
 
         Only features that have a temporal property that intersects the value of
-        `time` are selected.
+        `datetime` are selected.
 
         If a feature has multiple temporal properties, it is the decision of the
         server whether only a single temporal property is used to determine
@@ -583,7 +587,7 @@ components:
             $ref: '#/components/schemas/link'
         timeStamp:
           type: string
-          format: dateTime
+          format: date-time
         numberMatched:
           type: integer
           minimum: 0
@@ -655,7 +659,7 @@ components:
               minimum: 1
             lastUpdate:
               type: string
-              format: dateTime
+              format: date-time
 tags:
   - name: Capabilities
     description: >-

openapi.yaml

@@ -128,7 +128,7 @@ paths:
       - $ref: '#/components/parameters/collectionId'
       - $ref: '#/components/parameters/limit'
       - $ref: '#/components/parameters/bbox'
-      - $ref: '#/components/parameters/time'
+      - $ref: '#/components/parameters/datetime'
       responses:
         '200':
           description: >-
@@ -238,17 +238,21 @@ components:
           type: number
       style: form
       explode: false
-    time:
-      name: time
+    datetime:
+      name: datetime
       in: query
       description: >-
-        Either a date-time or a period string that adheres to RFC 3339. Examples:
+        Either a date-time or an interval, open or closed. Date and time expressions
+        adhere to RFC 3339. Open intervals are expressed using double-dots.
+
+        Examples:
 
         * A date-time: "2018-02-12T23:20:50Z"
-        * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
+        * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
+        * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
 
         Only features that have a temporal property that intersects the value of
-        `time` are selected.
+        `datetime` are selected.
 
         If a feature has multiple temporal properties, it is the decision of the
         server whether only a single temporal property is used to determine
@@ -517,7 +521,7 @@ components:
             $ref: '#/components/schemas/link'
         timeStamp:
           type: string
-          format: dateTime
+          format: date-time
         numberMatched:
           type: integer
           minimum: 0