Merge pull request #868 from radiantearth/dev

1.0.0-beta.2 release

Author: m-mohr

.circleci/config.yml

@@ -35,9 +35,34 @@ jobs:
       - run:
           name: validate
           command: npm run check-markdown
+  publish_schemas:
+    working_directory: ~/stac
+    docker:
+      - image: circleci/node:12
+    steps:
+      - checkout
+      - run:
+          name: install
+          command: npm install
+      - add_ssh_keys:
+          fingerprints:
+            - "9b:0a:88:ff:12:d1:29:9a:ff:bb:72:ab:7d:81:df:59"
+      - run:
+          name: publish
+          command: npm run publish-schemas -- $CIRCLE_TAG
 workflows:
   version: 2
-  test:
+  ci:
     jobs:
       - test_examples
-      - test_docs
+      - test_docs
+      - publish_schemas:
+          requires:
+            - test_examples
+          filters:
+            tags:
+              # All (future) tags
+              only: /.+/
+            branches:
+              # Only dev branch, not PRs
+              only: dev

.circleci/publish-schemas.js

@@ -0,0 +1,40 @@
+const klaw = require('klaw-sync');
+const path = require('path');
+const fs = require('fs');
+const ghpages = require('gh-pages');
+
+function filterFn (item) {
+	const basename = path.basename(item.path);
+	return basename === '.' || basename === 'node_modules' || basename[0] !== '.';
+}
+
+let args = process.argv.slice(2);
+let tag = 'dev';
+if (args.length && args[0].trim().length > 0) {
+	tag = args[0];
+}
+
+var folder = '.';
+var jsonSchemaFolderPattern = path.sep + 'json-schema' + path.sep;
+for (let file of klaw(folder, {filter: filterFn})) {
+	if (file.path.includes(jsonSchemaFolderPattern) && path.extname(file.path) === '.json') {
+		let source = file.path;
+		let target = 'schemas' + path.sep + tag + path.sep + path.relative(folder, file.path);
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.copyFileSync(source, target);
+		console.log(target);
+	}
+}
+
+ghpages.publish('schemas/' + tag, {
+	src: '**',
+	dest: tag,
+	message: 'Publish JSON Schemas [ci skip]',
+	user: {
+	  name: 'STAC CI',
+	  email: 'ci@stacspec.org'
+	}
+}, error => {
+	console.error(error ? error : 'Deployed to gh-pages');
+	process.exit(error ? 1 : 0);
+});

.gitignore

@@ -64,3 +64,6 @@ typings/
 # IntelliJ IDEA files
 .idea/
 *.iml
+
+# Folder created when CI puhlishes JSON Schemas
+schemas/

CHANGELOG.md

@@ -6,6 +6,31 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Added
+
+### Changed
+
+### Removed
+
+### Fixed
+
+
+## [v1.0.0-beta.2] - 2020-07-08
+
+### Added
+- JSON-schema file in the Point Cloud extension.
+
+### Changed
+- Clarification on null geometries, making bbox not required if a null geometry is used.
+- Multiple extents (bounding boxes / intervals) are allowed per Collection
+
+### Removed
+- Validation instructions
+
+### Fixed
+- Fixed several JSON Schemas
+- Fixed examples
+
 ## [v1.0.0-beta.1] - 2020-05-29
 
 ### Removed
@@ -333,6 +358,7 @@ Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkam
 
 
 [Unreleased]: <https://github.com/radiantearth/stac-spec/compare/master...dev>
+[v1.0.0-beta.2]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-beta.1..v1.0.0-beta.2>
 [v1.0.0-beta.1]: <https://github.com/radiantearth/stac-spec/compare/v0.9.0...v1.0.0-beta.1>
 [v0.9.0]: <https://github.com/radiantearth/stac-spec/compare/v0.8.1...v0.9.0>
 [v0.8.1]: <https://github.com/radiantearth/stac-spec/compare/v0.8.0...v0.8.1>

CONTRIBUTING.md

