Add notes about OGC APIs

best-practices.md

@@ -18,7 +18,7 @@
     - [Unrectified Satellite Data](#unrectified-satellite-data)
     - [Data that is not spatial](#data-that-is-not-spatial)
   - [Representing Vector Layers in STAC](#representing-vector-layers-in-stac)
-- **[Asset Best Practices](#asset-practices)**
+- **[Asset (and Link) Best Practices](#asset-and-link-best-practices)**
   - [Common Use Cases of Additional Fields for Assets](#common-use-cases-of-additional-fields-for-assets)
   - [Working with Media Types](#working-with-media-types)
     - [Common Media Types in STAC](#common-media-types-in-stac)
@@ -270,7 +270,7 @@ that is not possible then the appropriate way to handle Collection-level search
 [OGC API - Records](https://github.com/opengeospatial/ogcapi-records) standard, which is a 'brother' specification of STAC API. 
 Both are compliant with OGC API - Features, adding richer search capabilities to enable finding of data. 
 
-## Asset Practices
+## Asset (and Link) Bests Practices
 
 ### Common Use Cases of Additional Fields for Assets
 
@@ -305,8 +305,12 @@ providing them at the Asset level can prove to be very useful for using the data
 [Media Types](https://en.wikipedia.org/wiki/Media_type) are a key element that enables STAC to be a rich source of information for
 clients. The best practice is to use as specific of a media type as possible (so if a file is a GeoJSON then don't use a JSON
 media type), and to use [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) IANA types as much as possible.
-The following table lists types that commonly show up in STAC assets. And the [section](#formats-with-no-registered-media-type)
-past that gives recommendations on what to do if you have a format in your asset that does not have an IANA registered type.
+
+For hierarchical links (e.g. relation types `root`, `parent`, `child`, `item`) it is important that
+clients filter for the corresponding STAC media types
+(e.g. `application/json` for all relation types and/or `application/geo+json` for relation type `item`). 
+Hierarchical links with other media types (e.g. `text/html`) may be present for hierarchical links,
+especially in STAC implementations that are also implementing OGC API - Records.
 
 #### Common Media Types in STAC
 
@@ -331,15 +335,17 @@ following table lists some of the most common ones you may encounter or use.
 
 *Deprecation notice: GeoTiff previously used the media type `image/vnd.stac.geotiff` and
 Cloud Optimized GeoTiffs used `image/vnd.stac.geotiff; profile=cloud-optimized`.
-Both can still appear in old STAC implementations, but are deprecated and should be replaced. This will, unfortunately, likely shift in the future as
-[OGC sorts out the media types](https://github.com/opengeospatial/geotiff/issues/34).*
+Both can still appear in old STAC implementations, but are deprecated and should be replaced.
 
 #### Formats with no registered media type
 
+This section gives recommendations on what to do if you have a format in your links or assets
+that does not have an IANA registered type.
 Ideally every media type used is on the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml). If
-you are using a format that is not on that list we recommend you use [custom content 
-type](https://restcookbook.com/Resources/using-custom-content-types/). These typically use the `vnd.` prefix, see [RFC 6838 
-section-3.2](https://tools.ietf.org/html/rfc6838#section-3.2). Ideally the format provider will actually
+you are using a format that is not on that list we recommend you use
+[custom content type](https://restcookbook.com/Resources/using-custom-content-types/).
+These typically use the `vnd.` prefix, see [RFC 6838 section-3.2](https://tools.ietf.org/html/rfc6838#section-3.2).
+Ideally the format provider will actually
 register the media type with IANA, so that other STAC clients can find it easily. But if you are only using it internally it is 
 [acceptable to not register](https://stackoverflow.com/questions/29121241/custom-content-type-is-registering-with-iana-mandatory) 
 it. It is relatively easy to [register](https://www.iana.org/form/media-types) a `vnd` media type.

principles.md

@@ -5,37 +5,36 @@ reviewed in pull requests, approved by consensus. The goal of the principles is
 core geospatial standards.
 
 - **Creation and evolution of specs in Github**, using Open Source principles
-(please read [Producing OSS](http://producingoss.com/) if that phrase doesn't immediately make sense to you).
-The collaboration facilities of Github should be used to their full extent. All proposed improvements and
-changes should come in the form of pull requests, using code review functionality to discuss changes.
-
+  (please read [Producing OSS](http://producingoss.com/) if that phrase doesn't immediately make sense to you).
+  The collaboration facilities of Github should be used to their full extent. All proposed improvements and
+  changes should come in the form of pull requests, using code review functionality to discuss changes.
 - **JSON + REST + HTTP at the core.** JSON has won over XML, and REST over SOAP. We embrace them and
-are not considering legacy options. Forward looking protocols can be considered as extensions,
-but the default specifications should be in JSON, following best REST practices. HTTP caching and
-error codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response,
-so it should also be core. [JSON API](http://jsonapi.org/) should be used as basis of decisions where possible.
-
+  are not considering legacy options. Forward looking protocols can be considered as extensions,
+  but the default specifications should be in JSON, following best REST practices. HTTP caching and
+  error codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response,
+  so it should also be core.
+
+  [OGC APIs](https://ogcapi.ogc.org/) (especially Common, Features, and Records)
+  and/or [JSON API](https://jsonapi.org/) should be used as basis of decisions where possible.
+  There's a strong desire to be as compatible as possible with OGC API - Features and OGC API - Records.
 - **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible,
-defining one core concept and refraining from describing lots of options. Additional options can be made
-as separate specifications that build on the core. But the core specs should be small and easily understandable,
-with clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces.
-Implementors should not be forced to implement lots of options just for basic compliance - they should be
-able to pick and choose which pieces are relevant to the problems they are trying to solve.
-
+  defining one core concept and refraining from describing lots of options. Additional options can be made
+  as separate specifications that build on the core. But the core specs should be small and easily understandable,
+  with clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces.
+  Implementors should not be forced to implement lots of options just for basic compliance - they should be
+  able to pick and choose which pieces are relevant to the problems they are trying to solve.
 - **Focus on the developer**. Specifications should aim for implementability - any explanation or design choice
-should be considered with a developer audience. And specifications should be accessible to developers who do not
-have geospatial background. A developer should not need to understand 'projections' to implement a simple feature
-access service. But we should think through the spec extensions they could use in the future when their client asks
-for data in a different projection.
-
+  should be considered with a developer audience. And specifications should be accessible to developers who do not
+  have geospatial background. A developer should not need to understand 'projections' to implement a simple feature
+  access service. But we should think through the spec extensions they could use in the future when their client asks
+  for data in a different projection.
 - **Working code required.** Proposed changes should be accompanied by working code
-(ideally with a link to an online service running the code). A reference implementation should be available
-online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations
-that cover the entire specification. Extensions have their own [Extension Maturity](./extensions/README.md#extension-maturity) model.
-
+  (ideally with a link to an online service running the code). A reference implementation should be available
+  online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations
+  that cover the entire specification. Extensions have their own [Extension Maturity](./extensions/README.md#extension-maturity) model.
 - **Design for scale.** The design should work great with more data than can be imagined right now.
-Ideally implementations are built with large test data sets to validate that they will work.
-Everything should be compatible with content distribution network (CDN) caching.
+  Ideally implementations are built with large test data sets to validate that they will work.
+  Everything should be compatible with content distribution network (CDN) caching.
 
 ## Resources