latest changes from dev

radiantearth · Apr 6, 2018 · f1971c4 · f1971c4
2 parents 6478ae4 + fc84a35
commit f1971c4
Show file tree

Hide file tree

Showing 14 changed files with 681 additions and 102 deletions.
diff --git a/README.md b/README.md
@@ -39,6 +39,9 @@ other tools.
 **[api-spec/](api-spec/)** defines a dynamic API, specified as a [yaml](api-spec/spec.yaml) file in [OpenAPI](http://openapis.org) 
 2.0 (swagger). 
 
+**Extensions:** The *[extensions/](extensions/)* folder is where profiles and extensions live. Profiles are recommendations for
+adding fields for specific domains (like Earth Observation). Extensions bring additional functionality to the core specs.
+
 **Additional documents** include the current [roadmap](roadmap.md) and a complementary [how to help](how-to-help.md)
 document, a [list of implementations](implementations.md), 
 and a discussion of the collaboration [principles](principles.md) and specification approach.

diff --git a/api-spec/STAC-fragment.yaml b/api-spec/STAC-fragment.yaml
@@ -125,17 +125,18 @@ components:
       name: time
       in: query
       description: >-
-        A time range search that accepts a JSON search object.
-        
+        Either a date-time or a period string that adheres to RFC3339. 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"
         Only features that have a temporal property that intersects the value of
         `time` 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 the
-        extent or all relevant temporal properties.
+        server whether only a single temporal property is used to determine
+        the extent or all relevant temporal properties.
       required: false
       schema:
-        $ref: '#/components/schemas/timeRange'
+        type: string
+      style: form
       explode: false
   schemas:
     searchBody:
@@ -151,9 +152,7 @@ components:
         - 39
         - -105
         - 41
-        time:
-          gt: "2018-03-15T00:00:00.000Z"
-          lt: "2018-06-01T00:00:00.000Z"
+        time: "2018-03-15T00:00:00.000Z"
     bboxFilter:
       type: object
       description: Only return items that intersect the provided bounding box.
@@ -165,7 +164,7 @@ components:
       type: object
       properties:
         time:
-          $ref: '#/components/schemas/timeRange'
+          $ref: '#/components/parameters/time'
     intersectsFilter:
       type: object
       description: Only returns items that intersect with the provided polygon.
@@ -221,17 +220,6 @@ components:
       description: >-
         A single date-time string that adheres to RFC3339, for example
         1985-04-12T23:20:50.52Z
-    timeRange:
-      type: object
-      properties:
-        gt:
-          $ref: '#/components/schemas/time'
-        lt:
-          $ref: '#/components/schemas/time'
-        gte:
-          $ref: '#/components/schemas/time'
-        lte:
-          $ref: '#/components/schemas/time'
     itemCollection:
       type: object
       required:

diff --git a/api-spec/STAC-standalone.yaml b/api-spec/STAC-standalone.yaml
@@ -150,27 +150,19 @@ components:
     time:
       name: time
       in: query
-      description: >-
-        A time range search that accepts a JSON search object.
-        
+      description: |
+        Either a date-time or a period string that adheres to RFC3339. 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"
         Only features that have a temporal property that intersects the value of
         `time` 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 the
-        extent or all relevant temporal properties.
+        server whether only a single temporal property is used to determine
+        the extent or all relevant temporal properties.
       required: false
       schema:
-        type: object
-        properties:
-          gt:
-            $ref: '#/components/schemas/time'
-          lt:
-            $ref: '#/components/schemas/time'
-          gte:
-            $ref: '#/components/schemas/time'
-          lte:
-            $ref: '#/components/schemas/time'
+        type: string
+      style: form
       explode: false
     collectionId:
       name: collectionId

diff --git a/api-spec/WFS3core+STAC.yaml b/api-spec/WFS3core+STAC.yaml
@@ -308,26 +308,18 @@ components:
       name: time
       in: query
       description: >-
-        A time range search that accepts a JSON search object.
-        
+        Either a date-time or a period string that adheres to RFC3339. 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"
         Only features that have a temporal property that intersects the value of
         `time` 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 the
-        extent or all relevant temporal properties.
+        server whether only a single temporal property is used to determine
+        the extent or all relevant temporal properties.
       required: false
       schema:
-        type: object
-        properties:
-          gt:
-            $ref: '#/components/schemas/time'
-          lt:
-            $ref: '#/components/schemas/time'
-          gte:
-            $ref: '#/components/schemas/time'
-          lte:
-            $ref: '#/components/schemas/time'
+        type: string
+      style: form
       explode: false
     collectionId:
       name: collectionId

diff --git a/api-spec/filters.md b/api-spec/filters.md
@@ -6,7 +6,7 @@ and are required to be supported.
 
 The filters are designed to be simple as possible for a client to construct. To match the default JSON responses the 
 encoding of filters is done by default in JSON. This allows clients to support filtering without additional tools. The 
-search enpoint will accept application/json format queries, and GET on the collection will support URL encoded JSON. POST 
+search endpoint will accept application/json format queries, and GET on the collection will support URL encoded JSON. POST 
 search the is recommended way to filter results to avoid the URL encoding issues that can happen with GET. 
 
 Searching using POST will accept a JSON object where the top level keys are specifying which type of filter
@@ -20,33 +20,60 @@ This query will perform an intersects operation on the geometry values of the it
 objects may provide a bbox property in addition to geometry, but it should not be used for the bbox filter since
 it is an optional field in GeoJSON.
 
-example
+###### examples: ######
+POST:
 ```
 {
   "bbox": [-180,-90,180,90]
 }
 ```
 
-The temporal query will be based on [RFC 3339](https://tools.ietf.org/html/rfc3339) and should support time ranges as well as equality. To support range
-queries, we are using a simple JSON based language. Ranges will be specified as an object with keys indicating the comparison to use.
+GET:
+```
+?bbox=[-180,-90,180,90]
+```
+
+The temporal query will be based on [RFC 3339](https://tools.ietf.org/html/rfc3339) and should support time ranges as well as equality. It will compare against the datetime property of the STAC Item.
+
+###### To find items with an exact date ######
+
+POST:
+```
+{
+  "time": "2007-03-01T13:00:00Z"
+}
+```
 
-Equality is specified as `{"time": "2018-03-20T16:11:44.353Z"}`  
-Before is `{"time":{"lt":"2018-03-20T16:11:44.353Z"}}`  
-After is `{"time":{"gt":"2018-03-20T16:11:44.353Z"}}`  
-Before with Equality is `{"time":{"lte":"2018-03-20T16:11:44.353Z"}}`  
-After with Equality is `{"time":{"gte":"2018-03-20T16:11:44.353Z"}}`
+GET:
+```
+?time=2007-03-01T13:00:00Z
+```
 
-These queries can be combined to specify a search range:
+###### To specify a time range, use the interval syntax: ######
 
+POST:
 ```
 {
-  "time": {
-    "gt":"2018-03-15T00:00:00.000Z",
-    "lt":"2018-06-01T00:00:00.000Z",
-  }
-} 
+  "time": "2007-03-01T13:00:00Z/2008-05-11T15:30:00Z"
+}
 ```
 
+GET: 
+```
+?time=2007-03-01T13:00:00Z/2008-05-11T15:30:00Z
+```
+
+###### Specify intervals using durations:  ######
+
+`2007-03-01T13:00:00Z/P1Y2M10DT2H30M`
+
+If time is a period with out a start or end date, the end date is assigned to now:
+
+`P1Y2M10DT2H30M` is the same as `"P1Y2M10DT2H30M/" + new Date().toISOString()`
+
+
+
+
 Filter Extensions
 -----------------
 
@@ -124,10 +151,6 @@ Some additional extensions that have been discussed:
 CQL support for generic queries:  
 `{"CQL": "CQL Select String"}`
 
-Time intervals:  
-`{"time": "P1Y"}`  Assume Duration/now if no time specified?  
-`{"time": "2018/P1M"}` Any time in january of 2018  
-
 
 Adding filters to search
 ------------------------

diff --git a/api-spec/wfs-stac.md b/api-spec/wfs-stac.md
@@ -27,9 +27,48 @@ STAC endpoint.
 
 ### WFS Structure
 
-TODO: Give an overview of the main WFS endpoints
+A Web Feature Service is a standard API that represents collections of geospatial data. 
+
+```
+GET /collections
+```
+
+Lists the collections of data on the server that can be queried ([7.11](https://rawgit.com/opengeospatial/WFS_FES/master/docs/17-069.html#_feature_collections_metadata)), 
+and each describes basic information about the geospatial data collection, like its name and description, as well as the 
+spatial and temporal extents of all the data contained. A STAC search extension would only query those collections which
+have data that validates as STAC `Items` - with a datetime field and references to assets. But a STAC can live alongside
+other WFS collections, like an organization might choose to have their building and road data in WFS collections, alongside
+their STAC-compatible imagery data.
+
+```
+GET /collections/{name}/items?bbox=160.6,-55.95,-170,-25.89
+```
+
+Requests all the data in the collection that is in New Zealand. The filtering is made to be compatible with the STAC API, 
+and the two specs seek to share the general query and filtering patterns. The key difference is that a STAC search endpoint
+will do cross collection search. A typical WFS will have multiple collections, and each will just offer search for its particular
+collection.
+
 
 ### Strongly Typed STAC data
 
-TODO: explain the advantages of using WFS to provide schema information at a collection level, for stronger typing
-of data. Plus transactions.
+The scenario that using a WFS with a STAC search endpoint that makes the most sense is when a data provider wants to provide more
+insight in to heterogenous data that is exposed on a STAC search. For example they might have imagery data from different satellite providers
+and even some drone data. These will all have different fields. A single STAC endpoint can be used to expose them all. But it can be quite
+useful to let users inspect a particular data type. That area of the `/collections/{name}` hierarchy can be used to expose additional
+metadata and validation schemas that give more insight in to that data, as well as a place to query just that data.
+
+In general it is recommended to provide as much information about different types of data as possible, so using WFS is recommended. But
+the standalone option is there for those who just want to expose their data as quickly and easily as possible. Note a WFS can 
+provide heterogenous data from any of its collections endpoints, but the STAC API recommendation is to use one collection per 
+logical data type.
+
+### Potential Transaction Extension
+
+The other benefit of individual collection endpoints is that it gives a logical location for simple RESTful transactions
+
+```
+POST /collections/landsat/items/
+```
+
+There have been a couple implementations that have done transactions, and soon will contribute an extension.
diff --git a/extensions/examples/L1T-collection.json b/extensions/examples/L1T-collection.json
@@ -0,0 +1,93 @@
+
+{
+
+
+    "properties": {
+        "collection_name": "L1T",
+        "collection_description": "Landat 8 imagery that is radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.",
+        "provider": "USGS",
+        "license": "PDDL-1.0",
+        "eo:gsd" : 30,
+        "eo:platform": "landsat-8",
+        "eo:instrument": "OLI_TIRS",
+    },
+
+    "eo:bands": {
+      "1": {
+        "common_name": "coastal",
+        "gsd": 30.0,
+        "accuracy": null,
+        "wavelength": 0.44,
+        "fwhm": 0.02
+      },
+      "2": {
+        "common_name": "blue",
+        "gsd": 30.0,
+        "accuracy": null,
+        "wavelength": 0.48,
+        "fwhm": 0.06
+      },
+      "3": {
+        "common_name": "green",
+        "gsd": 30.0,
+        "accuracy": null,
+        "wavelength": 0.56,
+        "fwhm": 0.06
+      },
+      "4": {
+        "common_name": "red",
+        "gsd": 30.0,
+        "accuracy": null,
+        "wavelength": 0.65,
+        "fwhm": 0.04
+      },
+      "5": {
+        "common_name": "nir",
+        "gsd": 30.0,
+        "accuracy": null,
+        "wavelength": 0.86,
+        "fwhm": 0.03
+      },
+      "6": {
+        "common_name": "swir16",
+        "gsd": 30.0,
+        "accuracy": null,
+        "wavelength": 1.6,
+        "fwhm": 0.08
+      },
+      "7": {
+        "common_name": "swir22",
+        "gsd": 30.0,
+        "accuracy": null,
+        "wavelength": 2.2,
+        "fwhm": 0.2
+      },
+      "8": {
+        "common_name": "pan",
+        "gsd": 15.0,
+        "accuracy": null,
+        "wavelength": 0.59,
+        "fwhm": 0.18
+      },
+      "9": {
+        "common_name": "cirrus",
+        "gsd": 30.0,
+        "accuracy": null,
+        "wavelength": 1.37,
+        "fwhm": 0.02
+      },
+      "10": {
+        "common_name": "lwir11",
+        "gsd": 100.0,
+        "accuracy": null,
+        "wavelength": 10.9,
+        "fwhm": 0.8
+      },
+      "11": {
+        "common_name": "lwir12",
+        "gsd": 100.0,
+        "accuracy": null,
+        "wavelength": 12.0,
+        "fwhm": 1.0
+      }
+    }
diff --git a/extensions/examples/README.md b/extensions/examples/README.md
@@ -0,0 +1,8 @@
+## Landsat Example with EO profile and Collection extension
+
+The files in this directory contain a full example of Landsat data. It follows the Earth Observation
+Profile, and uses the 'Collection' extension to be less duplicative of information
+
+* [landsat8-sample](landsat8-sample.json) is a core `Item` including the link to its collection information.
+* [L1T-collection](L1T-collection.json) shows the collection information for Landsat 8 L1T collection
+* [landsat8-merged](landsat8-merged.json) is a fully expanded record, showing the result of merging of the collection data and the core `Item`.