@@ -37,6 +37,8 @@ system. Please use `check-markdown` locally, as described in the [next section](
 to ensure that the checks on the pull request succeed. If it does not then you can look at the
 mistakes online, which are the same as running `check-markdown` locally would surface.
 
+All pull requests that modify or create JSON schema files or examples should use [JSON formatter](https://jsonformatter.org/) to keep files consistent across the repo. 
+
 All pull requests additionally require a review of two STAC core team members. Releases are cut
 from dev to master (and require 3 approvals), see the [process](process.md) document for more details.
 

README.md

@@ -23,12 +23,13 @@ in a 'beta' state, with no major changes anticipated, so implementors can expect
 at this point we don't anticipate any major changes, but reserve the right to make them if we get feedback that something just doesn't 
 work. Which is to say the next couple months are a great time to implement STAC, as your changes will be head. After 1.0 our goal
 is to not change the core in any backwards incompatible way for a very long time, if ever, so that people can build on this until 
-JSON is no longer relevant. 
+JSON is no longer relevant. The STAC specification follows [Semantic Versioning](https://semver.org/), so once 1.0.0 is reached any breaking
+change will require the spec to go to 2.0.0. 
 
 ## Current version and branches
 
 The [master branch](https://github.com/radiantearth/stac-spec/tree/master) is the 'stable' version of the spec. It is currently version 
-**1.0.0-beta.1** of the specification. The 
+**1.0.0-beta.2** of the specification. The 
 [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch is where active development takes place, and may have inconsistent examples. 
 Whenever dev stabilizes a release is cut and we merge dev in to master. So master should be stable at any given time.
 It is possible that there may be small releases in quick succession, especially if they are nice improvements that do 
@@ -44,7 +45,7 @@ the specification takes place in the [issue tracker](https://github.com/radiante
 
 ## In this Repository
 
-This repository contains the core specifications plus examples and validation schemas and tools. Also included are a
+This repository contains the core specifications plus examples and validation schemas. Also included are a
 few documents that provide more context and plans for the evolution of the specification. Each spec folder contains a
 README explaining the layout of the folder, the main specification document, examples, and validating schemas. And 
 there is one more specification in the STAC 'family', which is

best-practices.md

@@ -5,6 +5,7 @@
 * [Field and ID formatting](#field-and-id-formatting)
 * [Field selection and Metadata Linking](#field-selection-and-metadata-linking)
 * [Datetime selection](#datetime-selection)
+* [Unlocated Items](#unlocated-items)
 * [Representing Vector Layers in STAC](#representing-vector-layers-in-stac)
 * [Common Use Cases of Additional Fields for Assets](#common-use-cases-of-additional-fields-for-assets)
 * [Static and Dynamic Catalogs](#static-and-dynamic-catalogs)
@@ -69,6 +70,45 @@ might choose to have `datetime` be the start. The key is to put in a date and ti
 the focus of STAC. If `datetime` is set to `null` then it is strongly recommended to use it in conjunction with a content extension
 that explains why it should not be set for that type of data. 
 
+## Unlocated Items
+
+Though the [GeoJSON standard](https://tools.ietf.org/html/rfc7946) allows null geometries, in STAC we strongly recommend
+that every item have a geometry, since the general expectation of someone using a SpatioTemporal Catalog is to be able to query
+all data by space and time. But there are some use cases where it can make sense to create a STAC Item before it gets
+a geometry. The most common of these is 'level 1' satellite data, where an image is downlinked and cataloged before it has 
+been geospatially located. 
+
+The recommendation for data that does not yet have a location is to follow the GeoJSON concept that it is an ['unlocated' 
+feature](https://tools.ietf.org/html/rfc7946#section-3.2). So if the catalog has data that is not located then it can follow 
+GeoJSON and set the geometry to null. Though normally required, in this case the `bbox` field should not be included.
+
+Note that this recommendation is only for cases where data does not yet have a geometry and it cannot be estimated. There
+are further details on the two most commonly requested desired use cases for setting geometry to null:
+
+### Unrectified Satellite Data
+
+Most satellite data is downlinked without information that precisely describes where it is located on earth. A satellite 
+imagery processing pipeline will always attempt to locate it, but often that process takes a number of hours, or never
+quite completes (like when it is too cloudy). It can be useful to start to populate the Item before it has a geometry. 
+In this case the recommendation is to use the 'estimated' position from the satellite, to populate at least the bounding box,
+and use the same broad bounds for the geometry (or leaving it null) until there is precise ground lock. This estimation is 
+usually done by onboard equipment, like GPS or star trackers, but can be off by kilometers or more. But it is very useful for 
+STAC users to be able to at least find approximate area in their searches. A commonly used field for communicating ground lock 
+is not yet established, but likely should be (an extension proposal would be appreciated).  If there is no way to provide an 
+estimate then the data then a null geometry with no `bbox` can be used, as described above. But the data will likely not
+show up in STAC API searches, as most will at least implicitly use a geometry. Though this section is written with 
+satellite data in mind, one can easily imagine other data types that start with a less precise geometry but have it 
+refined after processing.
+
+### Data that is not spatial
+
+The other case that often comes up is people who love STAC and want to use it to catalog everything they have, even if it is
+not spatial. This use case is not currently supported by STAC, as we are focused on data that is both temporal and spatial
+in nature. The [OGC API - Records](https://github.com/opengeospatial/ogcapi-records) is an emerging standard that likely
+will be able to handle a wider range of data to catalog than STAC. It builds on [OGC API - 
+Features](https://github.com/opengeospatial/ogcapi-features) just like [STAC API](https://github.com/radiantearth/stac-api-spec/)
+does. The [collection assets extension](extensions/collection-assets) may also provide an option for some use cases.
+
 ## Representing Vector Layers in STAC
 
 Many implementors are tempted to try to use STAC for 'everything', using it as a universal catalog of all their 'stuff'.

catalog-spec/README.md

@@ -26,10 +26,6 @@ contains a full sample catalog.
 **Schemas:** The schemas to validate the core Catalog definition are found in the *[json-schema/](json-schema/)* folder.
 The primary one is *[catalog.json](json-schema/catalog.json)*.
 
-## Schema Validation
-
-Instruction on schema validation for STAC Catalog can be found in the [validation instructions](../validation/README.md).
-
 ## Catalog Evolution 
 
 The Catalog specification is maturing, but it is still relatively early days. The core of Catalog has been defined very

catalog-spec/catalog-spec.md

@@ -36,7 +36,7 @@ also a valid STAC Catalog.
 | description     | string        | **REQUIRED.** Detailed multi-line description to fully explain the catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
 | links           | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents.       |
 
-**stac_extensions**: A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. This does *not* apply for API extensions. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file.
+**stac_extensions**: A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `single-file-stac` for the Point Cloud extension. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file.
 This list must only contain extensions that extend the Catalog itself, see the the 'Scope' column in the list of extensions.
 
 ### Link Object

catalog-spec/examples/catalog-items.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-beta.1",
+  "stac_version": "1.0.0-beta.2",
   "id": "hurricane-harvey-0831",
   "title": "Hurricane Harvey 08-31-2017",
   "description": "Planet Scenes and Composites for Hurricane Harvey on Aug 31, 2017",

catalog-spec/examples/catalog.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-beta.1",
+  "stac_version": "1.0.0-beta.2",
   "id": "NAIP",
   "description": "Catalog of NAIP Imagery",
   "links": [

catalog-spec/json-schema/catalog.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "catalog.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-beta.2/catalog-spec/json-schema/catalog.json#",
   "title": "STAC Catalog Specification",
   "description": "This object represents Catalogs in a SpatioTemporal Asset Catalog.",
   "allOf": [
@@ -22,7 +22,7 @@
         "stac_version": {
           "title": "STAC version",
           "type": "string",
-          "const": "1.0.0-beta.1"
+          "const": "1.0.0-beta.2"
         },
         "stac_extensions": {
           "title": "STAC extensions",

collection-spec/README.md

@@ -25,10 +25,6 @@ structures and fields.
 **Schemas:** The schemas to validate the STAC Collection definition are found in the 
 *[json-schema/](json-schema/)* folder. The primary one is *[collection.json](json-schema/collection.json)*.
 
-## Schema Validation
-
-Instruction on schema validation for STAC Items can be found in the [validation instructions](../validation/README.md).
-
 ## Collection Flexibility
 
 STAC Collections are defined for flexibility. They only require a handful of fields, and