Merge pull request #284 from opengeospatial/Multi-dimension-extent

New Requirements Class for uniform multi-dimensional data.

api_modules/extent-uad/envelope.yaml

@@ -0,0 +1,52 @@
+description: |-
+  The extent (envelope) of the coverage. In Common, currently only spatial and temporal
+  extents are specified. Coverages proposes to standardize how additional properties are defined, by specifying intervals and crs properties. `extent-additional-dimensions` or `extent-uniform-additional-dimensions` conformance class
+allOf:
+  - $ref: '../common-geodata/extent.yaml'
+  - type: object
+    properties:
+       - orderedAxes:
+            type: array
+            minItems: 1
+            items:
+               type: string
+               description: axis labels of all dimensions listed in CRS order. Spatial dimensions should be listed separately here.
+    additionalProperties:
+       description: |-
+         The domain intervals for any additional dimensions of the extent (envelope) beyond those described in temporal and spatial.
+       type: object
+       properties:
+         allOf:
+            - interval:
+              description: |-
+                One or more intervals that describe the extent for this dimension of the dataset.
+                The value `null` is supported and indicates an open interval.
+                In the Core only a single interval is supported. Extensions may support
+                multiple intervals. If multiple intervals are provided, the union of the
+                intervals describes the overall extent for the dimension.
+              type: array
+              minItems: 1
+              items:
+                description: |-
+                  Lower and upper bound values of the interval. The values
+                  are in the coordinate reference system specified in `crs`, `trs` or `vrs`.
+                type: array
+                minItems: 2
+                maxItems: 2
+                items:
+                  type: string
+                  nullable: true
+                example:
+                  - '2011-11-11T12:22:11Z'
+                  - 32.5
+                  - null
+            - oneOf:
+              - crs:
+                  type: string
+                  description: generic coordinate reference system suitable for any type of dimensions
+              - trs:
+                  type: string
+                  description: temporal coordinate reference system (e.g. as defined by Features for 'temporal')
+              - vrs:
+                  type: string
+                  description: vertical coordinate reference system (e.g. as defined in EDR for 'vertical')

api_modules/extent-uad/extent-uad.json

