Merge remote-tracking branch 'origin/dev' into remove-core-ext-schema

CHANGELOG.md

@@ -7,21 +7,29 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Changed
+
+- An empty Catalog is now allowed, removed the requirement that it must have a child or item link. ([#1115](https://github.com/radiantearth/stac-spec/issues/1115))
+
+## [v1.0.0-rc.3] - 2021-04-29
+
 ### Added
 
 - Summaries are allowed to specify JSON Schema in addition to ranges and sets of values. ([#1045](https://github.com/radiantearth/stac-spec/issues/1045))
 - Added `preview` relation type for interoperable thumbnails to best practices. ([#1090](https://github.com/radiantearth/stac-spec/issues/1090))
-- Recommendation to include both `root` and `parent` relation types when they point at the same file.
+- Recommendation to include both `root` and `parent` relation types when they point at the same file. ([#1098](https://github.com/radiantearth/stac-spec/issues/1098))
+- Overview section linking to various foundational standards. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111))
 
 ### Changed
 
 - The first extent in a Collection is always the overall extent, followed by more specific extents. ([#1064](https://github.com/radiantearth/stac-spec/issues/1064), [opengeospatial/ogcapi-features#520](https://github.com/opengeospatial/ogcapi-features/pull/520))
 - Updated examples for automatic collection creation from code and validation ([#1080](https://github.com/radiantearth/stac-spec/pull/1080))
 - Clarified that stac_extensions should also list extensions that are used in Collection summaries. ([#1077](https://github.com/radiantearth/stac-spec/issues/1077))
-- The Stats Object for Summaries has been renamed to Range Object (no functional change).
+- The Stats Object for Summaries has been renamed to Range Object (no functional change). ([#1093](https://github.com/radiantearth/stac-spec/pull/1093))
 - `changed`, `created` (common metadata) and temporal extents (collections): Timestamps must be always in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095))
 - Clarified that collection summaries do not require that all property fields are summarized. ([#1106](https://github.com/radiantearth/stac-spec/issues/1106))
 - Clarified that gsd should only be used on an asset to represent the sensor, not just different processing. ([#1105](https://github.com/radiantearth/stac-spec/pull/1105))
+- Clarified that leaving a field out is not equivalent to setting it as null. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111))
 
 ### Fixed
 
@@ -423,6 +431,7 @@ See the [milestone 0.4.0 in the issue tracker](https://github.com/radiantearth/s
 Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkamin, @hemphillda, @jeffnaus  and @fredliporace for contributing to the spec directly, and to [everyone](https://github.com/opengeospatial/wfs3hackathon/blob/master/notes/introductions.md#participants) who participated in the [Ft Collins sprint](https://github.com/radiantearth/community-sprints/tree/master/03072018-ft-collins-co) and brought great ideas.
 
 [Unreleased]: <https://github.com/radiantearth/stac-spec/compare/master...dev>
+[v1.0.0-rc.3]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-rc.2..v1.0.0-rc.3>
 [v1.0.0-rc.2]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-rc.1..v1.0.0-rc.2>
 [v1.0.0-rc.1]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-beta.2..v1.0.0-rc.1>
 [v1.0.0-beta.2]: <https://github.com/radiantearth/stac-spec/compare/v1.0.0-beta.1..v1.0.0-beta.2>

best-practices.md

@@ -9,7 +9,8 @@
     - [Deploying STAC Browser](#deploying-stac-browser)
   - [Requester Pays](#requester-pays)
 - **[Item Best Practices](#item-practices)**
-  - [Field and ID formatting](#field-and-id-formatting)
+  - [Field and ID formatting](#item-ids)
+  - [Searchable Identifiers](#searchable-identifiers)
   - [Field selection and Metadata Linking](#field-selection-and-metadata-linking)
   - [Datetime selection](#datetime-selection)
   - [Unlocated Items](#unlocated-items)
@@ -147,19 +148,22 @@ For data providers using STAC with requester pays buckets, there are two main re
 
 ## Item Practices
 
-### Field and ID formatting
+### Item IDs
 
 When defining one's STAC properties and fields there are many choices to make on how to name various aspects of one's
 data. One of the key properties is the ID. The specification is quite flexible on ID's, primarily so that existing
 providers can easily use their same ID when they translate their data into STAC - they just need to be sure it is globally
-unique, so may need a prefix. But the use of URI reserved characters such as `:` or `/` is discouraged since this will 
+unique, so may need a prefix. But the use of URI or file path reserved characters such as `:` or `/` is discouraged since this will 
 result in [percented encoded](https://tools.ietf.org/html/rfc3986#section-2) [STAC API](https://github.com/radiantearth/stac-api-spec) 
-endpoints. This isn't a blocker, it just makes the ID's served through API's a bit less parsable. 
+endpoints and it prevents the use of IDs as file names as recommended in the [catalog layout](#catalog-layout) best practices.
 
-When defining unique fields for search, like constellation or platform, it is recommended that 
-the value consist of only lowercase characters, numbers, `_`, and `-`. Examples include `sentinel-1a` (Sentinel-1), 
-`landsat-8` (Landsat-8) and `envisat` (Envisat). This is to provide consistency for search across Collections, so that
-people can just search for 'landsat-8', instead of thinking through all the ways providers might have chosen to name it.
+### Searchable Identifiers
+
+When coming up with values for fields that contain searchable identifiers of some sort, like `constellation` or `platform`,
+it is recommended that the identifiers consist of only lowercase characters, numbers, `_`, and `-`.
+Examples include `sentinel-1a` (Sentinel-1), `landsat-8` (Landsat-8) and `envisat` (Envisat).
+This is to provide consistency for search across Collections, so that people can just search for `landsat-8`,
+instead of thinking through all the ways providers might have chosen to name it.
 
 ### Field selection and Metadata Linking
 

catalog-spec/catalog-spec.md

@@ -94,7 +94,8 @@ The following types are commonly used as `rel` types in the Link Object of a STA
 | child   | URL to a child STAC entity (Catalog or Collection). |
 | item    | URL to a STAC Item. |
 
-**Note:** A link to at least one `item` or `child` (Catalog or Collection) is **REQUIRED**.
+**Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are
+allowed if there is an intent to populate it or its children were removed.
 
 There are additional `rel` types in the [Using Relation Types](../best-practices.md#using-relation-types) best practice, but as 
 they are more typically used in Collections, as Catalogs tend to just be used to structure STAC organization, so tend to just use

catalog-spec/json-schema/catalog-core.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/catalog-spec/json-schema/catalog-core.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/catalog-spec/json-schema/catalog-core.json#",
   "title": "Common STAC Catalog + Collection Fields",
   "description": "This object represents the common fields shared by Catalogs and Collections",
   "allOf": [
@@ -22,7 +22,7 @@
         "stac_version": {
           "title": "STAC version",
           "type": "string",
-          "const": "1.0.0-rc.2"
+          "const": "1.0.0-rc.3"
         },
         "stac_extensions": {
           "title": "STAC extensions",

catalog-spec/json-schema/catalog.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/catalog-spec/json-schema/catalog.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/catalog-spec/json-schema/catalog.json#",
   "title": "STAC Catalog Specification",
   "description": "This object represents Catalogs in a SpatioTemporal Asset Catalog.",
   "allOf": [

collection-spec/json-schema/collection.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/collection-spec/json-schema/collection.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/collection-spec/json-schema/collection.json#",
   "title": "STAC Collection Specification",
   "description": "This object represents Collections in a SpatioTemporal Asset Catalog.",
   "allOf": [

examples/catalog.json

@@ -1,7 +1,7 @@
 {
   "id": "examples",
   "type": "Catalog",
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "description": "This catalog is a simple demonstration of an example catalog that is used to organize a hierarchy of collections and their items.",
   "links": [
     {
@@ -35,7 +35,7 @@
     },
     {
       "rel": "self",
-      "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.2/examples/catalog.json",
+      "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.3/examples/catalog.json",
       "type": "application/json"
     }
   ]

examples/collection-only/collection-with-schemas.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "stac_extensions": [
     "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
     "https://stac-extensions.github.io/sat/v1.0.0/schema.json",

examples/collection-only/collection.json

@@ -1,6 +1,6 @@
 {
   "type": "Collection",
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "stac_extensions": [
     "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
     "https://stac-extensions.github.io/projection/v1.0.0/schema.json",

examples/collection.json

@@ -3,9 +3,10 @@
   "type": "Collection",
   "stac_extensions": [
     "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
+    "https://stac-extensions.github.io/projection/v1.0.0/schema.json",
     "https://stac-extensions.github.io/view/v1.0.0/schema.json"
   ],
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "description": "A simple collection demonstrating core catalog fields with links to a couple of items",
   "title": "Simple Example Collection",
   "providers": [
@@ -103,7 +104,7 @@
     },
     {
       "rel": "self",
-      "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.2/examples/collection.json",
+      "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.3/examples/collection.json",
       "type": "application/json"
     }
   ]

examples/collectionless-item.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "stac_extensions": [
     "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
     "https://stac-extensions.github.io/view/v1.0.0/schema.json"

examples/core-item.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "stac_extensions": [],
   "type": "Feature",
   "id": "20201211_223832_CS2",

examples/extended-item.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "stac_extensions": [
     "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
     "https://stac-extensions.github.io/projection/v1.0.0/schema.json",

examples/extensions-collection/collection.json

@@ -1,7 +1,7 @@
 {
   "id": "extensions-collection",
   "type": "Collection",
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "description": "A heterogenous collection containing deeper examples of various extensions",
   "links": [
     {

examples/extensions-collection/proj-example/proj-example.json

@@ -1,6 +1,6 @@
 {
   "type": "Feature",
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "id": "proj-example",
   "properties": {
     "datetime": "2018-10-01T01:08:32.033000Z",

examples/simple-item.json

@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-rc.2",
+  "stac_version": "1.0.0-rc.3",
   "stac_extensions": [],
   "type": "Feature",
   "id": "20201211_223832_CS2",

item-spec/item-spec.md

@@ -90,7 +90,7 @@ As most geospatial assets are already uniquely defined by some
 identification scheme from the data provider it is recommended to simply use that ID.
 Data providers are advised to include sufficient information to make their IDs globally unique,
 including things like unique satellite IDs.
-See the [id section of best practices](../best-practices.md#field-and-id-formatting) for additional recommendations.
+See the [id section of best practices](../best-practices.md#item-ids) for additional recommendations.
 
 #### assets
 

item-spec/json-schema/basics.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/basics.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/item-spec/json-schema/basics.json#",
   "title": "Basic Descriptive Fields",
   "type": "object",
   "properties": {

item-spec/json-schema/datetime.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/datetime.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/item-spec/json-schema/datetime.json#",
   "title": "Date and Time Fields",
   "type": "object",
   "dependencies": {

item-spec/json-schema/instrument.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/instrument.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/item-spec/json-schema/instrument.json#",
   "title": "Instrument Fields",
   "type": "object",
   "properties": {

item-spec/json-schema/item.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/item.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/item-spec/json-schema/item.json#",
   "title": "STAC Item",
   "type": "object",
   "description": "This object represents the metadata for an item in a SpatioTemporal Asset Catalog.",
@@ -93,7 +93,7 @@
             "stac_version": {
               "title": "STAC version",
               "type": "string",
-              "const": "1.0.0-rc.2"
+              "const": "1.0.0-rc.3"
             },
             "stac_extensions": {
               "title": "STAC extensions",

item-spec/json-schema/licensing.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/licensing.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/item-spec/json-schema/licensing.json#",
   "title": "Licensing Fields",
   "type": "object",
   "properties": {

item-spec/json-schema/provider.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/provider.json#",
+  "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/item-spec/json-schema/provider.json#",
   "title": "Provider Fields",
   "type": "object",
   "properties": {

overview.md

@@ -3,14 +3,37 @@
 There are three component specifications that together make up the core SpatioTemporal Asset Catalog specification.
 Each can be used alone, but they work best in concert with one another. The [STAC API specification](https://github.com/radiantearth/stac-api-spec) 
 builds on top of that core, but is out of scope for this overview. An [Item](item-spec/item-spec.md) represents a 
-single [spatiotemporal asset](#what-is-a-spatiotemporal-asset) as GeoJSON so it can be searched. 
+single [spatiotemporal asset](#what-is-a-spatiotemporal-asset) as [GeoJSON](https://geojson.org/) so it can be searched. 
 The [Catalog](catalog-spec/catalog-spec.md) specification provides structural elements, to group Items
 and [Collections](collection-spec/collection-spec.md). Collections *are* catalogs, that add more required metadata and 
 describe a group of related Items. For more on the differences see the [section below](#catalogs-vs-collections).
 
 A [UML diagram](https://en.wikipedia.org/wiki/Unified_Modeling_Language) of the [STAC model](STAC-UML.pdf) is also 
 provided to help with navigating the specification. 
 
+## Foundations
+
+STAC is built on top of many great standards and practices. Every part of STAC is 
+[JSON](https://www.json.org/json-en.html), and [GeoJSON](https://geojson.org/) provides the core geometry fields 
+and [features](https://en.wikipedia.org/wiki/Simple_Features) definition. All fields are described in the 
+specifications, and the acceptable values are defined with [JSON Schema](https://json-schema.org/). The released
+JSON Schemas provide the core testing definitions, and are used in an array of validation tools. We also rely
+on [RFC 8288 (Web Linking)](https://tools.ietf.org/rfc/rfc8288.txt) to express relationships between resources,
+and IANA [Media Types](https://en.wikipedia.org/wiki/Media_type) to describe file formats and format contents.
+The [OGC API - Features](https://ogcapi.ogc.org/features/) standard is a final core building block. The STAC
+Collection extends the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_)
+JSON defined in OGC API - Features (and the full API definition is the foundation for the STAC API specification).
+
+The STAC specifications are written to be understandable without needing a full background in these. But if you 
+want to get deep into STAC tool implementation and are not familiar with any of the standards mentioned above it is 
+recommended to read up on them. STAC development is guided by set of core philosophical tenets, like 
+building small reusable parts that are loosely coupled, focusing on developers, and more - see our the 
+[principles](principles.md) document to learn more.
+
+*Note: Setting a field in JSON to `null` is not equivalent to a field not appearing in STAC, as JSON Schema tools treat
+them differently. STAC defines `null` explicitly for some fields, where it has a particular meaning. So `null` should 
+not be used unless the STAC spec defines its use - instead the field should be left out entirely.* 
+
 ## Item Overview
 
 Fundamental to any SpatioTemporal Asset Catalog, an [Item](item-spec/item-spec.md) object represents a unit of

package.json

@@ -1,6 +1,6 @@
 {
   "name": "stac-spec",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.3",
   "description": "STAC spec helpers to check the spec.",
   "repository": "https://github.com/radiantearth/stac-spec",
   "license": "Apache-2.0",