@@ -0,0 +1,105 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Extent with Uniform Additional Dimensions Schema",
+    "description": "Extends the Extent object to support domain-specific uniform geometries.",
+    "type": "object",
+    "properties": {
+        "spatial": {
+            "description": "The spatial extend of the resources in the collection.",
+            "type": "object",
+            "properties": {
+                "bbox": {
+                    "description": "One or more bounding boxes or cubes which describe the spatial extent of the collection. If multiple areas are provided, the union of the bounding boxes describes the spatial extent.",
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "type": "array",
+                        "oneOf": [
+                            {
+                                "minItems": 4,
+                                "maxItems": 4
+                            },
+                            {
+                                "minItems": 6,
+                                "maxItems": 6
+                            }
+                        ],
+                        "items": {
+                            "type": "number"
+                            }
+                        }
+                    }
+                },  
+                "crs": {
+                    "description": "Coordinate reference system of the coordinates in the spatial extent (property `spatial`).",
+                    "type": "string",
+                    "enum": [
+                        "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
+                        "http://www.opengis.net/def/crs/OGC/0/CRS84h"
+                        ],
+                    "default": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+                    }
+                },
+        "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"
+                    }
+                }
+            },
+        "uniform-md": {
+            "description": " extends the Extent object to support domain-specific geometries defined by axis names and the occupied interval alone each access.",
+            "type": "object",
+            "properties": {
+                "orderedAxes": {
+                   "description": "axis labels of all dimensions listed in CRS order. Spatial dimensions should be listed separately here.",
+                   "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "type": "string"
+                        }
+                    },
+                "intervals": {
+                    "description": "One interval for each axis. An interval describes the extent of the dataset along that axis.",
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "description": "Lower and upper bound values of the interval.", 
+                        "type": "array",
+                        "minItems": 2,
+                        "maxItems": 2,
+                        "items": {
+                            "type": "string",
+                            "nullable": "true"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }

api_modules/extent-uad/extent-uad.yaml

@@ -0,0 +1,85 @@
+title: Extent with Uniform Additional Dimensions Schema
+description: Extends the Extent object to support domain-specific uniform geometries.
+type: object
+required:
+  - spatial
+  - temporal
+properties:
+  spatial:
+    description: The spatial extend of the resources in the collection.
+    type: object
+    properties:
+      bbox:
+        description: One or more bounding boxes or cubes which describe the spatial
+          extent of the collection. If multiple areas are provided, the union of the
+          bounding boxes describes the spatial extent.
+        type: array
+        minItems: 1
+        items:
+          type: array
+          oneOf:
+          - minItems: 4
+            maxItems: 4
+          - minItems: 6
+            maxItems: 6
+          items:
+            type: number
+    crs:
+      description: Coordinate reference system of the coordinates in the spatial extent
+        (property `spatial`).
+      type: string
+      enum:
+      - http://www.opengis.net/def/crs/OGC/1.3/CRS84
+      - http://www.opengis.net/def/crs/OGC/0/CRS84h
+      default: http://www.opengis.net/def/crs/OGC/1.3/CRS84
+  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
+  uniform-md:
+    description: " extends the Extent object to support domain-specific geometries
+      defined by axis names and the occupied interval alone each access."
+    type: object
+    properties:
+      orderedAxes:
+        description: axis labels of all dimensions listed in CRS order. Spatial dimensions
+          should be listed separately here.
+        type: array
+        minItems: 1
+        items:
+          type: string
+      intervals:
+        description: One interval for each axis. An interval describes the extent
+          of the dataset along that axis.
+        type: array
+        minItems: 1
+        items:
+          description: Lower and upper bound values of the interval.
+          type: array
+          minItems: 2
+          maxItems: 2
+          items:
+            type: string
+            nullable: 'true'

api_modules/extent-uad/requirements/REQ_extent-uad-definition.adoc

@@ -0,0 +1,6 @@
+[[req_extent-uad-definition]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/common/extent-uad-definition* 
+^|A |The content of an `Extent with Uniform Additional Dimensions` (Extent-uad) resource SHALL be based upon the OpenAPI segment  link:https://github.com/opengeospatial/ogcapi-common/tree/master/api_modules/extent-uad/extent-uad.json[extent-uad.oas].
+|===

api_modules/extent-uad/requirements_module_extent-uad.adoc

@@ -0,0 +1,47 @@
+[[rm_extent-uniform-additional-dimensions]]
+[cols="1,4",width="90%"]
+|===
+2+|*Requirements Module*
+2+|http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/extent-uad
+|Target type |Web API Resource
+|Dependencies |<<rc_collections-section,Collections>> Requirements Class
+|===
+
+The `Extent with Uniform Additional Dimensions` (Extent-uad) element extends the <<collection-extent-section,Extent>> element defined in the <<rc-collections-section,http://www.opengis.net/spec/ogcapi-common-2/1.0/req/collections>> Requirements Class to support domain-specific geometries. 
+
+The `Extent-uad` parameter is defined as follows:
+
+include::requirements/REQ_extent-uad-definition.adoc[]
+
+`Extent-uad` extends the `Extent` element with a new <<uniform-uad-schema,`uniform-md`>> property. 
+
+Since the `Extent-uad` element extends the `Extent` element, all operations applied against the `Extent` element will have identical behavior when applied against `Extend-uad`.
+
+[[uniform-uad-schema]]
+.Uniform-uad Property
+[source, YAML]
+----
+  uniform-md:
+    description: "extends the Extent object to support domain-specific geometries defined by axis names and the occupied interval alone each access."
+    type: object
+    properties:
+      orderedAxes:
+        description: axis labels of all dimensions listed in CRS order. Spatial dimensions should be listed separately here.
+        type: array
+        minItems: 1
+        items:
+          type: string
+      intervals:
+        description: One interval for each axis. An interval describes the extent of the dataset along that axis.
+        type: array
+        minItems: 1
+        items:
+          description: Lower and upper bound values of the interval.
+          type: array
+          minItems: 2
+          maxItems: 2
+          items:
+            type: string
+            nullable: 'true'
+----
+

api_modules/subset/requirements/REQ_subset-definition.adoc

@@ -2,31 +2,27 @@
 [width="90%",cols="2,6a"]
 |===
 ^|*Requirement {counter:req-id}* |*/req/collections/rc-subset-definition*
-^|A |The `subset` parameter SHALL have the following characteristics (using an Extended Backus Naur Form (EBNF) fragment):
+^|A |The `subset` parameter SHALL have the following characteristics (using an Augmented Backus Naur Form (ABNF) fragment):
 
-[source,EBNF]
+[source,ABNF]
 ----
-  SubsetSpec:        "subset"=axisName(intervalOrPoint)
-  axisName:          {text}
-  intervalOrPoint:   interval \| point
-  interval:          low : high
-  low:               point \| *
-  high:              point \| *
-  point:             {number} \| "{text}"
+  SubsetSpec:       "subset"=axisName(intervalOrPoint)
+  axisName:         {text}
+  intervalOrPoint:  interval \| point
+  interval:         low : high
+  low:              point \| *
+  high:             point \| *
+  point:            {number} \| "{text}"
 
   Where:
      \" = double quote = ASCII code 0x42,
      {number} is an integer or floating-point number, and
      {text} is some general ASCII text (such as a time and date notation in ISO 8601).
 ----
-
 ^|B |The axis name SHALL correspond to one of the axis of the Coordinate Reference System (CRS) of the target resource or else return a 400 status code.
 ^|C |If the intervalOrPoint values fall entirely outside the range of valid values defined for the identified axis, a 204 status code SHALL be returned
 ^|D |For a CRS where an axis can wrap around, such as subsetting across the dateline (anti-meridian) in a geographic CRS, a `low` value greater than `high` SHALL
 be supported to indicate an extent crossing that wrapping point.
 |===
 
 NOTE: When the intervalOrPoint values fall partially outside of the range of valid values defined by the CRS for the identified axis, the service is expected to return the non-empty portion of the resource resulting from the subset.
-For subsetting on the range set, and for coverage media types with no geo-referencing mechanisms (e.g. PNG), NO_DATA values or transparency should be used.
-If a georeferencing mechanism is available within the negotiated media type, the service could decide whether to use NO_DATA values
-or simply return the properly geo-referenced values within the domain set.

api_modules/subset/requirements/REQ_subset-success.adoc → api_modules/subset/requirements/REQ_subset-response.adoc

@@ -1,7 +1,7 @@
-[[req_collection_rc-subset-success]]
+[[req_collection_rc-subset-response]]
 [width="90%",cols="2,6a"]
 |===
-^|*Requirement {counter:req-id}* |*/req/collection/subset-success*
+^|*Requirement {counter:req-id}* |*/req/collection/subset-response*
 ^|A |Only that part of the resource that falls within the bounds of the subset expression SHALL be returned.
 ^|B |If an lower limit of the subset expression is populated with an asterix "*" THEN the mainumum extent of the resource along that axis SHALL be selected.
 ^|C |If an upper limit of the subset expression is populated with an asterix "*" THEN the maximum extent of the resource along that axis SHALL be selected.

api_modules/subset/requirements_module_subset.adoc

@@ -12,15 +12,7 @@ The `subset` parameter is defined as follows:
 
 include::requirements/REQ_subset-definition.adoc[]
 
-The following permission is granted to facilitate slicing data sparsely populated across a dimension, such as Earth Observation imagery:
-
-include::recommendations/PER_subset-slice-sparse-dimensions.adoc[]
-
 While the processing of the `subset` parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.
 
-include::requirements/REQ_subset-success.adoc[]
-
-=== Subsetting Examples
-
-include::examples/examples_subsetting.adoc[]
+include::requirements/REQ_subset-response.adoc[]
 

collections/clause_6_conventions.adoc

@@ -47,12 +47,14 @@ Additional information on the use of link relationships is provided in the link:
 
 === Geometry
 
-==== Spatial Geometry
+[[spatial-geometry-section]]
+==== Geospatial Geometry
 
-Standardized concepts for spatial characteristics are needed in order to share geographic information between applications. Concepts for shape (geometry) are key. These concepts are standardized in <<iso19107,_ISO 19107_>>.
+Standardized concepts for geospatial characteristics are needed in order to share geographic information between applications. Concepts for shape (geometry) are key. These concepts are standardized in <<iso19107,_ISO 19107_>>.
 
-The spatial geometry used in the OGC API - Common Standards is documented in the <<gmlsf,GML Simple Features Profile >> Standard. This Profile defines a subset of the ISO 19107 geometry which is aligned with the OGC <<sfsql,Simple Features for SQL>> Standard. That geometry includes: Point, Curve (LineString), Surface (Polygon), MultiPoint, MultiCurve, and MultiSurface.
+The geospatial geometry used in the OGC API - Common Standards is documented in the <<gmlsf,GML Simple Features Profile >> Standard. This Profile defines a subset of the ISO 19107 geometry which is aligned with the OGC <<sfsql,Simple Features for SQL>> Standard. That geometry includes: Point, Curve (LineString), Surface (Polygon), MultiPoint, MultiCurve, and MultiSurface.
 
+[[temporal-geometry-section]]
 ==== Temporal Geometry
 
 Standardized concepts for temporal characteristics are also needed in order to share date and time information between applications. OGC API Common adopts the Gregorian calendar and a 24 hour time keeping system for its temporal geometry. All representations of that geometry which are discussed in this document conform to <<rfc3339,RFC 3339>>.